# How reverse-skill Generates Evidence→Finding→Path Reports

> Learn how reverse-skill generates Evidence→Finding→Path reports by chaining a contract validator, case reviewer, and docs generator for reproducible security analysis.

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

---

**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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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
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
powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/verify-routing-coherence.ps1

```

Once validation succeeds, generate the report:

```powershell
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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/evidence-finding-path.md).
- **Read-Only Validation**: The `case-review` skill ([`skills/case-review/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/case-review/SKILL.md)) verifies graph integrity without altering source data.
- **Template-Driven Output**: `docs-generator` ([`skills/docs-generator/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/docs-generator/SKILL.md)) renders reports using [`security-report-templates.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/security-report-templates.md) and optional vendor rules.
- **Automated Routing**: [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs/ARCHITECTURE.md). This document illustrates the interaction between the case review and docs generator components.