Timeline-WorkItem Tracking System for Case Management: A Complete Guide

The timeline-workitem tracking system is an immutable, markdown-based audit mechanism that records every action and task status in penetration-testing and reverse-engineering cases, storing mutable data outside the git tree in work/<case>/ directories.

The zhaoxuya520/reverse-skill repository implements a timeline-workitem tracking system to manage case workflows without polluting version control. This architecture deliberately separates immutable skill logic from mutable engagement data, enabling clean diffs and comprehensive audit trails for security assessments.

Architectural Overview

The system is specified in skills/ops/timeline-workitem.md and centers on three core components stored outside the repository's tracked source code. By placing mutable case data in a git-ignored work/<case>/ directory, the system maintains immutable skill packages while preserving complete engagement histories.

Key components include:

• Case Directory: work/<case>/ holds all mutable artifacts for a single engagement
• Timeline File: work/<case>/timeline.md serves as the chronological, append-only log
• Work Items File: work/<case>/workitems.md tracks concrete tasks and coverage status
• Bootstrap Script: skills/scripts/case-init.ps1 initializes new case folders

Directory Structure and Git Isolation

All case-specific files reside under work/<case>/, which is excluded from Git via .gitignore. This separation allows collaborators to freely edit case data without generating repository noise.

The standard case directory layout includes:

work/<case>/
  scope.md           # Engagement contract (from ops/scope-contract.md)

  timeline.md        # Immutable-append audit log

  workitems.md       # Task table and coverage checklist

  evidence/          # Raw artifacts (screenshots, pcaps, logs)

  notes/             # Working notes

  report/            # Draft or final reports

Because this folder is ignored, git diff remains focused on skill improvements rather than case-specific changes, while the case data stays portable and reviewable as plain markdown.

The Timeline (timeline.md)

The timeline.md file functions as an append-only ledger recording every step of an engagement. Each entry follows a strict block format using ISO-8601 timestamps, role identifiers, and phase markers.

Required entry format:

## 2026-07-15T14:32:00Z | pentester | Recon

- action: Conducted external port scan
- command_or_ref: `nmap -sS -T4 -p1-65535 $TARGET`
- result_summary: Open ports 22, 80, 443
- artifacts: [evidence/E-001.png]
- evidence_ids: [E-001]
- next: Perform service enumeration

Critical constraint: Entries must never be deleted or rewritten. If correction is necessary, append a new block with corrects: <timestamp> referencing the erroneous entry. This immutability ensures a complete, tamper-evident audit trail.

Work Items (workitems.md)

The workitems.md file maintains a tabular list of Work Items (WIs) representing concrete tasks, their current status, and linked evidence. This enables coverage tracking across the engagement lifecycle.

Table structure:

ID	title	role	targets	surface	status	evidence	notes
WI-001	Port scan edge	cie	{ip}	network	done	E-001
WI-002	Auth bypass check	cpe	/api/login	web	blocked		need creds

Valid status values: pending, in_progress, blocked, done, cancelled.

The file also contains a Coverage checklist mapping high-level milestones to completed work items, ensuring no critical phases are omitted from the final report.

Initialization and Automation

Practitioners initialize new cases using the provided PowerShell bootstrap script located at skills/scripts/case-init.ps1.

Creating a new case:

# Scaffold the case folder "acme-2026" with core files

powershell -File skills\scripts\case-init.ps1 -Hint "full pentest" -CaseName "acme-2026"

This generates the folder structure and populates timeline.md and workitems.md with header comments and table templates.

For automated logging, the repository includes helper functions such as Add-TimelineEntry that append formatted blocks without manual editing:

function Add-TimelineEntry {
    param(
        [string]$Case,
        [string]$Phase,
        [string]$Action,
        [string]$Cmd,
        [string]$Result,
        [string[]]$Artifacts
    )
    $timestamp = (Get-Date).ToString("yyyy-MM-ddTHH:mm:ssZ")
    $entry = @"

## $timestamp | pentester | $Phase

- action: $Action
- command_or_ref: `$Cmd`
- result_summary: $Result
- artifacts: $(($Artifacts -join ', '))
- evidence_ids: []
- next:
"@
    Add-Content -Path "work/$Case/timeline.md" -Value $entry
}

Integration with Skills

The timeline-workitem tracking system enforces compliance through skill-level integration hooks. Skills must update case files after each operational phase.

• attack-chain/: Each phase conclusion requires a timeline entry and work item status update. As specified in skills/attack-chain/SKILL.md, transitioning from Recon to next phases must mark relevant work items as done.
• pentest-tools/: Tool executions must generate at least one timeline record. When evidence is discovered, corresponding work items are created automatically in workitems.md.

This integration ensures that skills remain stateless while case state accumulates in the central timeline and work item records.

Practical Usage Examples

Example 1: Manual timeline entry

Append the following block to work/acme-2026/timeline.md to record DNS enumeration:

## 2026-08-01T09:15:00Z | pentester | Recon

- action: External DNS enumeration
- command_or_ref: `dig axfr $TARGET`
- result_summary: Retrieved zone file with 112 records
- artifacts: [evidence/E-010.txt]
- evidence_ids: [E-010]
- next: Identify publicly exposed services

Example 2: Adding a work item

Insert a new row into work/acme-2026/workitems.md to track an identified issue:

| WI-015 | Insecure admin portal | pentester | https://acme.example.com/admin | web | in_progress | | |

Then update the coverage checklist to reflect pending evidence collection.

Example 3: Automated updates via PowerShell

Invoke the helper function after a successful scan:

Add-TimelineEntry -Case "acme-2026" -Phase "Recon" -Action "Service enumeration" -Cmd "nmap -sV -O $TARGET" -Result "Apache 2.4.41, Ubuntu 20.04" -Artifacts @("evidence/E-015.xml")

This instantly expands the audit trail without opening an editor.

Summary

• The timeline-workitem tracking system stores mutable case data in git-ignored work/<case>/ directories, separating engagement artifacts from skill source code.
• timeline.md serves as an immutable, append-only log using ISO-8601 timestamps and structured markdown blocks.
• workitems.md tracks task status through a markdown table with strict status values: pending, in_progress, blocked, done, or cancelled.
• skills/scripts/case-init.ps1 bootstraps new cases with standardized file templates.
• Integration hooks in skills/attack-chain/SKILL.md and skills/pentest-tools/SKILL.md require skills to update timeline and work item files after each phase.
• The plain-text format enables diff-friendly reviews and LLM-agent compatibility without specialized APIs.

Frequently Asked Questions

What is the timeline-workitem tracking system?

The timeline-workitem tracking system is a markdown-based case management framework that records every action and task status in penetration-testing or reverse-engineering engagements. It maintains an immutable chronological log in timeline.md and a tabular task tracker in workitems.md, both stored outside version control in case-specific directories.

How does the system ensure data integrity?

The system enforces an append-only policy for timeline.md where historic entries must never be edited or deleted. Corrections require appending new blocks with corrects: <timestamp> references. This creates a tamper-evident audit trail where every action remains visible, supporting compliance and forensic review requirements.

Where are case files stored in the reverse-skill repository?

Case files reside in work/<case>/ directories that are explicitly excluded from Git via .gitignore. This location houses scope.md, timeline.md, workitems.md, and subdirectories for evidence/, notes/, and report/, keeping mutable engagement data separate from the immutable skill logic tracked in the repository.

How do skills integrate with the timeline system?

Skills such as attack-chain and pentest-tools integrate through mandatory update hooks specified in their respective SKILL.md files. After completing each phase, these skills must append entries to timeline.md and update relevant rows in workitems.md, ensuring the case record reflects all tool executions and phase transitions without requiring manual documentation steps.

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