# Understanding the Evidence → Finding → Path Chain in reverse-skill

> Learn the Evidence Finding Path chain in reverse-skill a three-stage data model structuring security workflows into immutable observations validated conclusions and actionable sequences.

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

---

**The Evidence → Finding → Path chain is the mandatory three-stage data model in the reverse-skill repository that structures every security and reverse-engineering workflow into immutable observations, validated conclusions, and actionable sequences.**

This architectural pattern enforces **reproducibility** and **auditability** across forensic investigations, penetration tests, and CTF challenges. According to the `zhaoxuya520/reverse-skill` source code, the chain lives in [`skills/ops/evidence-finding-path.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/evidence-finding-path.md) and requires analysts to progress through three distinct layers before generating final reports.

## The Three-Stage Data Model

The reverse-skill framework divides every investigation into three immutable asset types stored as markdown files in `work/<case>/`.

### Evidence: Immutable Observations

**Evidence** represents raw, tamper-evident records of what was observed. Stored as `E-{nnn}.md` files under `work/<case>/evidence/`, each evidence asset must include mandatory fields that guarantee immutability and reproducibility.

Key fields include:
- `content_hash` – Cryptographic hash ensuring integrity
- `observed_at` – ISO 8601 timestamp
- `source_ref` – Pointer to original log or artifact
- `repro_command` – Exact command to regenerate the observation

As specified in [`skills/ops/evidence-finding-path.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/evidence-finding-path.md), evidence files are append-only. The `supersedes` field allows chaining corrections without invalidating previous hashes.

### Finding: Analyst Conclusions

**Finding** assets (`F-{nnn}.md`) represent analyst-level interpretations derived from one or more evidence files. Each finding must reference at least one evidence ID via the `evidence_ids` array.

Critical validation rules enforced by the framework:
- `status=validated` requires `confidence` ≠ `low` unless `residual_risks` is explicitly documented
- Must specify `severity` (low/medium/high/critical) and `category` (vuln/malware/config)
- `location` and `impact` fields provide spatial and business context

The finding layer acts as the **interpretation boundary** between raw data and human analysis.

### Path: Actionable Sequences

**Path** assets (`P-{nnn}.md`) connect findings into ordered sequences that achieve higher-level goals. The `path_type` field adapts to domain requirements (`attack`, `callflow`, or `solve`).

Each step in the `steps` array must reference:
- `evidence` – The supporting observation
- `finding` – The derived conclusion
- `action` – The narrative or operational instruction

Paths enable **attack chain reconstruction**, **call-flow documentation**, and **CTF solve walkthroughs** while maintaining full traceability back to original evidence.

## Architectural Flow

The reverse-skill implementation enforces a five-phase workflow:

1. **Evidence Creation** – Analysts or automated scripts write `E-{nnn}.md` files using CLI helpers like `skills/scripts/append-evidence.ps1`. This guarantees immutability through hashes and timestamps.

2. **Finding Composition** – Validation logic in [`skills/case-review/scripts/review_case.py`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/case-review/scripts/review_case.py) ensures every finding references sufficient evidence before `status` can transition to `validated`.

3. **Path Assembly** – `P-{nnn}.md` files string together steps, with the `docs-generator` module consuming these assets to produce final reports.

4. **Verification & Reporting** – The generator mandates inclusion of Scope summaries, Evidence tables, Findings lists, and at least one Path, as 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).

5. **Auditability** – The read-only case-review script verifies hash integrity and cross-references work items, enforcing that no finding exists without supporting evidence.

## Implementation Details and File Structure

The reverse-skill repository organizes validation logic and templates across four key locations:

| File | Purpose |
|------|---------|
| [`skills/ops/evidence-finding-path.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/evidence-finding-path.md) | Authoritative schema specification for all three stages |
| [`skills/docs-generator/references/security-report-templates.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/docs-generator/references/security-report-templates.md) | Report templates enforcing chain inclusion |
| [`skills/case-review/scripts/review_case.py`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/case-review/scripts/review_case.py) | Python validation engine for hash verification and sufficiency checks |
| `skills/scripts/append-evidence.ps1` | PowerShell CLI for creating Evidence markdown files |

The naming convention (`E-`, `F-`, `P-` prefixes with zero-padded numeric identifiers) ensures lexical sorting and unambiguous referencing across the evidence chain.

## Practical Code Examples

The following markdown snippets demonstrate the exact schema required for each stage. These can be generated automatically using the CLI helpers or written manually.

### Evidence File Example ([`E-001.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/E-001.md))

```markdown

### E-001

- title: Suspicious PowerShell command execution
- observed_at: 2026-08-24T14:32:00Z
- source_type: command
- source_ref: work/sample/commands.log
- content_hash: 3a7bd3e5f9c2c0e8b9d9a6c4a1b1e2f3d4c5e6f7a8b9c0d1e2f3a4b5c6d7e8f9
- artifact_path: work/sample/powershell-output.txt
- repro_command: |
    powershell -NoProfile -ExecutionPolicy Bypass -File script.ps1
- raw_excerpt: |
    Get-Process | Where-Object {$_.CPU -gt 1000}
- linked_workitem: WI-001
- supersedes: none

```

### Finding File Example ([`F-001.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/F-001.md))

```markdown

### F-001

- title: High‑CPU PowerShell process indicates possible crypto‑miner
- severity: high
- category: vuln
- status: validated
- evidence_ids: [E-001]
- location: C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe
- impact: Unauthorized CPU consumption and potential data exfiltration
- confidence: high
- repro_steps:
  1. Run the command recorded in E-001
  2. Observe CPU usage spike
- remediation: Investigate scheduled tasks and disable the suspicious script
- optional_attack: T1496

```

### Path File Example ([`P-001.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/P-001.md))

```markdown

### P-001

- title: Crypto‑miner deployment chain
- path_type: attack
- start: Initial user login
- goal: Persistent cryptomining on the host
- steps:
  1. action: Execute PowerShell → evidence: E-001 → finding: F-001
  2. action: Deploy miner binary → evidence: E-005 → finding: F-003
  3. action: Establish persistence → evidence: E-009 → finding: F-007
- residual_risks: None

```

Create these assets programmatically using:

```powershell
powershell -File skills/scripts/append-evidence.ps1 `
  -CaseRoot work/<case> `
  -Id E-001 `
  -Title "Suspicious PowerShell command execution" `
  -ReproCommand "powershell -NoProfile..." `
  -Severity high `
  -Status observed

```

## Validation and Auditability

The [`skills/case-review/scripts/review_case.py`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/case-review/scripts/review_case.py) script implements **read-only audit logic** that enforces the Evidence → Finding → Path contract. It performs three critical checks:

- **Hash Integrity** – Verifies `content_hash` values against current file contents
- **Reference Validation** – Ensures every `evidence_ids` entry points to an existing `E-` file
- **Sufficiency Rules** – Confirms high-severity findings do not rely solely on low-confidence evidence without documented residual risks

This validation layer prevents "silent" validation states where findings appear authoritative without proper evidentiary backing.

## Summary

- The **Evidence → Finding → Path** chain structures all reverse-skill investigations into three immutable, linked asset types.
- **Evidence** (`E-*.md`) provides tamper-evident raw observations with mandatory hashes and reproduction commands.
- **Findings** (`F-*.md`) require at least one evidence reference and enforce confidence thresholds via [`review_case.py`](https://github.com/zhaoxuya520/reverse-skill/blob/main/review_case.py).
- **Paths** (`P-*.md`) sequence findings into attack chains, call flows, or CTF solutions while maintaining full traceability.
- The `docs-generator` module mandates inclusion of all three stages in final security reports.
- CLI helpers in `skills/scripts/` and validation logic in `skills/case-review/` automate creation and verification of the chain.

## Frequently Asked Questions

### What happens if a Finding references Evidence that has been superseded?

The `supersedes` field in Evidence files creates a forward chain without invalidating historical hashes. When [`review_case.py`](https://github.com/zhaoxuya520/reverse-skill/blob/main/review_case.py) audits a case, it checks the `supersedes` lineage to ensure analysts review the correct evidence version. Findings should reference the most current non-superseded evidence ID unless documenting historical context.

### How does reverse-skill enforce the Evidence → Finding → Path relationship?

Validation occurs at two levels. First, the markdown schema in [`skills/ops/evidence-finding-path.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/evidence-finding-path.md) defines mandatory fields. Second, [`skills/case-review/scripts/review_case.py`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/case-review/scripts/review_case.py) performs runtime verification, checking that every `evidence_ids` array contains valid references and that high-severity findings possess sufficient evidentiary support before `status` can be set to `validated`.

### Can Path files reference multiple Findings from the same Evidence?

Yes. The `steps` array in Path files supports many-to-many relationships. A single piece of evidence can support multiple findings (e.g., one log entry revealing both vulnerability and misconfiguration), and a single path can weave together findings derived from overlapping evidence sets. Each step explicitly links one evidence ID to one finding ID.

### What is the difference between path_type `attack` and `callflow`?

The `path_type` field adapts the chain to domain-specific narratives. `attack` chains map adversary TTPs (Tactics, Techniques, and Procedures) for penetration testing reports. `callflow` documents reverse-engineered function call sequences. `solve` paths structure CTF write-ups. The `docs-generator` module applies different templates based on this type while maintaining the underlying Evidence → Finding → Path structure.