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

> Learn about the timeline-workitem tracking system for case management. This guide explains how this immutable, markdown-based audit mechanism records all actions and task statuses in your cases.

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

---

**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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/timeline.md))

The [`timeline.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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:**

```markdown

## 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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/workitems.md))

The [`workitems.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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:**

```powershell

# 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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/timeline.md) and [`workitems.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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:

```powershell
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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/work/acme-2026/timeline.md) to record DNS enumeration:

```markdown

## 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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/work/acme-2026/workitems.md) to track an identified issue:

```markdown
| 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:

```powershell
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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/timeline.md)** serves as an immutable, append-only log using ISO-8601 timestamps and structured markdown blocks.
- **[`workitems.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](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) 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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/timeline.md) and a tabular task tracker in [`workitems.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md), [`timeline.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/timeline.md), [`workitems.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) files. After completing each phase, these skills must append entries to [`timeline.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/timeline.md) and update relevant rows in [`workitems.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/workitems.md), ensuring the case record reflects all tool executions and phase transitions without requiring manual documentation steps.