# How Reverse-Skill Structures Evidence, Findings, and Paths: A Three-Layer Chain Explained

> Discover how Reverse-Skill builds a robust Evidence → Finding → Path chain. Learn how immutable observations link to security conclusions and actionable sequences for full traceability and auditability.

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

---

**Reverse-Skill enforces a strict Evidence → Finding → Path chain where immutable observations link to security conclusions and finally to actionable attack or solve sequences, ensuring full traceability and auditability.**

The `zhaoxuya520/reverse-skill` repository implements a markdown-based contract system that standardizes how reverse-engineering and security investigations are documented. This three-layer architecture, defined in [`skills/ops/evidence-finding-path.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/evidence-finding-path.md) and governed by [`skills/ops/analysis-decision-framework.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/analysis-decision-framework.md), creates an unbreakable audit trail from raw artefacts to final reports.

## The Three-Layer Architecture

Reverse-Skill organizes every investigative step into a hierarchical chain. **Evidence** files capture raw, immutable observations. **Finding** files derive security conclusions from that evidence. **Path** files sequence these findings into coherent attack flows or solution sequences. This structure ensures that every claim in a final report traces back to reproducible data points.

## Evidence Layer: Immutable Observations

Evidence records represent the atomic unit of investigation. Each piece of raw data lives in its own Markdown file named `E-{nnn}.md` under the `work/<case>/evidence/` directory. According to the schema defined in [`skills/ops/evidence-finding-path.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/evidence-finding-path.md) (lines 10-24), every Evidence file must include:

- **title**, **observed_at**, **source_type**, and **source_ref**
- **content_hash** (SHA-256 for file artefacts) and **artifact_path** (relative location)
- **repro_command** (exact command to reproduce the artefact)
- **raw_excerpt** (sanitised snippet of the observation)

The `skills/scripts/append-evidence.ps1` CLI helper automates creation of these files (lines 28-33). Every Finding must reference at least one Evidence record (line 26), ensuring no conclusion exists without supporting data.

### Creating Evidence Records

Use the PowerShell helper to generate properly formatted Evidence files:

```powershell
powershell -File skills/scripts/append-evidence.ps1 `
  -CaseRoot work/my-case `
  -Id E-001 -Title "Checksec output" `
  -ReproCommand "checksec --format=json binary" `
  -Severity info -Status observed

```

This generates a file like [`work/my-case/evidence/E-001.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/work/my-case/evidence/E-001.md) with the following structure:

```markdown

### E-001

- title: Checksec output
- observed_at: 2026-08-24T10:12Z
- source_type: command
- source_ref: checksec
- content_hash: a3f5c9…
- artifact_path: evidence/checksec-output.json
- repro_command: |
    checksec --format=json binary
- raw_excerpt: |
    {"stack_canary":true,"pie":false,…}
- linked_workitem: WI-01
- supersedes: none

```

## Finding Layer: Security Conclusions

Findings represent analytical conclusions drawn from Evidence. Stored as `F-{nnn}.md` files, they bridge raw observations with security impact. The mandatory schema (lines 45-60 in the framework) requires:

- **title**, **severity**, **category**, and **status**
- **evidence_ids** – a non-empty list of linked Evidence IDs (line 62)
- **location**, **impact**, **confidence**, **remediation**
- **optional_attack** (ATT&CK ID for threat mapping)

The **status** field drives workflow rigor. Only when a Finding reaches **validated** status does the framework enforce that it must be supported by **≥2 independent** Evidence items (see the “Validated sufficiency” table, lines 25-29). This prevents single-point-of-failure conclusions in critical assessments.

### Linking Evidence in Findings

A validated Finding references multiple Evidence items:

```markdown

### F-001

- title: Stack canary disabled
- severity: high
- category: misconfig
- status: validated
- evidence_ids: [E-001, E-002]
- location: binary:0x40123
- impact: Allows buffer‑overflow exploits
- confidence: high
- remediation: Re‑enable stack canary via compiler flags
- optional_attack: T1068

```

## Path Layer: Attack and Solve Sequences

Paths describe the ordered sequence of actions connecting an initial state to a goal. Each Path file (`P-{nnn}.md`) documents either an **attack**, **callflow**, or **solve** sequence. According to [`skills/ops/evidence-finding-path.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/evidence-finding-path.md) (lines 75-82), each step in a Path must tie a specific Evidence record to a Finding.

Required Path fields include:

- **title** and **path_type** (attack | callflow | solve)
- **start** (initial state) and **goal** (desired end state)
- **steps** – ordered list mapping Evidence to Findings

The **docs-generator** enforces the presence of complete Evidence → Finding → Path chains in every generated security report (lines 90-96). When a step claims privilege escalation or data acquisition, it must reference validated Evidence.

### Describing Investigation Paths

Path files map the investigative journey:

```markdown

### P-001

- title: Exploit preparation
- path_type: attack
- start: Unprivileged shell
- goal: Root privilege
- steps:
  1. action: — evidence: E-001 — finding: F-001 | none
  2. action: — evidence: E-003 — finding: F-004 | none
- residual_risks: None

```

## Integration and Governance

The `docs-generator` pipeline validates that every report contains the full three-layer chain (lines 90-95). Downstream, the **field-journal** hook extracts concise summaries for quick reference (lines 100-106).

The [`skills/ops/analysis-decision-framework.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/analysis-decision-framework.md) governs how evidence quality influences finding promotion (see R4* in lines 45-53) and defines special Evidence IDs for edge cases (lines 17-20). Together, these contracts guarantee that reverse-skill investigations remain reproducible, auditable, and defensible.

## Summary

- **Reverse-Skill** structures investigations as a strict **Evidence → Finding → Path** chain documented in markdown files.
- **Evidence** files (`E-{nnn}.md`) store immutable observations with SHA-256 hashes and reproduction commands in `work/<case>/evidence/`.
- **Findings** (`F-{nnn}.md`) require at least one Evidence reference, with **validated** status demanding **≥2 independent** Evidence items.
- **Paths** (`P-{nnn}.md`) sequence steps into attack, callflow, or solve sequences, linking specific Evidence IDs to Findings.
- The **docs-generator** and **analysis-decision-framework** enforce these contracts, ensuring traceability from raw data to final security reports.

## Frequently Asked Questions

### What is the minimum number of Evidence items required for a Finding?

Every Finding must reference **at least one** Evidence item in its `evidence_ids` field. However, when a Finding reaches **validated** status, the `analysis-decision-framework` enforces a stricter rule requiring **two or more independent Evidence items** (lines 25-29). This ensures high-confidence conclusions rely on corroborating data sources.

### How does Reverse-Skill ensure Evidence immutability?

Evidence files include a **content_hash** field containing a SHA-256 checksum of the artifact and a **repro_command** field with the exact command used to generate the observation. Stored in dedicated `work/<case>/evidence/` directories with strict naming conventions (`E-{nnn}.md`), these records serve as immutable reference points that cannot be altered without breaking the hash chain linking them to Findings.

### What are the valid path_type values in a Path file?

According to [`skills/ops/evidence-finding-path.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/evidence-finding-path.md) (lines 75-82), the **path_type** field accepts three values: **attack** (describing exploit sequences), **callflow** (documenting function or API call chains), and **solve** (outlining solution steps for CTF or remediation scenarios). Each type structures the **steps** array to map Evidence IDs to Finding IDs sequentially.

### Which file governs the promotion rules for Findings?

The [`skills/ops/analysis-decision-framework.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/analysis-decision-framework.md) defines the governance rules for Finding promotion, specifically referencing **R4*** requirements (lines 45-53) that dictate how evidence sufficiency affects status transitions. This framework also specifies special Evidence ID conventions for edge cases (lines 17-20) and integrates with the **docs-generator** to enforce quality gates before report generation.