Understanding the Evidence-Finding-Path Workflow in reverse-skill ops Contracts

The evidence-finding-path workflow is a three-stage contract framework that structures security cases into immutable Evidence, analyst-level Findings, and traceable Paths to ensure reproducible reverse-engineering operations.

The zhaoxuya520/reverse-skill repository defines a rigorous evidence-finding-path workflow within its ops contracts to standardize how security researchers document and validate reverse-engineering cases. This contract-driven approach creates an immutable chain of custody from initial observation through final reporting, ensuring every analysis remains reproducible and auditable. The framework is implemented across several Markdown contract files and automation scripts that enforce data integrity at each stage.

The Three Stages of the Evidence-Finding-Path Workflow

The ops contracts in skills/ops/evidence-finding-path.md define a strict progression from raw data to actionable intelligence through three distinct stages.

Stage 1: Evidence (Immutable Observations)

The Evidence stage captures raw, immutable observations of artifacts, commands, screenshots, and system states. Each evidence record is stored as a Markdown file under work/<case>/evidence/E-*.md and must include fields such as title, observed_at, source_type, source_ref, content_hash, artifact_path, repro_command, raw_excerpt, linked_workitem, and supersedes.

According to skills/ops/evidence-finding-path.md (lines 6–24), the Evidence contract requires a content_hash for integrity verification and a repro_command to ensure any analyst can recreate the observation. The source_type field categorizes whether the evidence derives from commands, files, or network captures.

Stage 2: Finding (Analyst Conclusions)

The Finding stage represents analyst-level conclusions derived from one or more Evidence records. Defined in skills/ops/evidence-finding-path.md (lines 43–60), each Finding must reference at least one evidence_ids entry and include fields such as severity, category, status, location, impact, confidence, repro_steps, remediation, and optional_attack.

The contract enforces that evidence_ids cannot be empty, and a status: validated Finding cannot have low confidence unless residual_risks are explicitly documented. This ensures that all conclusions remain traceable to concrete observations rather than speculation.

Stage 3: Path (Attack Chains and Solutions)

The Path stage constructs an ordered sequence connecting Evidence to Findings and ultimate operational goals. As specified in skills/ops/evidence-finding-path.md (lines 64–84), Paths include path_type (attack, call-flow, or CTF solution), start and goal descriptors, and a steps array where each step references specific Evidence and Finding IDs.

Each step uses the syntax action: — evidence: E-xxx — finding: F-xxx | none, enabling automated pipelines to render traceable narratives that show exactly how raw observations lead to security conclusions.

Workflow Enforcement Mechanisms

The ops contracts implement six distinct enforcement points to maintain chain integrity throughout the case lifecycle.

Evidence Creation via CLI Helpers

Analysts create Evidence records using the append-evidence.ps1 PowerShell helper located at skills/scripts/append-evidence.ps1. This script validates input parameters and generates properly formatted Markdown files with correct field ordering and syntax.

Validation and Linking Constraints

Before a Finding can be marked as validated, the contract enforces two critical constraints: the evidence_ids array must contain at least one valid Evidence reference, and low-confidence findings must explicitly document residual risks. These rules prevent untested assertions from entering the final report.

Automated Verification with review_case.py

Before case hand-off, reviewers execute skills/case-review/scripts/review_case.py to verify:

• Scope fields are present and complete
• All Evidence records have matching content_hash values
• Work-item and timeline references remain consistent
• Cross-references between Findings, Paths, and Evidence are valid

Report Generation Integration

The docs-generator module consumes the complete Evidence-Finding-Path chain and injects it into security report templates defined in skills/docs-generator/references/security-report-templates.md. The contract mandates that at least one Path must appear in the final deliverable to ensure traceability.

Field-Journal Anonymization

When cases are archived to the anonymized field-journal, the contract extracts up to three key Evidence IDs, one core Finding, and a one-sentence Path summary. This preserves actionable intelligence while removing identifying information, as detailed in the field-journal hooks section of the contract.

Practical Implementation Examples

The following examples demonstrate how to create and link Evidence, Findings, and Paths according to the ops contract specifications.

Creating a new Evidence entry using the PowerShell helper:

powershell -File skills/scripts/append-evidence.ps1 -CaseRoot work/MyCase `
  -Id E-001 -Title "Suspicious DLL loaded" -ReproCommand "ldd /tmp/malware.so" `
  -Severity info -Status observed

This generates a Markdown file with the following structure:

### E-001

- title: Suspicious DLL loaded
- observed_at: 2026-08-08T14:32:00Z
- source_type: command
- source_ref: work/MyCase/evidence/E-001.md
- content_hash: n/a
- artifact_path: n/a
- repro_command: |
    ldd /tmp/malware.so
- raw_excerpt: |
    libcrypto.so.1.1 => /usr/lib/libcrypto.so.1.1 (0x7f...)
- linked_workitem: WI-010
- supersedes: none

Linking Evidence to a Finding requires referencing the Evidence ID in the evidence_ids field:

### F-001

- title: Remote Code Execution via libcrypto
- severity: high
- category: vuln
- status: validated
- evidence_ids: [E-001]
- location: /tmp/malware.so
- impact: Attacker can execute arbitrary code
- confidence: high
- repro_steps:
  1. Run the command shown in E-001
  2. Observe crash
- remediation: Update libcrypto to version ≥1.1.1
- optional_attack: T1203

Constructing a Path that traces the exploit chain:

### P-001

- title: Exploit Chain for CVE‑2026‑XYZ
- path_type: attack
- start: Initial foothold on target host
- goal: Execute attacker‑controlled payload
- steps:
  1. action: Load libcrypto — evidence: E-001 — finding: F-001
  2. action: Trigger overflow — evidence: none — finding: none
- residual_risks: None

Key Contract Files and Automation Scripts

The evidence-finding-path workflow relies on specific files within the zhaoxuya520/reverse-skill repository:

• skills/ops/evidence-finding-path.md — Defines the complete E-F-P contract, including field specifications, CLI helper documentation, and verification procedures.
• skills/ops/IDENTITY.md — Explains the operational philosophy and how the evidence chain integrates with the broader reverse-skill identity framework.
• skills/scripts/append-evidence.ps1 — PowerShell automation script that generates properly formatted Evidence Markdown files with consistent field ordering.
• skills/case-review/scripts/review_case.py — Python verification script that validates the integrity of the entire Evidence-Finding-Path chain before case completion.
• skills/docs-generator/references/security-report-templates.md — Specifies required report sections, including mandatory Path inclusion for traceability.

Summary

• The evidence-finding-path workflow divides reverse-engineering cases into three immutable stages: Evidence (raw observations), Finding (analyst conclusions), and Path (traceable chains).
• Each stage is governed by strict contracts defined in skills/ops/evidence-finding-path.md that enforce field completeness and cross-referencing requirements.
• Evidence records require content_hash and repro_command fields to ensure integrity and reproducibility.
• Findings must link to at least one Evidence ID via evidence_ids, and validated findings cannot have low confidence without documented residual risks.
• Paths connect Evidence and Findings into ordered steps using a standardized syntax that supports automated narrative generation.
• The workflow is enforced through CLI helpers (append-evidence.ps1), automated verification (review_case.py), and mandatory report generation hooks.

Frequently Asked Questions

What is the primary purpose of the evidence-finding-path workflow?

The workflow establishes a contract-driven evidence chain that guarantees reproducibility, traceability, and consistent reporting across all reverse-skill operations. By separating raw observations from analyst conclusions and connecting them through structured Paths, the framework ensures that every security claim can be traced back to immutable evidence and reproduced by independent reviewers.

How does the contract enforce data integrity between Evidence and Findings?

The contract mandates that every Finding must include a non-empty evidence_ids array referencing specific Evidence records. Additionally, the review_case.py script verifies that content_hash values match between stored artifacts and metadata, and that all cross-references resolve correctly before case hand-off occurs.

Can a Path exist without referencing specific Evidence or Findings?

Yes, individual steps within a Path may use none for the evidence or finding fields when documenting inferred actions or hypothetical steps. However, the contract requires that at least one Path appear in the final security report, and the overall case must maintain a valid chain from Evidence through Finding to support validated conclusions.

What tools automate the creation and validation of workflow components?

Analysts use append-evidence.ps1 to create properly formatted Evidence records through a command-line interface. For validation, the review_case.py script automates integrity checks across the entire Evidence-Finding-Path chain, verifying hash matches, reference consistency, and contract compliance before generating final reports.

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