# How Evidence Is Appended in reverse-skill: Complete PowerShell Workflow

> Learn how evidence is appended in reverse-skill using the append-evidence.ps1 script. This PowerShell workflow creates markdown files and updates timeline.md for an immutable audit trail.

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

---

**Evidence is appended in reverse-skill by executing the `append-evidence.ps1` PowerShell script, which validates case directories, creates structured markdown files in the `evidence/` folder, and chronologically updates the [`timeline.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/timeline.md) log to maintain an immutable audit trail.**

The reverse-skill repository provides a structured case management framework for digital forensics and penetration testing workflows. Understanding how evidence is appended in reverse-skill requires examining the PowerShell automation scripts that enforce consistent documentation standards. The entire process centers on `skills/scripts/append-evidence.ps1`, which serves as the single entry point for adding reproducible artifacts to a case.

## The Core Evidence Appending Script

The primary mechanism for adding evidence resides in `skills/scripts/append-evidence.ps1`. This script acts as the gatekeeper for case data integrity, ensuring every piece of evidence receives a unique identifier, proper attribution, and chronological placement within the investigation timeline.

When invoked, the script performs three critical operations: it validates the target case directory structure, generates a new markdown evidence file (e.g., [`E-001.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/E-001.md)) containing supplied metadata, and appends a corresponding entry to the case-wide [`timeline.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/timeline.md) file located in the case root.

## Step-by-Step Evidence Appending Workflow

The reverse-skill framework follows a strict four-phase workflow when appending evidence to maintain forensic integrity.

### 1. Initialize the Case Directory

Before adding evidence, analysts must run `skills/scripts/case-init.ps1` to create the working directory structure under `work/<case-name>`. This establishes the `evidence/` folder and initializes the [`timeline.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/timeline.md) file that will track all subsequent evidence additions.

### 2. Gather and Document Evidence

After collecting artifacts during reconnaissance, the analyst invokes `append-evidence.ps1` with specific metadata parameters. Required inputs include the evidence ID (e.g., `E-001`), descriptive title, reproducible command used to generate the artifact, and the artifact's file path.

### 3. Script Execution and File Generation

Upon execution, `append-evidence.ps1` performs automated validation checks to confirm the case directory exists and is writable. The script then creates a structured markdown file in the `evidence/` directory containing the supplied fields. If provided, the script also copies raw excerpt content via the `-RawExcerptFile` or `-RawExcerpt` parameters directly into the evidence documentation for quick reference.

Simultaneously, the script inserts a chronological entry into [`timeline.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/timeline.md), ensuring the new evidence appears in the correct temporal sequence within the final report.

### 4. Verification via Smoke Testing

The `skills/scripts/smoke.ps1` utility validates the appending operation by confirming the new evidence file exists in the expected location and verifying the timeline entry was recorded correctly. This sanity check ensures immutability of case data and detects any filesystem inconsistencies.

## PowerShell Implementation Examples

The following examples demonstrate the canonical usage patterns for appending evidence in reverse-skill, as documented in [`skills/ops/evidence-finding-path.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/evidence-finding-path.md).

Append a cryptographic hash as new evidence:

```powershell
powershell -File skills/scripts/append-evidence.ps1 `
    -CaseRoot work\my-case `
    -Id E-002 `
    -Title "Malware SHA256" `
    -ReproCommand "sha256sum evidence/malware.bin" `
    -ArtifactPath "evidence\malware.bin"

```

Append manual analysis findings with inline excerpt:

```powershell
powershell -File skills/scripts/append-evidence.ps1 `
    -CaseRoot work\my-case `
    -Id E-003 `
    -Title "Interesting string" `
    -RawExcerpt "The function xyz() is called with suspicious parameters..." `
    -ArtifactPath "evidence\strings.txt"

```

Execute the validation suite after appending:

```powershell
powershell -File skills/scripts/smoke.ps1 -Name append-evidence.ps1

```

## Critical Files in the Evidence Appending Process

Several files within the zhaoxuya520/reverse-skill repository define and implement the evidence appending workflow:

- **`skills/scripts/append-evidence.ps1`** — Core PowerShell script that creates evidence markdown files and updates the timeline log.
- **[`skills/ops/evidence-finding-path.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/evidence-finding-path.md)** — Documentation specifying required parameters and the canonical calling convention for evidence appending.
- **`skills/scripts/smoke.ps1`** — Sanity-check utility that verifies evidence file existence and timeline integrity.
- **`skills/scripts/case-init.ps1`** — Directory initialization script that prepares the case structure for evidence reception.
- **[`skills/pentest-tools/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/pentest-tools/SKILL.md)** — References the evidence appending workflow within penetration testing contexts.
- **[`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md)** — Contains the canonical command line examples for appending evidence during automated routing workflows.

## Integration with Master Routing and Pentest Workflows

The evidence appending mechanism integrates directly with reverse-skill's broader automation framework. As documented in [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md), the `append-evidence.ps1` script receives orchestrated calls during master routing executions, allowing automated tools to submit findings directly into case files without manual intervention.

Similarly, [`skills/pentest-tools/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/pentest-tools/SKILL.md) references these scripts when documenting how penetration testing tools should output findings, ensuring that dynamic scan results follow the same immutable documentation standards as manual evidence collection.

## Summary

- **Centralized Script**: All evidence appending flows through `skills/scripts/append-evidence.ps1`, ensuring consistent metadata capture.
- **Immutable Timeline**: Every append operation updates [`timeline.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/timeline.md) to maintain chronological integrity of the investigation.
- **Validation Required**: The `smoke.ps1` script verifies successful evidence registration and filesystem consistency.
- **Parameter-Driven**: Analysts supply `-CaseRoot`, `-Id`, `-Title`, `-ReproCommand`, and `-ArtifactPath` to create reproducible evidence records.
- **Framework Integration**: The process integrates with master routing and pentest tool workflows for automated case population.

## Frequently Asked Questions

### What parameters are required to run append-evidence.ps1?

The script requires five mandatory parameters: `-CaseRoot` specifies the case directory path, `-Id` provides a unique evidence identifier (e.g., `E-001`), `-Title` describes the evidence, `-ReproCommand` records the exact command used to generate the artifact, and `-ArtifactPath` indicates the relative path to the evidence file. Optional parameters include `-RawExcerpt` for inline text or `-RawExcerptFile` for referencing external text files.

### How does reverse-skill ensure evidence integrity after appending?

The framework enforces integrity through immutable timeline updates and automated validation. After appending, the `smoke.ps1` script verifies that the markdown file exists in the `evidence/` directory and confirms the chronological entry appears in [`timeline.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/timeline.md). This dual-verification ensures that once evidence is recorded, it remains traceable within the case audit trail.

### Can evidence be appended to existing case files, or only new ones?

The `append-evidence.ps1` script creates new evidence files for each unique ID (e.g., [`E-001.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/E-001.md)), but updates the existing [`timeline.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/timeline.md) file to maintain the chronological record. While individual evidence files are created anew, the timeline acts as an append-only log that grows with each new submission, preserving the historical sequence of the investigation.

### Where is the evidence appending process documented in the repository?

The primary documentation resides in [`skills/ops/evidence-finding-path.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/evidence-finding-path.md), which details the workflow parameters and calling conventions. Additional references appear in [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md) for automation contexts and [`skills/pentest-tools/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/pentest-tools/SKILL.md) for penetration testing integration examples.