How Case Workspaces Are Organized in reverse-skill: Directory Structure and Security Model

Each case workspace in reverse-skill is isolated as a dedicated, Git-ignored directory under work/<case>/ that enforces a standardized layout with mandatory contract files (scope.md, timeline.md), an evidence repository, and automated gate-keeping scripts that prevent analytical actions until authorization criteria are met.

The reverse-skill repository structures every reverse engineering engagement as a discrete case workspace to ensure sensitive artifacts remain outside version control while maintaining rigorous operational standards. Located under the repository’s top-level work/ folder, these directories follow strict Ops contracts defined in skills/ops/ and implement hard gates that validate security scope before any tool execution.

Directory Structure of a Case Workspace

When initialized via skills/scripts/case-init.ps1 (or its shell equivalent), every case workspace adheres to a fixed hierarchy designed for forensic integrity and reproducibility.

Root Layout and Git Isolation

The work/ directory itself is listed in .gitignore, ensuring that all case contents—potentially containing malware samples, credentials, or exploit code—never enter the git history. Each case resides in its own subdirectory:

work/<case>/               # Root of the case (git-ignored)

├─ scope.md                # Ops contract: authentication, network profile

├─ timeline.md             # Chronological decision log (decision_delta)

├─ workitems.md            # List of pending work items

├─ evidence/               # Individual evidence files (E-001.md, etc.)

│  └─ INDEX.md             # Evidence index

└─ report/                 # Generated hand-off reports

Contract Files and Metadata Standards

Three primary Markdown files enforce the Ops contracts defined in skills/ops/scope-contract.md and skills/ops/timeline-workitem.md:

• scope.md – Contains the authoritative operations contract, including auth.status and network_profile fields that must be populated before any ACT.
• timeline.md – Maintains a chronological decision_delta log tracking analytical choices.
• workitems.md – Enumerates discrete tasks to be performed during the engagement.

The evidence/ subdirectory stores individual findings as sequentially numbered Markdown files (e.g., E-001.md), indexed by evidence/INDEX.md according to the specifications in skills/ops/evidence-finding-path.md.

Authorization Gates and Security Controls

Before any analytical tool executes against a target, the workspace must pass mandatory validation checks enforced by skills/scripts/case-guard.ps1.

The case-guard Enforcement Mechanism

As documented in RULES.md under “MUST case scope before ACT”, the guard script performs a hard check that scope.md contains auth.status=granted alongside a valid network_profile or an offline-sample preset. This gate prevents accidental execution of operations against unauthorized targets or live environments without explicit contractual consent. The verification runs both interactively and in CI pipelines.

Evidence Integrity Workflows

New evidence items are appended via skills/scripts/append-evidence.ps1, which automatically generates properly formatted E-*.md files under evidence/ and updates the index. This ensures consistent metadata fields—including ReproCommand and RawExcerpt—across all case artifacts.

Automating Case Workspace Operations

The repository provides native automation for the entire case lifecycle, accepting a --CaseRoot work/<case> argument to remain agnostic of the underlying reverse engineering skill (IDA, radare2, APK analysis, etc.).

Initialize a new case with mandatory boilerplate:

powershell -File skills/scripts/case-init.ps1 -Hint "malware analysis" -CaseName sample-case

Validate authorization before running tools:

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

Add forensic evidence programmatically:

powershell -File skills/scripts/append-evidence.ps1 `
    -CaseRoot work/sample-case `
    -Title "Initial binary dump" `
    -ReproCommand "cp target.bin evidence.bin" `
    -RawExcerpt "binary size: 1.2 MB"

Generate final review reports:

python3 skills/case-review/scripts/review_case.py work/sample-case \
    --format markdown > work/sample-case/report/case-review.md

Summary

• Case workspaces reside under work/<case>/ and are strictly Git-ignored to protect sensitive artifacts from entering version control.
• The directory structure mandates scope.md, timeline.md, and workitems.md per Ops contracts stored in skills/ops/.
• The case-guard.ps1 script enforces a hard gate requiring auth.status=granted and valid network profiles before any ACT can occur.
• Evidence management uses sequential E-*.md files in evidence/ managed by append-evidence.ps1 and validated against evidence-finding-path.md.
• All scripts accept --CaseRoot parameters, making the workspace model tool-agnostic and compatible with any reverse engineering workflow.

Frequently Asked Questions

What files are created when initializing a new case workspace?

Running skills/scripts/case-init.ps1 generates the complete directory tree, including scope.md for authorization contracts, timeline.md for decision logs, workitems.md for task tracking, and the evidence/ subdirectory with its INDEX.md. The script also creates the report/ folder for final deliverables. This standardized initialization ensures every case begins with the required Ops contract structure.

How does reverse-skill prevent sensitive case data from leaking into git?

The entire work/ directory is listed in .gitignore, which prevents Git from tracking any files within case workspaces. This isolation ensures that sensitive artifacts such as malware samples, proprietary credentials, or exploit code never enter the repository history, maintaining strict confidentiality for each engagement.

What validation must pass before running tools against a case target?

Before any tool execution, skills/scripts/case-guard.ps1 validates that scope.md contains auth.status=granted and either a valid network_profile or an offline-sample preset. This enforcement of the “MUST case scope before ACT” rule from RULES.md prevents unauthorized analytical actions against live targets or unapproved samples.

Can the case workspace structure be used with different reverse engineering tools?

Yes, the architecture is explicitly tool-agnostic; all automation scripts including skills/case-review/scripts/review_case.py accept a --CaseRoot work/<case> argument that points to the workspace directory. This design allows the standardized scope.md, timeline.md, and evidence/ structure to function seamlessly across IDA Pro, radare2, APK analysis tools, or custom reverse engineering pipelines.

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