How reverse-skill Generates Evidence→Finding→Path Reports

reverse-skill chains three dedicated components—a contract validator, a read-only case reviewer, and a docs generator—to transform raw security evidence into reproducible, auditable reports.

The zhaoxuya520/reverse-skill repository implements a deterministic pipeline for converting raw security observations into professional documentation. This article explains how the Evidence→Finding→Path workflow enforces data integrity through immutable evidence records, structured findings, and validated attack paths before rendering the final output.

The Evidence→Finding→Path Contract

The foundation of the reporting system is defined in skills/ops/evidence-finding-path.md. This markdown contract establishes strict validation rules that every report must satisfy:

• Every Evidence record (immutable raw observations) must be referenced by at least one Finding (structured analysis).
• Each Finding that claims a successful exploit or data exfiltration must point to a validated Path entry describing the specific attack steps.
• The contract requires a reproducible repro_command or a clear offline limitation note for every validated chain.

These rules ensure that no finding appears in the final report without supporting evidence and a documented technical path.

Case Review: Validating the Evidence Chain

Before report generation begins, the case-review skill (defined in skills/case-review/SKILL.md) performs a read-only audit of the evidence graph. This step visualizes the Evidence→Finding→Path relationships, checks cryptographic fixity to ensure evidence has not been tampered with, and verifies that the chain is complete.

The case review is strictly non-destructive—it does not modify the underlying Evidence—but prepares validated data structures for the reporting engine. If the chain contains gaps or integrity failures, the pipeline halts before reaching the docs generator.

Docs‑Generator: Compiling the Final Report

The docs-generator skill (skills/docs-generator/SKILL.md) serves as the rendering engine. It reads the validated structures output by the case review and applies the markdown template defined in skills/docs-generator/references/security-report-templates.md. This template includes dedicated sections for the Evidence Chain, Findings, and Path narratives.

Optional vendor-specific formatting is controlled by skills/docs-generator/references/vendor-report-rules.md, allowing the generated report to match specific organizational standards. The output can be further enriched with diagrams from the diagram-generator skill when visual attack flows are required.

Execution Flow and Routing Configuration

According to docs/ARCHITECTURE.md, the end-to-end flow follows a deterministic sequence:

Evidence → Finding → Path → Case Review → Docs‑Generator → Final Report

The routing table in skills/config/routing.json maps the docs-generator skill as the downstream action for any task reaching the “report” branch. This guarantees automatic report generation once the Evidence→Finding→Path chain passes validation, eliminating manual handoff errors.

Running the Report Pipeline (Code Examples)

Trigger the complete pipeline from a Linux, macOS, or Kali shell:

bash skills/scripts/master-route.sh --hint "Generate report for case 001"

For manual execution on Windows, first invoke the case review to validate routing coherence:

powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/verify-routing-coherence.ps1

Once validation succeeds, generate the report:

powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/run-docs-generator.ps1

(Note: The repository provides wrappers such as verify-routing-coherence.ps1 that automatically invoke docs-generator upon successful review.)

Summary

• Immutable Evidence: Raw observations are locked and referenced by findings in skills/ops/evidence-finding-path.md.
• Read-Only Validation: The case-review skill (skills/case-review/SKILL.md) verifies graph integrity without altering source data.
• Template-Driven Output: docs-generator (skills/docs-generator/SKILL.md) renders reports using security-report-templates.md and optional vendor rules.
• Automated Routing: skills/config/routing.json ensures reports trigger automatically upon chain validation.
• Reproducibility: Every finding requires a repro_command or explicit limitation note before inclusion in the final document.

Frequently Asked Questions

How does reverse-skill ensure Evidence immutability?

The contract in skills/ops/evidence-finding-path.md mandates that Evidence records remain immutable once created. The case-review skill performs cryptographic fixity checks to verify that evidence files have not been modified before the report is generated.

What triggers the docs-generator skill automatically?

The routing configuration in skills/config/routing.json maps the docs-generator as the downstream handler for any task branch labeled “report”. When the case review validates the Evidence→Finding→Path chain, the routing table automatically queues the docs generator without manual intervention.

Can I customize the report format for specific vendors?

Yes. The docs-generator reads formatting rules from skills/docs-generator/references/vendor-report-rules.md. By modifying this file, analysts can apply vendor-specific styling, section ordering, or compliance markings to the generated markdown output.

Where is the end-to-end architecture documented?

The complete data flow—from raw Evidence through Finding and Path validation to final report delivery—is visualized in docs/ARCHITECTURE.md. This document illustrates the interaction between the case review and docs generator components.

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