# How Evidence Records Are Structured and Named in reverse-skill

> Discover how evidence records are structured and named in reverse-skill. Learn about the Markdown file format, required schema, and storage location for efficient evidence management.

- Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill)
- Tags: how-to-guide
- Published: 2026-08-23

---

**In reverse-skill, every piece of raw proof is captured as an Evidence record stored as a Markdown file named `E-<nnn>.md` under `work/<case>/evidence/`, following a strict schema defined in [`skills/ops/evidence-finding-path.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/evidence-finding-path.md) that requires a title, source metadata, SHA-256 hash, and reproducible command.**

The reverse-skill framework enforces a rigorous evidence-tracking system for security research and CTF workflows. Understanding how evidence records are structured and named ensures reproducible findings and auditable case work. This guide examines the canonical specification and file conventions implemented in the zhaoxuya520/reverse-skill repository.

## File Naming Convention and Storage Location

Evidence files reside in a predictable path within case workspaces. According to the source code specification in [`skills/ops/evidence-finding-path.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/evidence-finding-path.md), each evidence record follows the naming pattern:

```

work/<case>/evidence/E-<nnn>.md

```

Where `<case>` represents the case directory name and `<nnn>` is a zero-padded sequential number (e.g., `E-001`, `E-002`). This convention ensures chronological ordering and unique identification across the investigation lifecycle.

## Required Fields and Markdown Structure

Every Evidence file is a standalone Markdown document that begins with a heading `### E-<nnn>` followed by a structured field list. The schema mandates specific metadata fields to maintain forensic integrity.

### The Complete Field Schema

| Field | Description |
|-------|-------------|
| `title` | Human-readable short description of the evidence. |
| `observed_at` | Timestamp (optional) when the evidence was collected. |
| `source_type` | One of `command`, `screenshot`, `file`, `log`, `memory`, `network`, `manual`. |
| `source_ref` | Reference to the originating command or file path. |
| `content_hash` | SHA-256 of the artifact (if a file) or `n/a`. |
| `artifact_path` | Relative path under the case root where the artifact lives. |
| `repro_command` | Exact command that can recreate the evidence. |
| `raw_excerpt` | Sanitized excerpt of the raw output. |
| `linked_workitem` | Optional link to a work-item (`WI-<nnn>`) that generated the evidence. |
| `supersedes` | Optional reference to a previous evidence record that this one replaces. |

### Mandatory Validation Rules

The reverse-skill specification enforces strict validation rules via the CLI tooling. Every Evidence record must contain:

- A non-empty `title` field
- A valid `repro_command` that third parties can execute (or marked as offline-only)

Additionally, every Finding must reference at least one Evidence record to maintain the audit chain.

## Automating Evidence Creation with append-evidence.ps1

The repository provides a PowerShell helper script at `skills/scripts/append-evidence.ps1` that automates file creation while enforcing naming conventions and required fields.

```powershell
powershell -File skills/scripts/append-evidence.ps1 -CaseRoot work/my-case `
  -Id E-002 -Title "Initial memory dump" -SourceType memory `
  -ReproCommand "gcore -o evidence/memdump $(pid)" -ArtifactPath "evidence/memdump.core"

```

This command generates [`work/my-case/evidence/E-002.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/work/my-case/evidence/E-002.md) with properly formatted front matter and validates that mandatory fields are present.

## Complete Evidence Record Example

A minimal yet valid evidence file demonstrates the expected structure. Here is an example from the CTF demo at [`examples/ctf-demo/evidence/E-001.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/examples/ctf-demo/evidence/E-001.md):

```markdown

### E-001

- title: Checksec output for binary `pwn1`
- observed_at: 2026-08-16T14:23:00Z
- source_type: command
- source_ref: checksec pwn1
- content_hash: 9f2c3e5b7a1d4f8e9c6b2a4d5e7f1a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f
- artifact_path: evidence/checksec-output.txt
- repro_command: |
    checksec --format=brief pwn1 > evidence/checksec-output.txt
- raw_excerpt: |
    ... (sanitized excerpt of the checksec output) ...
- linked_workitem: WI-001
- supersedes: n/a

```

## Summary

- Evidence records in reverse-skill are Markdown files stored under `work/<case>/evidence/` with the naming convention `E-<nnn>.md`.
- Each file must begin with a heading `### E-<nnn>` and contain mandatory fields including `title`, `repro_command`, and `content_hash`.

- The `source_type` field categorizes evidence as command, screenshot, file, log, memory, network, or manual.
- The `skills/scripts/append-evidence.ps1` CLI helper automates creation while enforcing the schema defined in [`skills/ops/evidence-finding-path.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/evidence-finding-path.md).
- Validation rules require every Finding to reference at least one Evidence record, ensuring complete audit trails.

## Frequently Asked Questions

### What is the required filename format for evidence records in reverse-skill?

Evidence files must follow the pattern `E-<nnn>.md` where `<nnn>` is a sequential number (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)). These files reside in the `work/<case>/evidence/` directory relative to the case workspace root.

### Which fields are mandatory when creating an Evidence record?

Every Evidence record must include a non-empty `title` and a valid `repro_command` that third parties can execute. While other fields like `observed_at` and `linked_workitem` are optional, the schema requires `source_type`, `source_ref`, `content_hash`, and `artifact_path` for complete traceability.

### How does reverse-skill validate evidence file integrity?

The framework validates that `content_hash` contains a SHA-256 checksum for file artifacts (or `n/a` for non-file sources) and verifies that `repro_command` contains runnable instructions. The `append-evidence.ps1` script enforces these constraints during file creation.

### Can an evidence record replace or update a previous entry?

Yes, use the `supersedes` field to reference a previous Evidence record (e.g., `supersedes: E-001`). This maintains version history while allowing investigators to update or correct evidence without losing the audit trail.