# How the Evidence-Finding Path Establishes the Evidence Chain in reverse‑skill

> Learn how the evidence finding path establishes the evidence chain in reverse skill. Discover its SHA-256 hashing and contract enforcement for traceable, verifiable, and reproducible steps.

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

---

**The evidence-finding path enforces a strict Evidence → Finding → Path workflow that guarantees every investigative step is traceable, verifiable, and reproducible through SHA‑256 hashing and mandatory contract enforcement.**

The **evidence-finding path** is a core architectural pattern in the `zhaoxuya520/reverse-skill` repository that transforms raw security artefacts into a tamper-evident audit trail. Defined primarily in [`skills/ops/evidence-finding-path.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/evidence-finding-path.md), this workflow ensures that every analysis action—from initial data collection to final reporting—maintains an unbroken chain of custody.

## The Evidence Chain Architecture

The framework implements a **five-step evidence chain** that links raw data to analytical conclusions through cryptographic verification and structured documentation.

### Step 1: Evidence Collection with Cryptographic Binding

Raw artefacts (logs, memory dumps, screenshots) are gathered into the case's `evidence/` directory. Each piece receives a **unique identifier** and a **SHA‑256 content hash** stored in the `content_hash` field.

This requirement is baked into the contract: no evidence entry is valid without its hash computed at ingestion time.

### Step 2: Finding Identification and Hash Linkage

Analysts examine evidence and produce **findings**—concise markdown statements of what the artefact reveals. Each finding file (e.g., [`F-001.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/F-001.md)) explicitly references its source evidence through the original `content_hash`.

This bidirectional linkage ensures findings remain tethered to their source material regardless of file moves or renames.

### Step 3: Path Construction for Attack Progression

Findings accumulate into a **logical path** that reconstructs attack progression, compliance gaps, or remediation sequences. The path file aggregates all hashes and findings into a traversable narrative.

The operational command `evidence-finding-path + review_case --verify-hashes` recomputes stored hashes to detect any evidence tampering before path finalization.

### Step 4: Verification and Timeline Append

Before case closure, **rules R5 and R20‑R21** in [`skills/ops/analysis-decision-framework.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/analysis-decision-framework.md) mandate:
- Hash re-verification against source files
- Automated `append-evidence` action to the case work-items timeline

These rules trigger at [`analysis-decision-framework.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/analysis-decision-framework.md) lines 100 and 129, creating a governance checkpoint that prevents incomplete or unverified chains from entering the permanent record.

### Step 5: Report Integration for Audit Visibility

Finalized paths feed directly into security reports. The templates in [`skills/docs-generator/references/security-report-templates.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/docs-generator/references/security-report-templates.md) (line 9) **require** an Evidence→Finding→Path section, making the chain visible to external auditors.

## Contract Enforcement Mechanisms

The evidence chain operates through three layers of enforcement:

| Layer | Implementation | Key File |
|-------|---------------|----------|
| **Contract definition** | Data schema, naming conventions, hash algorithms | [`skills/ops/evidence-finding-path.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/evidence-finding-path.md) |
| **Rule enforcement** | Mandatory invocation for every `ACT` operation | [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md) (line 21) |
| **Operational integration** | Automatic evidence recording in skill definitions | Individual [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) files |

As stated in [`README_AI.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/README_AI.md) (line 42), the evidence chain is a **core pre-condition** for all AI-assisted operations in the framework.

## Practical Implementation: YAML Skill Definition

The following snippet from a domain [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) demonstrates how the path is referenced operationally:

```yaml
ACT:
  - description: "Run privilege escalation check"
    command: "./check_privesc.sh"
    evidence: "evidence/E-001.md"          # raw command output

    finding:  "F-001.md"                   # analyst interpretation

    path:    "ops/evidence-finding-path.md" # hash verification contract

```

The `path` field ensures that [`evidence-finding-path.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/evidence-finding-path.md) validates the hash linkage before the action completes.

## Hash Verification: Bash Helper

This utility script verifies chain integrity after findings are added:

```bash
verify_evidence_chain () {
  local evidence_file=$1
  local hash=$(sha256sum "$evidence_file" | cut -d' ' -f1)
  grep -q "$hash" ops/evidence-finding-path.md && echo "✅ Hash verified"
}

# Usage

verify_evidence_chain evidence/E-001.md

```

The script extracts the SHA‑256 hash and confirms its presence in the central path registry, catching any file corruption or substitution.

## Timeline Append: PowerShell Automation

For Windows environments, this script appends new evidence entries with computed hashes:

```powershell
$evidence = Get-Content -Raw -Path "evidence/E-002.md"
$hash = (Get-FileHash -Path "evidence/E-002.md" -Algorithm SHA256).Hash
Add-Content -Path "ops/evidence-finding-path.md" -Value "`n$hash :: $evidence"

```

The `Get-FileHash` cmdlet guarantees algorithmic consistency with Unix-based operations, ensuring cross-platform chain validity.

## Source File Reference Map

All evidence chain behavior is codified in these repository locations:

- [`skills/ops/evidence-finding-path.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/evidence-finding-path.md) — primary contract defining the Evidence→Finding→Path workflow
- [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md) — mandates evidence chain usage for every `ACT` step
- [`README_AI.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/README_AI.md) — establishes the chain as a core operational pre-condition
- [`skills/ops/analysis-decision-framework.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/analysis-decision-framework.md) — specifies verification (`R5`) and append (`R20-R21`) rules
- [`skills/docs-generator/references/security-report-templates.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/docs-generator/references/security-report-templates.md) — requires Evidence→Finding→Path sections in generated reports
- [`skills/ops/README.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/README.md) — module overview and operational guidelines

## Summary

- The **evidence-finding path** creates an **immutable audit trail** through mandatory SHA‑256 hashing of all artefacts
- Five sequential steps—collection, finding, path construction, verification, and reporting—ensure **traceability from raw data to final conclusion**
- Rules **R5 and R20-R21** in [`analysis-decision-framework.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/analysis-decision-framework.md) enforce verification gates before case closure
- The architecture is **cross-platform** with reference implementations in Bash and PowerShell
- All `ACT` operations must declare their `evidence`, `finding`, and `path` fields per [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md) line 21

## Frequently Asked Questions

### What makes the evidence chain tamper-evident?

The SHA‑256 `content_hash` stored at ingestion time is recomputed during verification. Any modification to evidence files—accidental or malicious—produces a hash mismatch that [`evidence-finding-path.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/evidence-finding-path.md) detects during the `--verify-hashes` operation.

### Can the evidence chain work without automated tools?

Yes. While scripts automate hash computation, the contract only requires that hashes be **present and verifiable**. Manual workflows using standard `sha256sum` or `Get-FileHash` commands satisfy the requirement equally.

### How does the framework prevent missing evidence links?

[`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md) explicitly prohibits `ACT` operations without declared `evidence`, `finding`, and `path` fields. The parser rejects skill definitions lacking these mandatory components, enforcing structural compliance at definition time rather than runtime.

### Where is the evidence chain documented for auditors?

Generated reports automatically include the Evidence→Finding→Path section per [`security-report-templates.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/security-report-templates.md). This section presents the complete hash-linked narrative in auditor-friendly format without requiring repository access.