Evidence‑Finding‑Path Workflow in reverse‑skill: A Complete Guide

The evidence‑finding‑path workflow in reverse‑skill is an append‑only, three‑stage chain that connects raw observations (Evidence) to analytical conclusions (Finding) and finally to the overall solution narrative (Path), enforced by CLI tools and validators to guarantee immutable, traceable records.

This workflow serves as the backbone of the reverse‑skill project, providing a structured approach to security research, penetration testing, and CTF workflows. Every piece of data collected flows through this chain, ensuring reproducible and auditable analysis. The core contract is defined in skills/ops/evidence-finding-path.md, with enforcement tools distributed across the repository.

---

The Three Stages of the Evidence‑Finding‑Path Workflow

Each stage in the chain has a distinct purpose and strict contract rules that validation tools enforce automatically.

Stage 1: Evidence

Evidence represents immutable records of what was observed during an engagement—commands executed, screenshots captured, files collected, logs extracted, or network traffic recorded.

The Evidence contract (lines 6‑25 in skills/ops/evidence-finding-path.md) requires these fields:

• id: Unique identifier (e.g., E-001)
• title: Human‑readable description
• source_type: How the evidence was obtained (command, screenshot, file, log)
• timestamp: When captured
• hash: Cryptographic integrity check
• repro_command: Exact command to reproduce the observation

Evidence creation is handled by append‑evidence.ps1, which enforces field constraints and rejects duplicate IDs. The script generates immutable Markdown files under work/<case>/evidence/ and maintains an index for quick lookup.

powershell -File skills/scripts/append-evidence.ps1 -CaseRoot work/my-case `
  -Id E-001 -Title "Open clock API" -ReproCommand "curl -sI https://example.com/" `
  -Severity info -Status observed

This command creates work/my-case/evidence/E-001.md following the contract format (lines 28‑34).

---

Stage 2: Finding

Finding represents security or reverse‑engineering conclusions derived from one or more Evidence items. Findings bridge raw data with actionable intelligence.

The Finding contract (lines 43‑60 in skills/ops/evidence-finding-path.md) mandates:

• id: Unique identifier (e.g., F-001)
• title: Summary of the vulnerability or insight
• severity: Critical, high, medium, low, or info
• category: Classification (misconfig, vulnerability, bug, etc.)
• status: validated, tentative, or disputed
• evidence_ids: Array of Evidence IDs that support this Finding (must be non‑empty)
• confidence: Certainty level (high, medium, low)
• impact: Description of security implications
• remediation: Recommended fix or mitigation

Crucially, every Finding must reference at least one Evidence item. This rule is enforced by review_case.py (lines 26‑28), which validates that evidence_ids is non‑empty and that all referenced Evidence exists.

### F-001

- title: Exposed Clock Endpoint
- severity: low
- category: misconfig
- status: validated
- evidence_ids: [E-001]
- location: https://example.com/clock
- impact: Information disclosure
- confidence: high
- repro_steps:
  1. Run the curl command above
- remediation: Restrict endpoint to internal use
- optional_attack: T1087

---

Stage 3: Path

Path weaves Findings into a coherent narrative—whether an attack chain, call‑flow analysis, or step‑by‑step solve sequence. Paths answer: "How did we get from initial access to the goal?"

The Path contract (lines 64‑84 in skills/ops/evidence-finding-path.md) specifies:

• id: Unique identifier (e.g., P-001)
• title: Describes the overall flow
• path_type: attack, defense, analysis, or solve
• start: Initial condition or entry point
• goal: Desired end state
• steps: Ordered list linking Evidence and Finding items
• residual_risks: Remaining concerns after completion

Each step in the steps array must reference both evidence and finding fields, maintaining the complete chain.

### P-001

- title: Privilege Escalation Flow
- path_type: attack
- start: Initial access via exposed clock API
- goal: Obtain root privileges
- steps:
  1. action: Exploit endpoint — evidence: E-001 — finding: F-001
- residual_risks: None

The docs‑generator module requires at least one Path in final security reports, ensuring the complete chain appears in delivered documentation.

---

Enforcement Mechanisms in reverse‑skill

The evidence‑finding‑path workflow is not merely documented—it is programmatically enforced through three integrated components.

Immutable Evidence Creation with append‑evidence.ps1

The PowerShell script skills/scripts/append-evidence.ps1 guarantees Evidence integrity by:

• Validating required fields (severity, status, source type)
• Computing and storing cryptographic hashes
• Rejecting duplicate IDs to prevent overwrites
• Generating timestamped, read‑only Markdown files
• Updating case indices for fast retrieval

Once created, Evidence files are treated as immutable. Any correction requires creating a new Evidence item that supersedes the original, preserving audit history.

Chain Validation with review_case.py

skills/case-review/scripts/review_case.py performs comprehensive integrity checks:

• Verifies every Finding references existing Evidence
• Confirms every Path references at least one Finding and one Evidence
• Validates artifact hashes match stored values
• Builds a reference graph counting Evidence usage across work items, timeline events, and reports
• Generates warnings for unreferenced Evidence items

Run validation with strict mode for production cases:

python3 skills/case-review/scripts/review_case.py work/my-case --verify-hashes --strict

The script outputs a markdown summary including chain status and any integrity violations (see entry point lines 38‑44).

Report Generation Requirements

Templates in docs-generator/references/security-report-templates.md mandate inclusion of the complete evidence‑finding‑path chain. Reports without at least one valid Path fail generation, institutionalizing the workflow in deliverables.

---

Traceability and Graph Analysis

Beyond validation, review_case.py constructs a reference graph that tracks how often each Evidence item appears across:

• Work items and task descriptions
• Timeline events and chronological records
• Generated reports and documentation

This graph enables analysts to identify:

• Orphaned Evidence that never contributed to Findings
• Over‑relied‑upon sources that may need corroboration
• Gaps in the analytical chain requiring additional investigation

The append‑only nature of the system ensures that even corrected conclusions retain visible lineage to original observations.

---

Key Files Implementing the Workflow

File	Purpose	Location
evidence-finding-path.md	Core contract defining all three stages	skills/ops/evidence-finding-path.md
append-evidence.ps1	CLI tool for immutable Evidence creation	skills/scripts/append-evidence.ps1
review_case.py	Validation engine for chain integrity	skills/case-review/scripts/review_case.py
security-report-templates.md	Report templates enforcing Path inclusion	docs-generator/references/security-report-templates.md
IDENTITY.md	Role‑based integration with case metadata	skills/ops/IDENTITY.md

---

Summary

• Evidence captures immutable observations with cryptographic integrity, created via append-evidence.ps1
• Finding derives conclusions from Evidence, enforced to have non‑empty evidence_ids by review_case.py
• Path narrates the complete flow, required in final reports by generator templates
• The entire chain is append‑only, traceable, and programmatically validated across the reverse‑skill toolchain

---

Frequently Asked Questions

What happens if a Finding references non‑existent Evidence?

review_case.py flags this as a validation error. The script checks that every ID in evidence_ids corresponds to an existing Evidence file in the case directory, and that stored hashes match current file contents. Cases with orphaned references fail strict validation.

Can Evidence be modified after creation?

No. The workflow treats Evidence as immutable. The append‑evidence.ps1 script creates read‑only files and rejects duplicate IDs. To correct or update an observation, analysts create a new Evidence item (e.g., E-001-corrected) that references the original, preserving complete audit history.

How does the workflow handle case reports?

The docs‑generator module requires at least one valid Path to produce a security report. Templates in security‑report‑templates.md specify sections that must include the evidence‑finding‑path chain. This ensures traceability from raw data through conclusions to final narrative in all delivered documentation.

What path types are supported in the Path stage?

According to the contract in lines 70‑72 of evidence-finding-path.md, supported path_type values include attack (offensive security flows), defense (incident response or hardening sequences), analysis (reverse‑engineering or debugging), and solve (CTF or puzzle solutions).

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