# Understanding the Evidence-Finding-Path Workflow in reverse-skill ops Contracts

> Master the evidence-finding-path workflow for reproducible reverse-engineering operations. Structure security cases with immutable Evidence, analyst Findings, and traceable Paths in ops contracts.

- Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill)
- Tags: internals
- Published: 2026-08-08

---

**The evidence-finding-path workflow is a three-stage contract framework that structures security cases into immutable Evidence, analyst-level Findings, and traceable Paths to ensure reproducible reverse-engineering operations.**

The `zhaoxuya520/reverse-skill` repository defines a rigorous **evidence-finding-path workflow** within its `ops` contracts to standardize how security researchers document and validate reverse-engineering cases. This contract-driven approach creates an immutable chain of custody from initial observation through final reporting, ensuring every analysis remains reproducible and auditable. The framework is implemented across several Markdown contract files and automation scripts that enforce data integrity at each stage.

## The Three Stages of the Evidence-Finding-Path Workflow

The `ops` contracts in [`skills/ops/evidence-finding-path.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/evidence-finding-path.md) define a strict progression from raw data to actionable intelligence through three distinct stages.

### Stage 1: Evidence (Immutable Observations)

The **Evidence** stage captures raw, immutable observations of artifacts, commands, screenshots, and system states. Each evidence record is stored as a Markdown file under `work/<case>/evidence/E-*.md` and must include fields such as `title`, `observed_at`, `source_type`, `source_ref`, `content_hash`, `artifact_path`, `repro_command`, `raw_excerpt`, `linked_workitem`, and `supersedes`.

According to [`skills/ops/evidence-finding-path.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/evidence-finding-path.md) (lines 6–24), the Evidence contract requires a `content_hash` for integrity verification and a `repro_command` to ensure any analyst can recreate the observation. The `source_type` field categorizes whether the evidence derives from commands, files, or network captures.

### Stage 2: Finding (Analyst Conclusions)

The **Finding** stage represents analyst-level conclusions derived from one or more Evidence records. Defined in [`skills/ops/evidence-finding-path.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/evidence-finding-path.md) (lines 43–60), each Finding must reference at least one `evidence_ids` entry and include fields such as `severity`, `category`, `status`, `location`, `impact`, `confidence`, `repro_steps`, `remediation`, and `optional_attack`.

The contract enforces that `evidence_ids` cannot be empty, and a `status: validated` Finding cannot have low confidence unless `residual_risks` are explicitly documented. This ensures that all conclusions remain traceable to concrete observations rather than speculation.

### Stage 3: Path (Attack Chains and Solutions)

The **Path** stage constructs an ordered sequence connecting Evidence to Findings and ultimate operational goals. As specified in [`skills/ops/evidence-finding-path.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/evidence-finding-path.md) (lines 64–84), Paths include `path_type` (attack, call-flow, or CTF solution), `start` and `goal` descriptors, and a `steps` array where each step references specific Evidence and Finding IDs.

Each step uses the syntax `action: — evidence: E-xxx — finding: F-xxx | none`, enabling automated pipelines to render traceable narratives that show exactly how raw observations lead to security conclusions.

## Workflow Enforcement Mechanisms

The `ops` contracts implement six distinct enforcement points to maintain chain integrity throughout the case lifecycle.

### Evidence Creation via CLI Helpers

Analysts create Evidence records using the `append-evidence.ps1` PowerShell helper located at `skills/scripts/append-evidence.ps1`. This script validates input parameters and generates properly formatted Markdown files with correct field ordering and syntax.

### Validation and Linking Constraints

Before a Finding can be marked as validated, the contract enforces two critical constraints: the `evidence_ids` array must contain at least one valid Evidence reference, and low-confidence findings must explicitly document residual risks. These rules prevent untested assertions from entering the final report.

### Automated Verification with review_case.py

Before case hand-off, reviewers execute [`skills/case-review/scripts/review_case.py`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/case-review/scripts/review_case.py) to verify:

- Scope fields are present and complete
- All Evidence records have matching `content_hash` values
- Work-item and timeline references remain consistent
- Cross-references between Findings, Paths, and Evidence are valid

### Report Generation Integration

The `docs-generator` module consumes the complete Evidence-Finding-Path chain and injects it into security report templates defined in [`skills/docs-generator/references/security-report-templates.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/docs-generator/references/security-report-templates.md). The contract mandates that at least one Path must appear in the final deliverable to ensure traceability.

### Field-Journal Anonymization

When cases are archived to the anonymized field-journal, the contract extracts up to three key Evidence IDs, one core Finding, and a one-sentence Path summary. This preserves actionable intelligence while removing identifying information, as detailed in the field-journal hooks section of the contract.

## Practical Implementation Examples

The following examples demonstrate how to create and link Evidence, Findings, and Paths according to the `ops` contract specifications.

Creating a new Evidence entry using the PowerShell helper:

```powershell
powershell -File skills/scripts/append-evidence.ps1 -CaseRoot work/MyCase `
  -Id E-001 -Title "Suspicious DLL loaded" -ReproCommand "ldd /tmp/malware.so" `
  -Severity info -Status observed

```

This generates a Markdown file with the following structure:

```markdown

### E-001

- title: Suspicious DLL loaded
- observed_at: 2026-08-08T14:32:00Z
- source_type: command
- source_ref: work/MyCase/evidence/E-001.md
- content_hash: n/a
- artifact_path: n/a
- repro_command: |
    ldd /tmp/malware.so
- raw_excerpt: |
    libcrypto.so.1.1 => /usr/lib/libcrypto.so.1.1 (0x7f...)
- linked_workitem: WI-010
- supersedes: none

```

Linking Evidence to a Finding requires referencing the Evidence ID in the `evidence_ids` field:

```markdown

### F-001

- title: Remote Code Execution via libcrypto
- severity: high
- category: vuln
- status: validated
- evidence_ids: [E-001]
- location: /tmp/malware.so
- impact: Attacker can execute arbitrary code
- confidence: high
- repro_steps:
  1. Run the command shown in E-001
  2. Observe crash
- remediation: Update libcrypto to version ≥1.1.1
- optional_attack: T1203

```

Constructing a Path that traces the exploit chain:

```markdown

### P-001

- title: Exploit Chain for CVE‑2026‑XYZ
- path_type: attack
- start: Initial foothold on target host
- goal: Execute attacker‑controlled payload
- steps:
  1. action: Load libcrypto — evidence: E-001 — finding: F-001
  2. action: Trigger overflow — evidence: none — finding: none
- residual_risks: None

```

## Key Contract Files and Automation Scripts

The evidence-finding-path workflow relies on specific files within the `zhaoxuya520/reverse-skill` repository:

- **[`skills/ops/evidence-finding-path.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/evidence-finding-path.md)** — Defines the complete E-F-P contract, including field specifications, CLI helper documentation, and verification procedures.
- **[`skills/ops/IDENTITY.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/IDENTITY.md)** — Explains the operational philosophy and how the evidence chain integrates with the broader reverse-skill identity framework.
- **`skills/scripts/append-evidence.ps1`** — PowerShell automation script that generates properly formatted Evidence Markdown files with consistent field ordering.
- **[`skills/case-review/scripts/review_case.py`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/case-review/scripts/review_case.py)** — Python verification script that validates the integrity of the entire Evidence-Finding-Path chain before case completion.
- **[`skills/docs-generator/references/security-report-templates.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/docs-generator/references/security-report-templates.md)** — Specifies required report sections, including mandatory Path inclusion for traceability.

## Summary

- The **evidence-finding-path workflow** divides reverse-engineering cases into three immutable stages: Evidence (raw observations), Finding (analyst conclusions), and Path (traceable chains).
- Each stage is governed by strict contracts defined in [`skills/ops/evidence-finding-path.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/evidence-finding-path.md) that enforce field completeness and cross-referencing requirements.
- **Evidence** records require `content_hash` and `repro_command` fields to ensure integrity and reproducibility.
- **Findings** must link to at least one Evidence ID via `evidence_ids`, and validated findings cannot have low confidence without documented residual risks.
- **Paths** connect Evidence and Findings into ordered steps using a standardized syntax that supports automated narrative generation.
- The workflow is enforced through CLI helpers (`append-evidence.ps1`), automated verification ([`review_case.py`](https://github.com/zhaoxuya520/reverse-skill/blob/main/review_case.py)), and mandatory report generation hooks.

## Frequently Asked Questions

### What is the primary purpose of the evidence-finding-path workflow?

The workflow establishes a **contract-driven evidence chain** that guarantees reproducibility, traceability, and consistent reporting across all reverse-skill operations. By separating raw observations from analyst conclusions and connecting them through structured Paths, the framework ensures that every security claim can be traced back to immutable evidence and reproduced by independent reviewers.

### How does the contract enforce data integrity between Evidence and Findings?

The contract mandates that every Finding must include a non-empty `evidence_ids` array referencing specific Evidence records. Additionally, the [`review_case.py`](https://github.com/zhaoxuya520/reverse-skill/blob/main/review_case.py) script verifies that `content_hash` values match between stored artifacts and metadata, and that all cross-references resolve correctly before case hand-off occurs.

### Can a Path exist without referencing specific Evidence or Findings?

Yes, individual steps within a Path may use `none` for the evidence or finding fields when documenting inferred actions or hypothetical steps. However, the contract requires that at least one Path appear in the final security report, and the overall case must maintain a valid chain from Evidence through Finding to support validated conclusions.

### What tools automate the creation and validation of workflow components?

Analysts use **`append-evidence.ps1`** to create properly formatted Evidence records through a command-line interface. For validation, the **[`review_case.py`](https://github.com/zhaoxuya520/reverse-skill/blob/main/review_case.py)** script automates integrity checks across the entire Evidence-Finding-Path chain, verifying hash matches, reference consistency, and contract compliance before generating final reports.