How Findings (F-{nnn}) Are Defined and Validated in reverse-skill

In the reverse-skill repository, Findings (F-{nnn}) are structured security observations defined by a markdown template in skills/pentest-tools/templates/findings.md and validated through an Evidence-to-Finding pipeline that requires at least one linked Evidence (E-{nnn}) entry to be marked "validated" before the Finding is considered confirmed.

The reverse-skill repository implements a rigorous documentation framework for penetration testing workflows that enforces traceability between raw observations and reported vulnerabilities. Understanding how Findings (F-{nnn}) are defined and validated in reverse-skill ensures that every security observation links to concrete evidence through structured templates and automated CI checks.

What Is a Finding in reverse-skill?

A Finding is a structured result that records a security-related observation such as a vulnerability, information leak, or investigative clue. Each Finding receives a unique identifier following the F-{nnn} format (for example, F-001, F-002), which appears in field-journal tables to link Evidence (E-{nnn}) rows to specific Finding IDs.

Findings serve as the canonical output of the reverse-skill workflow, transforming raw technical evidence into actionable security reports with assigned severity levels and remediation guidance.

Finding Definition and Template Structure

The Official Template Location

The authoritative definition for Finding structure resides in skills/pentest-tools/templates/findings.md. This template mandates specific sections that every Finding must contain:

• Confirmed bugs: Validated vulnerabilities with reproduction steps
• Potential bugs: Suspected issues requiring further investigation
• Leaks: Information disclosure observations
• Clues: Indicators that suggest additional attack vectors
• Excluded items: Deliberately ruled-out vulnerabilities

The template establishes the expected markdown hierarchy, ensuring that Findings follow a consistent format across all penetration testing engagements.

Required Finding Components

According to the template implementation, each validated Finding must document:

• Risk level (high/medium/low severity classification)
• Location (affected endpoint, file path, or component)
• Evidence reference (linked E-{nnn} identifier)
• Reproduction steps (exact commands or sequences)
• Remediation suggestions (specific fix recommendations)

The Evidence-to-Finding Validation Pipeline

The validation workflow follows the Evidence → Finding → Path pipeline documented in skills/ops/evidence-finding-path.md. This five-stage process ensures that only verified observations reach final reports.

Step 1: Collect Evidence

Raw observations are recorded as Evidence entries (E-{nnn}) in the field-journal. Each entry captures the specific command, request, or observation that produced a security-relevant result.

Step 2: Link to Finding

Evidence rows include a dedicated column for the associated Finding ID (F-{nnn}). This creates a bidirectional traceability link: the Evidence points to its parent Finding, and the Findings document references its supporting Evidence.

Step 3: Confirm Validity

A Finding achieves validated status only when at least one linked Evidence entry contains the status validated in the field-journal's status column. Evidence marked merely as observed does not confer validation status upon its linked Finding.

Step 4: Assign Confidence

Once validated, the Finding receives a confidence rating (high, medium, or low) based on the strength and reproducibility of its linked Evidence.

Step 5: Record in Findings Document

The validated Finding is then written into the findings markdown file using the structure defined in skills/pentest-tools/templates/findings.md, ensuring consistent formatting across the security assessment.

Automated Validation Checks

The repository enforces data integrity through routing and checklist scripts located in skills/scripts/. These automated validators perform critical consistency checks:

• Verify that every F-{nnn} referenced in the field-journal has a matching Evidence entry
• Confirm that linked Evidence entries carry the validated status flag
• Fail CI pipelines when Findings lack validated Evidence or contain broken links

This automation prevents unconfirmed observations from appearing in final deliverables, maintaining the repository's standards for reproducibility and accuracy.

Field-Journal Linking Syntax

The field-journal uses a specific table format to establish Evidence-to-Finding relationships. Each row follows this structure:

| Evidence | Severity | Status     | Type    | Command                                 | Finding |
|----------|----------|------------|---------|-----------------------------------------|---------|
| E-001    | high     | validated  | command | `python3 exploit.py REMOTE`             | F-001   |
| E-002    | medium   | observed   | command | `curl http://target/api/info`           | F-002   |

In this example:

• E-001 is validated evidence linked to F-001, confirming that Finding
• E-002 remains merely observed, so F-002 stays in "potential" status

The Finding ID (F-001) must appear as a heading in the findings document using the format ### F-001 [Title], creating a navigable link between the evidence table and the detailed Finding description.

Summary

• Findings (F-{nnn}) are standardized security observations defined by the template in skills/pentest-tools/templates/findings.md
• Validation requires at least one linked Evidence (E-{nnn}) entry with status validated per skills/ops/evidence-finding-path.md
• Traceability is enforced through field-journal tables that map Evidence rows to Finding IDs
• Automation in skills/scripts/* prevents unvalidated Findings from passing CI checks
• Structure mandates risk levels, locations, reproduction steps, and remediation guidance for every confirmed Finding

Frequently Asked Questions

What is the difference between Evidence (E-{nnn}) and Findings (F-{nnn}) in reverse-skill?

Evidence (E-{nnn}) represents raw technical observations—individual commands, requests, or outputs captured during testing. Findings (F-{nnn}) represent synthesized security conclusions that interpret one or more Evidence entries. The relationship is hierarchical: multiple Evidence items can support a single Finding, but a Finding cannot exist without at least one linked Evidence entry.

Where is the Finding template defined in the reverse-skill repository?

The official Finding template resides in skills/pentest-tools/templates/findings.md. This file establishes the required markdown sections including confirmed bugs, potential bugs, leaks, clues, and excluded items. It also defines the expected format for risk ratings, evidence references, and remediation guidance that automated scripts validate against.

How does automated validation work for Findings in reverse-skill?

Automated validation scripts in skills/scripts/ parse field-journal markdown tables to verify that every referenced F-{nnn} has corresponding E-{nnn} entries marked with validated status. The CI pipeline fails if Findings reference non-existent Evidence or if linked Evidence lacks validation, enforcing the repository's requirement that only verified observations appear in final reports.

Can a Finding be confirmed without validated Evidence?

No. According to the pipeline defined in skills/ops/evidence-finding-path.md, a Finding achieves confirmed status only when at least one linked Evidence entry carries the validated status flag. Evidence marked merely as observed or pending does not satisfy the validation requirements, ensuring that all reported vulnerabilities are reproducible and verified.

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