Understanding the Structure of Case Artifacts in reverse-skill

The reverse-skill repository organizes every security analysis case under work/<case>/, enforcing a strict artifact layout—including scope.md, timeline.md, evidence/, and report/ directories—that is validated by the case-guard script before any action execution.

The reverse-skill framework provides a structured environment for conducting reproducible security analyses, storing all case-specific data within a dedicated work/ directory. Understanding the structure of case artifacts in reverse-skill is essential for maintaining a defensible evidence chain and ensuring that every operation adheres to the predefined operational contract. Each case directory functions as an isolated workspace containing mandatory markdown contracts, evidence logs, and final reports that are automatically generated and validated by the framework's tooling.

Core Directory Layout

All case data resides under work/<case>/, where <case> represents a unique identifier for the analysis session. This directory is excluded from version control via the repository's .gitignore file (containing the pattern work/), ensuring that sensitive engagement data remains local while the framework code stays portable. When initialized via skills/scripts/case-init.ps1, this root directory becomes the canonical container for all subsequent artifacts.

Mandatory Case Artifacts

The framework enforces the presence of specific files that constitute the operational backbone of every case.

Scope Contract (scope.md)

Located at work/<case>/scope.md, this file holds the operational security contract derived from ops/scope-contract.md. It records critical parameters including the authentication status (auth.status=granted), the network profile (mode: authorized_target_only or offline), and the ready_for_act: true flag. The case-guard script treats this file as a hard gate; execution blocks until scope.md exists and passes validation.

Timeline (timeline.md)

The work/<case>/timeline.md file maintains a chronological log of major case actions, including initialization events, routing decisions, and evidence collection timestamps. This artifact is consumed by the timeline-workitem skill to reconstruct the investigation sequence.

Workitems (workitems.md)

Stored at work/<case>/workitems.md, this human-readable markdown list tracks active tasks, research vectors, and exploitation steps. It serves as the living document that drives the case forward, bridging automated scripts and analyst decisions.

Evidence Collection (evidence/)

The work/<case>/evidence/ directory contains all collected findings, with individual items stored as E-<n>.md files (e.g., E-001.md, E-002.md) following the specification in skills/ops/evidence-finding-path.md. An evidence/INDEX.md file provides a curated lookup table for rapid navigation. Each evidence file includes reproducible commands and verification hashes to maintain forensic integrity.

Report Output (report/)

Upon case completion, the skills/case-review/scripts/review_case.py script populates work/<case>/report/ with finalized deliverables, including case-review.md and case-review.json. These documents provide a defensible hand-off record suitable for client delivery or archival.

Identity and Role Mapping

Optional but recommended files include IDENTITY.md, which links the case to formal organizational identities (team, client, project), and role-map.md, which maps contributors to roles defined in ops/role-map.md for access control auditing.

Optional Assets and Reproducibility

Beyond mandatory artifacts, analysts may create sub-directories such as patches/ or samples/ to store binary diffs, network captures, or other data required for reproduction. While these folders are permitted by the framework, they remain local-only artifacts thanks to the work/ gitignore rule.

Enforcement and Validation

The integrity of the structure of case artifacts in reverse-skill relies on the skills/scripts/case-guard.ps1 script, which implements a hard gate validation. Before any ACT script executes, case-guard verifies that work/<case>/scope.md exists, confirms that auth.status equals "granted", and validates the network profile configuration. This mechanism guarantees that operations cannot proceed against live targets without explicit authorization, preventing accidental data exfiltration or unauthorized testing.

Practical Case Management

The following commands demonstrate the lifecycle of case artifact generation and validation within the work/<case>/ structure.

Initialize a new case (creates the directory structure and mandatory files):

powershell -File skills/scripts/case-init.ps1 -Hint "web pentest" -CaseName my-pentest

Validate the case structure before execution:

powershell -File skills/scripts/case-guard.ps1 -CaseRoot work/my-pentest

Append verified evidence to the case:

powershell -File skills/scripts/append-evidence.ps1 -CaseRoot work/my-pentest `
  -Title "nmap scan" -ReproCommand "nmap -sV target.example" `
  -RawExcerpt "$(cat nmap.txt)" -Status "verified"

Generate the final case review report:

python3 skills/case-review/scripts/review_case.py work/my-pentest \
  --verify-hashes --strict --format markdown > work/my-pentest/report/case-review.md

Summary

• All case artifacts reside under work/<case>/, which is automatically excluded from Git via .gitignore.
• The scope contract (scope.md) acts as a mandatory operational gate, enforced by case-guard.ps1 before any action execution.
• Evidence files follow a strict naming convention (E-<n>.md) within the evidence/ subdirectory, indexed by INDEX.md.
• Timeline and workitems files provide chronological and task-oriented views of the investigation.
• Final reports are generated in the report/ directory by review_case.py, ensuring auditable hand-off documentation.
• Optional identity and role files support multi-analyst coordination and formal client associations.

Frequently Asked Questions

What is the purpose of the scope.md file in reverse-skill?

The scope.md file serves as the operational contract for each case, defining authentication status, network restrictions, and readiness flags. It is mandatory because the case-guard script blocks all ACT operations until this file validates that the engagement is authorized and properly configured.

How does reverse-skill prevent sensitive case data from being committed to Git?

The repository includes a .gitignore rule that matches the work/ directory pattern, ensuring all case artifacts—including evidence, reports, and scope contracts—remain local to the analyst's machine and are never pushed to remote repositories.

What naming convention does reverse-skill use for evidence files?

Evidence artifacts must follow the E-<n>.md format (e.g., E-001.md, E-002.md) within the work/<case>/evidence/ directory. This convention is specified in skills/ops/evidence-finding-path.md and enables the automated generation of INDEX.md for quick reference.

Can I customize the directory structure within work//?

While you can create optional subdirectories such as patches/ or samples/ for reproducibility assets, the core files (scope.md, timeline.md, workitems.md, and the evidence/ folder) are strictly enforced by the framework's initialization and validation scripts. Deviating from this structure will cause case-guard to fail.

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