# Understanding the Structure of Case Artifacts in reverse-skill > Explore the structured case artifact layout in the reverse-skill repository. Learn about scope.md, timeline.md, evidence/, and report/ directories validated by case-guard. - Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill) - Tags: deep-dive - Published: 2026-08-23 --- **The reverse-skill repository organizes every security analysis case under `work//`, enforcing a strict artifact layout—including [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md), [`timeline.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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//`, where `` 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//scope.md`, this file holds the operational security contract derived from [`ops/scope-contract.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) exists and passes validation. ### Timeline (timeline.md) The `work//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//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//evidence/` directory contains all collected findings, with individual items stored as `E-.md` files (e.g., [`E-001.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/E-001.md), [`E-002.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/E-002.md)) following the specification in [`skills/ops/evidence-finding-path.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/evidence-finding-path.md). An [`evidence/INDEX.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/case-review/scripts/review_case.py) script populates `work//report/` with finalized deliverables, including [`case-review.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/case-review.md) and [`case-review.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/IDENTITY.md), which links the case to formal organizational identities (team, client, project), and [`role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/role-map.md), which maps contributors to roles defined in [`ops/role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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//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//` structure. Initialize a new case (creates the directory structure and mandatory files): ```powershell powershell -File skills/scripts/case-init.ps1 -Hint "web pentest" -CaseName my-pentest ``` Validate the case structure before execution: ```powershell powershell -File skills/scripts/case-guard.ps1 -CaseRoot work/my-pentest ``` Append verified evidence to the case: ```powershell 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: ```bash 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//`, which is automatically excluded from Git via `.gitignore`. - The **scope contract** ([`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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-.md`) within the `evidence/` subdirectory, indexed by [`INDEX.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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-.md` format (e.g., [`E-001.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/E-001.md), [`E-002.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/E-002.md)) within the `work//evidence/` directory. This convention is specified in [`skills/ops/evidence-finding-path.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/evidence-finding-path.md) and enables the automated generation of [`INDEX.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md), [`timeline.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/timeline.md), [`workitems.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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.