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

The 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 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 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 is to provide a tamper-evident, replayable log of the entire engagement lifecycle. According to 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 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 follows a strict markdown template defined in skills/ops/timeline-workitem.md. The format ensures machine readability while maintaining human-friendly documentation.

Standard Entry Template

## {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 (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

Architectural Principles and Constraints

The 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 (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 (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 works in tandem with workitems.md to enforce the "no silent gaps >1 major phase" rule. The Coverage checklist in 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:

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

.\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, cross-reference them in the timeline to maintain bidirectional traceability:

## 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 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 (Line 6): Mandates timeline updates at each attack-chain phase transition
• 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 (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 (Line 57) and 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 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.
• 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, driving automated workflow gates.
• Integration with 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. 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, maintains a tamper-evident audit trail while allowing factual corrections.

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

While timeline.md captures the chronological narrative of actions taken, 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 and 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 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.

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