# How to Append Evidence Records Using reverse-skill Scripts: A Complete Guide

> Learn to append evidence records using reverse-skill scripts. This guide explains the file-based workflow for analysts to add evidence and manage it effectively within the zhaoxuya520/reverse-skill repository.

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

---

**The reverse-skill repository provides a file-based workflow where analysts append evidence by creating markdown files in the `evidence/` folder and referencing their IDs in [`timeline.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/timeline.md) and optionally [`workitems.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/workitems.md)—all orchestrated through [`case-init.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/case-init.sh).**

The open-source **reverse-skill** repository automates security case management through structured file generation and disciplined documentation practices. This article explains how to **append evidence records** once a case has been initialized and marked ready for action.

## Understanding the Evidence Workflow in reverse-skill

At the heart of reverse-skill's case management system is [`skills/scripts/case-init.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/case-init.sh), which creates a standardized directory structure under `work/<case-id>/`. The script establishes four key components:

- **`evidence/`** — Stores individual evidence records as markdown files (`E-*.md`)
- **[`timeline.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/timeline.md)** — An append-only audit log that tracks all actions
- **[`workitems.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/workitems.md)** — A task table that can reference evidence for traceability
- **[`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md)** — Defines the investigation boundaries

According to lines 335-339 of the source code, when a case reaches **ready_for_act** status (indicating `auth.status=granted` and an in-scope asset is set), [`case-init.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/case-init.sh) explicitly instructs analysts to append new evidence files and reference them in the timeline.

## Creating Evidence Files

Evidence records in reverse-skill are simple markdown documents stored in the `evidence/` subdirectory. The filename itself becomes the evidence ID.

### Step 1: Locate Your Case Directory

[`case-init.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/case-init.sh) generates the case root at runtime. Find it programmatically:

```bash
CASE_ROOT=$(find work -maxdepth 1 -type d -name "*-$(date +%Y%m%d)*" | head -n1)

```

### Step 2: Create a New Evidence Record

Create a markdown file with the `E-<NNN>.md` naming convention. As shown in lines 26-27 of [`case-init.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/case-init.sh), this directory is generated during case initialization:

```bash
cat > "$CASE_ROOT/evidence/E-004.md" <<'EOF'

# Evidence E-004 – Sample Private Key Leak

## Description

A PEM-encoded private key was discovered in the repository `src/crypto/keys/`.

## Artefacts

- src/crypto/keys/leaked_key.pem
- git log showing the commit that introduced the key

## Impact

Allows decryption of traffic encrypted with the corresponding public key.

## Mitigation

Rotate the key pair and remove the private key from source control.
EOF

```

The source code's generated [`README.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/README.md) (lines 35-40) reinforces this pattern: "Append [`timeline.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/timeline.md); update [`workitems.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/workitems.md); **Append Evidence under `evidence/`**."

## Linking Evidence to the Audit Trail

The **append-only nature** of [`timeline.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/timeline.md) ensures immutable record-keeping. Each entry must include the `evidence_ids` field to establish traceability.

### Step 3: Append to timeline.md

```bash
DATE=$(date -Iseconds)
cat >> "$CASE_ROOT/timeline.md" <<EOF

## $DATE | analyst | add-evidence

- action: add_evidence
- command_or_ref: skills/scripts/case-init.sh
- result_summary: added evidence E-004
- artifacts: [evidence/E-004.md]
- evidence_ids: [E-004]
- decision_delta: [evidence_added]
- next: continue-analysis
EOF

```

Key fields for evidence linkage:

- **`evidence_ids`** — Array of evidence IDs this action references
- **`artifacts`** — File paths to the actual evidence documents
- **`decision_delta`** — What changed in the case state

### Step 4: Update workitems.md (Optional)

For task tracking, reference evidence IDs in the work items table:

```bash
sed -i '/^| WI-001 /a| WI-002 | Review evidence E-004 | analyst | case | in_progress | E-004 | |' "$CASE_ROOT/workitems.md"

```

This maintains traceability between tasks and supporting evidence without external tooling.

## File Structure Reference

| Component | Purpose | Location |
|-----------|---------|----------|
| Case Initializer | Generates case skeleton, creates `evidence/`, prints next actions | [`skills/scripts/case-init.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/case-init.sh) |
| Evidence Folder | Stores individual evidence records (`E-*.md`) | `work/<case-id>/evidence/` |
| Timeline | Append-only action log with evidence linking | `work/<case-id>/timeline.md` |
| Work Items | Task table referencing evidence IDs | `work/<case-id>/workitems.md` |
| Evidence Guide | Conceptual workflow documentation | [`skills/ops/evidence-finding-path.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/evidence-finding-path.md) |

## Complete Evidence Addition Example

Here's the full workflow an analyst executes after case initialization:

```bash
#!/bin/bash
set -euo pipefail

# Locate case directory

CASE_ROOT=$(find work -maxdepth 1 -type d -name "*-$(date +%Y%m%d)*" | head -n1)
[[ -z "$CASE_ROOT" ]] && { echo "No case directory found"; exit 1; }

EVIDENCE_ID="E-$(printf '%03d' $(( $(ls "$CASE_ROOT/evidence"/E-*.md 2>/dev/null | wc -l) + 1 )))"

# Create evidence record

cat > "$CASE_ROOT/evidence/${EVIDENCE_ID}.md" <<EOF

# Evidence ${EVIDENCE_ID} – Unauthorized API Key

## Description

Hardcoded API key found in environment configuration.

## Artefacts

- config/production.yml (line 42)

## Impact

Unauthorized access to payment processing API.

## Severity

High
EOF

# Append to timeline

date -Iseconds | xargs -I {} cat >> "$CASE_ROOT/timeline.md" <<EOF

## {} | $(whoami) | add-evidence

- action: add_evidence
- command_or_ref: skills/scripts/case-init.sh
- result_summary: added evidence ${EVIDENCE_ID}
- artifacts: [evidence/${EVIDENCE_ID}.md]
- evidence_ids: [${EVIDENCE_ID}]
- decision_delta: [evidence_added]
- next: assess-severity
EOF

echo "Evidence ${EVIDENCE_ID} appended successfully"

```

## Key Design Principles

The reverse-skill evidence system adheres to several security-focused constraints:

1. **File-system only** — No databases or external services required
2. **Append-only timeline** — Prevents tampering with historical records
3. **Self-describing IDs** — Filenames serve as canonical identifiers
4. **Plaintext storage** — Full auditability without specialized tools

These principles align with the repository's security rules while maintaining operational simplicity.

## Summary

- **[`case-init.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/case-init.sh)** creates the `evidence/` folder and instructs analysts on evidence workflow
- **Evidence files** are markdown documents in `work/<case-id>/evidence/` with `E-<NNN>.md` naming
- **Timeline entries** must reference evidence IDs in the `evidence_ids` field
- **Work items** can optionally link to evidence for task traceability
- All operations use standard file-system commands—no additional dependencies required

## Frequently Asked Questions

### What naming convention should I use for evidence files?

Use the `E-<NNN>.md` format where `<NNN>` is a zero-padded three-digit number, such as [`E-001.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/E-001.md) or [`E-042.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/E-042.md). This convention is established by the case skeleton generated in [`skills/scripts/case-init.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/case-init.sh) and ensures consistent, sortable identifiers throughout the case lifecycle.

### Can I edit evidence files after creating them?

While technically possible, you should **not** edit evidence files once referenced in [`timeline.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/timeline.md). The append-only design of [`timeline.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/timeline.md) presumes evidence is immutable to maintain audit integrity. If corrections are needed, create a new evidence file (e.g., [`E-005.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/E-005.md)) that supersedes or clarifies the original.

### What happens if I forget to update timeline.md?

Missing timeline entries break the case's audit trail. The `evidence_ids` field in timeline entries is what formally links evidence to investigative actions. Without this linkage, evidence exists in isolation and cannot be traced to specific decisions or analyst activities. Always append the timeline entry immediately after creating evidence.

### Do I need any special permissions to append evidence?

Evidence appending requires only standard file-system write access to the `work/<case-id>/` directory. The reverse-skill repository deliberately avoids external authentication or secrets for this workflow, as implemented in `zhaoxuya520/reverse-skill` to satisfy air-gapped and restricted-access environments.