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

> Discover how reverse-skill organizes case workspaces in isolated Git-ignored directories. Learn about standardized layouts, mandatory contract files, evidence repositories, and automated gate-keeping scripts.

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

---

**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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md), [`timeline.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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:

```text
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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/scope-contract.md) and [`skills/ops/timeline-workitem.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/timeline-workitem.md):

- **[`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md)** – Contains the authoritative operations contract, including `auth.status` and `network_profile` fields that must be populated before any ACT.
- **[`timeline.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/timeline.md)** – Maintains a chronological **decision_delta** log tracking analytical choices.
- **[`workitems.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/E-001.md)), indexed by [`evidence/INDEX.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/evidence/INDEX.md) according to the specifications in [`skills/ops/evidence-finding-path.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md) under “MUST case scope before ACT”, the guard script performs a hard check that [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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
powershell -File skills/scripts/case-init.ps1 -Hint "malware analysis" -CaseName sample-case

```

Validate authorization before running tools:

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

```

Add forensic evidence programmatically:

```powershell
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:

```bash
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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md), [`timeline.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/timeline.md), and [`workitems.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) for authorization contracts, [`timeline.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/timeline.md) for decision logs, [`workitems.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/workitems.md) for task tracking, and the `evidence/` subdirectory with its [`INDEX.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md), [`timeline.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/timeline.md), and `evidence/` structure to function seamlessly across IDA Pro, radare2, APK analysis tools, or custom reverse engineering pipelines.