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

> Explore the evidence-finding-path workflow in reverse-skill. This guide details how this immutable, three-stage chain connects observations to conclusions and solutions.

- Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill)
- Tags: how-to-guide
- Published: 2026-08-20

---

**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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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
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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/review_case.py) (lines 26‑28), which validates that `evidence_ids` is non‑empty and that all referenced Evidence exists.

```markdown

### 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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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.

```markdown

### 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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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:

```bash
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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/evidence-finding-path.md) | Core contract defining all three stages | [`skills/ops/evidence-finding-path.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/evidence-finding-path.md) |
| `append-evidence.ps1` | CLI tool for immutable Evidence creation | `skills/scripts/append-evidence.ps1` |
| [`review_case.py`](https://github.com/zhaoxuya520/reverse-skill/blob/main/review_case.py) | Validation engine for chain integrity | [`skills/case-review/scripts/review_case.py`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/case-review/scripts/review_case.py) |
| [`security-report-templates.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/security-report-templates.md) | Report templates enforcing Path inclusion | [`docs-generator/references/security-report-templates.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs-generator/references/security-report-templates.md) |
| [`IDENTITY.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/IDENTITY.md) | Role‑based integration with case metadata | [`skills/ops/IDENTITY.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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).