Evidence-Finding-Path Workflow in reverse-skill: Connecting Findings to Reports

The evidence-finding-path workflow is an immutable audit chain that connects raw observations (Evidence) to analyst conclusions (Findings) and attack narratives (Paths), ensuring every security report traces back to reproducible data.

The reverse-skill repository implements a rigorous evidence-finding-path workflow to structure security assessments and reverse-engineering engagements. This contract-based system mandates that every conclusion references immutable source data, creating an audit trail that the docs-generator skill converts into compliant security reports.

Understanding the Three Core Components

The workflow enforces a strict hierarchy: Evidence feeds Findings, which are organized into Paths. Each component uses a standardized Markdown format with specific filename conventions.

Evidence (E‑xxx): Immutable Observations

Evidence entries capture raw, unalterable observations as Markdown files named E‑<nnn>.md. Each record contains fields for title, source_type, source_ref, content_hash, artifact_path, and repro_command, ensuring any observation can be independently verified.

According to the specification in skills/ops/evidence-finding-path.md (lines 28-34), analysts create Evidence using the helper script at skills/scripts/append-evidence.ps1. This script generates the Markdown file with a unique ID and computes content hashes automatically, preventing tampering after creation.

Finding (F‑xxx): Analyst Conclusions

Findings represent the security or reverse-engineering conclusions drawn from Evidence. Stored as F‑<nnn> entries, each Finding lists severity, category, status, and crucially an evidence_ids array that points to supporting Evidence entries (lines 45-53 in skills/ops/evidence-finding-path.md).

Validation rules in the same file (lines 62-63) enforce two critical constraints:

• Every Finding must reference at least one Evidence ID
• A Finding marked as validated cannot carry low confidence unless accompanied by a residual‑risk note

Path (P‑xxx): Attack and Solution Narratives

Paths provide the narrative structure connecting Evidence and Findings into coherent stories. Whether documenting an attack chain, call flow, or remediation steps, each Path entry (P‑<nnn>) contains a steps array where individual actions explicitly reference both Evidence (E‑xxx) and Finding (F‑yyy) IDs (lines 74-82).

This linkage demonstrates how the analyst moved from observation to conclusion, satisfying requirements for auditability in security assessments.

Validation Rules and Quality Gates

The workflow implements hard validation rules to maintain data integrity:

1. Mandatory Evidence Binding – No Finding can exist without at least one evidence_ids entry. This prevents unsubstantiated claims in final reports.

2. Confidence Consistency – The system blocks Findings marked status: validated when confidence: low unless the analyst explicitly documents residual risk. This prevents overconfidence in tentative conclusions.

3. Immutable Evidence – Once created via append-evidence.ps1, Evidence files cannot be modified without breaking the content_hash validation, ensuring forensic integrity.

Report Generation: From Chain to Document

The docs-generator skill consumes the evidence-finding-path chain to produce security reports. As specified in skills/docs-generator/references/security-report-templates.md (lines 7-26), the security report template mandates inclusion of:

• §0 Evidence Chain – A table of all Evidence entries
• Findings Section – List of Findings with hyperlinked Evidence IDs
• Path Description – At least one Path showing the attack or solution flow

When executing skills/docs-generator/scripts/generate-report.ps1, the generator pulls Markdown tables for Evidence, renders the Findings list with linked Evidence IDs, and inserts the Path steps. This automation guarantees traceability from the final PDF or HTML report back to the raw observations and reproduction commands.

Practical Implementation Example

Create Evidence using the PowerShell helper:

# Create immutable Evidence E-001

powershell -File skills/scripts/append-evidence.ps1 -CaseRoot work/MyCase `
    -Id E-001 -Title "Found vulnerable configuration" `
    -ReproCommand "nmap -p 22,80 target.com" -Severity info -Status observed

Define a Finding that references the Evidence:

### F-001

- title: "Unauthenticated SSH access"
- severity: high
- category: misconfig
- status: validated
- evidence_ids: [E-001]
- location: "target.com:22"
- confidence: high
- remediation: "Disable password authentication"

Link them in a Path narrative:

### P-001

- title: "Privilege escalation path"
- path_type: attack
- start: "Initial foothold"
- goal: "Root access"
- steps:
  1. action: "Enumerate services" — evidence: E-001 — finding: F-001
  2. action: "Exploit CVE-2023-XYZ" — evidence: E-002 — finding: F-002

Generate the final report:

powershell -File skills/docs-generator/scripts/generate-report.ps1 -CaseRoot work/MyCase

Summary

• The evidence-finding-path workflow in reverse-skill creates an immutable chain from raw data to final reports, ensuring auditability and reproducibility.
• Evidence (E‑<nnn>.md) captures immutable observations via skills/scripts/append-evidence.ps1, storing reproduction commands and content hashes.
• Findings (F‑<nnn>) must reference at least one Evidence ID and cannot claim validated status with low confidence without residual-risk documentation.
• Paths (P‑<nnn>) narrate the connection between Evidence and Findings, showing how conclusions were reached.
• The docs-generator skill enforces inclusion of this chain in security reports according to the template in skills/docs-generator/references/security-report-templates.md.

Frequently Asked Questions

What is the evidence-finding-path workflow in reverse-skill?

The evidence-finding-path workflow is a structured audit chain that mandates every security conclusion (Finding) connects to immutable source data (Evidence) and narrative context (Path). Implemented in the reverse-skill repository, it ensures that reports generated by the docs-generator skill contain fully traceable and reproducible findings.

How does Evidence differ from Findings in the workflow?

Evidence (E‑xxx) represents raw, immutable observations captured as Markdown files with hashes and reproduction commands, created via skills/scripts/append-evidence.ps1. Findings (F‑xxx) represent the analyst's interpreted conclusions—such as vulnerabilities or misconfigurations—that explicitly reference Evidence IDs in their evidence_ids array to substantiate the claim.

Why are Evidence entries immutable in this workflow?

Evidence entries are immutable to preserve forensic integrity and ensure reproducibility. Once created, the content_hash field prevents modification, guaranteeing that reports always reference the exact data observed during the engagement, not interpretations changed after the fact.

How is the evidence chain validated during report generation?

The docs-generator skill validates the chain by enforcing the template requirements defined in skills/docs-generator/references/security-report-templates.md. It verifies that the report includes the Evidence table, Findings list with linked Evidence IDs, and at least one Path section before rendering the final document, ensuring no Finding appears without supporting Evidence.

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