# What Is timeline.md in Reverse-Skill Case Management? A Complete Guide

> Discover the purpose of timeline.md in Reverse-Skill case management. This guide explains how this append-only chronicle records every step for complete security engagement replayability.

- Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill)
- Tags: deep-dive
- Published: 2026-08-01

---

**The [`timeline.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/timeline.md) file serves as an immutable, append-only chronicle that records every operational step in a Reverse-Skill case, enabling full replayability of security engagements from reconnaissance to final reporting.**

In the `zhaoxuya520/reverse-skill` framework, every case initialization creates a structured workspace under `work/<case>/`, where [`timeline.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/timeline.md) functions as the central source of truth. This markdown file implements the "Z3r0 timeline 思想" (Zero Timeline philosophy), ensuring that every action, tool execution, and finding is permanently recorded without silent gaps. Understanding the purpose and format of [`timeline.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/timeline.md) is essential for maintaining audit trails and generating verifiable security reports.

## Core Purpose of timeline.md in Case Management

The primary function of [`timeline.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/timeline.md) is to provide a **tamper-evident, replayable log** of the entire engagement lifecycle. According to [`skills/ops/timeline-workitem.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/timeline-workitem.md), the timeline embodies immutable record-keeping that allows teams to reconstruct the exact sequence of events without relying on live streaming or external logs.

When a new case boots via `skills/scripts/case-init.ps1`, the directory scaffold automatically includes an empty [`timeline.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/timeline.md) ready for entries. This file captures:

- Reconnaissance actions and scan results
- Tool executions with exact commands
- Artifact generation and storage paths
- Evidence promotion tracking (E-xxx IDs)
- Decision points and next steps

## Timeline Entry Format and Structure

Each entry in [`timeline.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/timeline.md) follows a strict markdown template defined in [`skills/ops/timeline-workitem.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/timeline-workitem.md). The format ensures machine readability while maintaining human-friendly documentation.

### Standard Entry Template

```markdown

## {ISO-8601} | {role} | {phase}

- action:
- command_or_ref:
- result_summary:
- artifacts: []      # relative paths under this case

- evidence_ids: []   # E-xxx when promoted

- next:

```

**Key fields explained:**

- **ISO-8601 timestamp**: Provides precise temporal ordering (e.g., `2026-08-01T14:30:00Z`)
- **Role**: Maps to entries in [`skills/ops/role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/role-map.md) (e.g., `cie` for Cyber Intelligence Expert, `cpe` for Cyber Penetration Expert)
- **Phase**: Aligns with engagement phases like `Recon`, `Act`, or `Post`
- **Artifacts**: Relative paths to files stored under the case's `evidence/` directory
- **Evidence IDs**: Reference numbers (e.g., `E-015`) that feed into the **Evidence → Finding → Path** workflow defined in [`skills/ops/evidence-finding-path.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/evidence-finding-path.md)

## Architectural Principles and Constraints

The [`timeline.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/timeline.md) implementation enforces several architectural constraints to maintain integrity across the case lifecycle.

### Immutable Append-Only Policy

As specified in [`skills/ops/timeline-workitem.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/timeline-workitem.md) (Lines 38-39), existing `##` blocks must never be edited or removed. Corrections require new entries with a `corrects:` field referencing the erroneous timestamp. This guarantees a tamper-evident history that supports forensic validation.

### Role-Phase Context Binding

The `role` and `phase` headers tie directly to [`skills/ops/role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/role-map.md) (Line 25). This binding drives decision gates where the framework checks "update timeline + workitems" before allowing phase transitions. For example, a `cie` role operating in the `Recon` phase must log activities before moving to `Act`.

### Coverage Tracking Integration

[`timeline.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/timeline.md) works in tandem with [`workitems.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/workitems.md) to enforce the "no silent gaps >1 major phase" rule. The Coverage checklist in [`skills/ops/timeline-workitem.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/timeline-workitem.md) (Lines 52-58) verifies that every significant activity appears in the timeline, preventing undocumented operational gaps.

## How to Create and Update timeline.md

While `skills/scripts/case-init.ps1` creates the initial file, population occurs through both manual editing and automated scripts.

### Manual Entry Example

To record a port scan manually, append the following block to `work/<case>/timeline.md`:

```markdown

## 2026-08-01T14:30:00Z | cie | Recon

- action: Enumerate open ports on target subnet
- command_or_ref: nmap -p 1-65535 10.10.10.0/24
- result_summary: Found 23 open ports across 5 hosts
- artifacts: [evidence/nmap_2026-08-01.txt]
- evidence_ids: [E-015]
- next: Proceed to service fingerprinting

```

### Automated Append via PowerShell

The framework provides `append-evidence.ps1` to programmatically add entries while preserving existing content:

```powershell
.\skills\scripts\append-evidence.ps1 `
  -CaseName "acme-2026" `
  -Role "cie" `
  -Phase "Recon" `
  -Action "Enumerate open ports" `
  -Command "nmap -p 1-65535 10.10.10.0/24" `
  -Result "23 open ports on 5 hosts" `
  -Artifacts "evidence/nmap_2026-08-01.txt" `
  -EvidenceIds "E-015"

```

This script formats the block and writes it to the end of the timeline file without modifying historical entries.

### Linking to Work Items

After creating entries in [`workitems.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/workitems.md), cross-reference them in the timeline to maintain bidirectional traceability:

```markdown

## 2026-08-01T15:05:00Z | cie | Recon

- action: Verify vulnerable service identified in WI-001
- command_or_ref: curl http://10.10.10.5:8080/
- result_summary: Service responded with version 1.2.3 (vulnerable)
- artifacts: [evidence/curl_2026-08-01.txt]
- evidence_ids: [E-016]
- next: Exploit development (WI-002)

```

## Ecosystem Integration and Reporting

[`timeline.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/timeline.md) serves as the backbone for multiple downstream processes within the Reverse-Skill framework.

### Skill Integration Points

Specialized skills must append timeline entries after execution batches:

- **[`skills/attack-chain/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/attack-chain/SKILL.md)** (Line 6): Mandates timeline updates at each attack-chain phase transition
- **[`skills/pentest-tools/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/pentest-tools/SKILL.md)** (Line 16): Requires at least one timeline entry after each tool batch run

These integrations ensure that automated tool executions remain visible in the case chronicle.

### Evidence and Finding Workflow

Timeline entries link to the **Evidence → Finding → Path** workflow via [`skills/ops/evidence-finding-path.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/evidence-finding-path.md) (Line 87). When artifacts are promoted to evidence (assigned `E-xxx` IDs), the timeline provides the temporal context for how those findings were discovered, supporting the chain of custody requirements.

### Report Generation

According to [`skills/docs-generator/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/docs-generator/SKILL.md) (Line 57) and [`README.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/README.md) (Line 57), final security reports embed selected timeline entries directly. This approach ensures that report narratives are backed by verifiable, timestamped logs rather than reconstructed memories.

## Summary

- **[`timeline.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/timeline.md)** acts as the immutable, append-only chronicle for every Reverse-Skill case, initialized by `skills/scripts/case-init.ps1`.
- Entries follow a strict template with ISO-8601 timestamps, role/phase context, and artifact references defined in [`skills/ops/timeline-workitem.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/timeline-workitem.md).
- The append-only policy prohibits editing existing entries; corrections require new blocks with `corrects:` fields.
- Role and phase headers bind to [`skills/ops/role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/role-map.md), driving automated workflow gates.
- Integration with [`workitems.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/workitems.md) prevents silent operational gaps through coverage tracking.
- Skills like `attack-chain` and `pentest-tools` are contractually required to append entries after execution.
- Evidence IDs in the timeline feed into the **Evidence → Finding → Path** workflow for audit trails.
- Final reports leverage timeline entries as verifiable source material, ensuring forensic accuracy.

## Frequently Asked Questions

### What happens if I need to correct an error in a previous timeline entry?

You must never edit or delete existing `##` blocks in [`timeline.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/timeline.md). Instead, append a new entry with a `corrects:` field referencing the timestamp of the erroneous entry. This append-only policy, defined in [`skills/ops/timeline-workitem.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/timeline-workitem.md), maintains a tamper-evident audit trail while allowing factual corrections.

### How does timeline.md relate to workitems.md in case management?

While [`timeline.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/timeline.md) captures the chronological narrative of actions taken, [`workitems.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/workitems.md) tracks discrete tasks and deliverables. The two files work together to enforce coverage rules—specifically, the framework checks that no major phase gap exists without corresponding timeline entries. Cross-referencing work item IDs (e.g., `WI-001`) in timeline entries creates bidirectional traceability between tasks and executed actions.

### Which skills are required to update timeline.md during an engagement?

According to [`skills/attack-chain/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/attack-chain/SKILL.md) and [`skills/pentest-tools/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/pentest-tools/SKILL.md), both the attack-chain and pentest-tools skills must append at least one timeline entry after each batch run or phase transition. This requirement ensures that automated activities are captured in the case chronicle alongside manual operations.

### Can timeline.md entries be used directly in final client reports?

Yes. The [`skills/docs-generator/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/docs-generator/SKILL.md) explicitly supports embedding timeline entries into final security reports. Because entries include ISO-8601 timestamps, evidence IDs, and artifact references, they provide verifiable source material that backs narrative findings with immutable operational logs.