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

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 and governed by 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 (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 -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 with the following structure:

### 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:

### 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 (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:

### 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 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 (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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}