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

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 and optionally workitems.md—all orchestrated through 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, 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 — An append-only audit log that tracks all actions
• workitems.md — A task table that can reference evidence for traceability
• 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 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 generates the case root at runtime. Find it programmatically:

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, this directory is generated during case initialization:

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 (lines 35-40) reinforces this pattern: "Append timeline.md; update workitems.md; Append Evidence under evidence/."

Linking Evidence to the Audit Trail

The append-only nature of timeline.md ensures immutable record-keeping. Each entry must include the evidence_ids field to establish traceability.

Step 3: Append to timeline.md

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:

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
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

Complete Evidence Addition Example

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

#!/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 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 or E-042.md. This convention is established by the case skeleton generated in 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. The append-only design of timeline.md presumes evidence is immutable to maintain audit integrity. If corrections are needed, create a new evidence file (e.g., 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.

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