# How Does the timeline-workitem.md Structure Track Analysis Progress Across Sessions?

> Discover how timeline-workitem.md tracks analysis progress across sessions. Learn about its append-only log and mutable coverage table for a resilient audit trail.

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

---

**The timeline-workitem.md structure implements an append-only chronological log paired with a mutable coverage table to create a Git-friendly, session-resilient audit trail that survives across multiple analyst sessions and tool invocations.**

The zhaoxuya520/reverse-skill repository defines a standardized methodology for managing complex reverse engineering investigations through pure text artifacts. By implementing a two-layer record-keeping model in [`skills/ops/timeline-workitem.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/timeline-workitem.md), the system captures both chronological actions and work item coverage while remaining fully diffable and parseable by automated agents.


## Directory Convention: Isolating Case State in work/<case>/

All operational state for a single investigation lives under `work/<case>/` (e.g., `work/acme-2026/`). According to the specification in [`skills/ops/timeline-workitem.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/timeline-workitem.md) lines 6-13, this folder is git-ignored, keeping volatile operational data separate from version-controlled skill definitions. This isolation ensures that binary evidence, temporary analysis outputs, and session logs never contaminate the repository's main history while remaining locally accessible for continuity.


## The Append-Only timeline.md: Immutable Session History

At the heart of the progress tracking system sits [`timeline.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/timeline.md), an append-only markdown log where each analytical step becomes a new heading following the strict format `## {ISO-8601} | {role} | {phase}` (lines 24-38 in [`skills/ops/timeline-workitem.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/timeline-workitem.md)). Every entry contains a fixed schema of fields including `action`, `command_or_ref`, `result_summary`, `artifacts`, `evidence_ids`, `decision_delta`, and `carry_forward_refs`.

```markdown

## 2026-08-28T14:35:00Z | cie | static_analysis

- action: Run static analysis on binary `sample.exe`
- command_or_ref: `./binwalk -e sample.exe`
- result_summary: Extracted embedded ELF sections
- artifacts: [evidence/static-analysis-output.txt]
- evidence_ids: [E-045]
- decision_delta: [phase=triage->static]
- carry_forward_refs: [scope.md, workitems.md]
- next: |
    Continue with dynamic analysis on identified modules

```

This format ensures that every tool invocation, decision, and evidence reference is permanently recorded with microsecond precision and role attribution.


### Enforcing Immutable History with Correction Chains

The specification mandates that existing `##` blocks must never be edited after creation (line 40). When analysts need to correct previous entries, they append new timeline entries that include a `corrects:` reference pointing to the erroneous timestamp. This creates an immutable audit chain that preserves the complete analytical thought process, including false starts and remediations, which is critical for forensic reproducibility.


### Recording Decision Deltas to Minimize Log Bloat

Rather than duplicating entire authoritative documents, the `decision_delta` field (lines 42-50) captures only the differences between the previous state and the current state. For example, when transitioning from `phase=triage` to `phase=static`, only this change is logged, not the full contents of [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) or [`workitems.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/workitems.md). This lightweight approach keeps the timeline readable while maintaining a complete record of decision points.


### Carry-Forward References for Context Reconstruction

To enable session resumption without storing redundant data, entries utilize `carry_forward_refs` (lines 36-38) to point to unchanged authoritative files like [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) or [`workitems.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/workitems.md). When an analyst returns to a case, they follow these references to reconstruct the full contextual snapshot, then apply the logged `decision_delta` to reach the current state. This reference-based architecture prevents the timeline from ballooning with duplicated static content.


## The workitems.md Coverage Table and Milestone Checklist

Complementing the timeline, [`workitems.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/workitems.md) maintains a structured markdown table (lines 55-62) enumerating individual work items with columns for ID, title, role, targets, surface, status, evidence, and notes. Below this table, a `## Coverage` section contains a checklist of high-level milestones such as "Recon complete", "Critical/High candidates triaged", and "Timeline continuous" (lines 65-71).

```markdown
| WI-003 | Dynamic analysis of network module | cie | 10.0.1.5 | network | in_progress | E-045 | |

## Coverage

- [x] Recon complete for in_scope assets
- [ ] Critical/High candidates triaged
- [ ] Validated findings have Evidence
- [ ] Path documented (attack/call/solve)
- [ ] Timeline continuous (no silent gaps >1 major phase)

```

This dual structure tracks both granular task progress and phase-level completion criteria, providing clear "done" signals before generating final reports.


## Resuming Analysis Across Sessions: The Rehydration Workflow

The session-spanning mechanics rely on the separation between immutable history and mutable state. When resuming work:

1. **Rehydrate context** by reading the latest [`timeline.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/timeline.md) entry, following `carry_forward_refs` to reload the authoritative snapshot, and applying pending `decision_delta`s.

2. **Append new actions** by adding a new `##` heading with updated fields and evidence references.

3. **Update coverage** by modifying the [`workitems.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/workitems.md) table status and checking off completed milestones in the coverage checklist.

4. **Preserve evidence** by dropping new files into the `evidence/` subdirectory and referencing them in the timeline entry's `artifacts` array.

Because [`timeline.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/timeline.md) is strictly append-only and [`workitems.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/workitems.md) uses explicit status fields and checkboxes, analysts can safely stop and resume investigations at any point without losing continuity. The checklist ensures that critical phases like "Evidence validated" and "Path documented" are eventually completed regardless of how many sessions the analysis spans.

According to lines 85-87 in [`skills/ops/timeline-workitem.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/timeline-workitem.md), the pure text design enables diff-based reviews, automated parsing by agents, and straightforward integration with the tool-index commands. No live sockets are required; the timeline can be copied into reports or fed to downstream generators when needed.


## Summary

- The [`timeline-workitem.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/timeline-workitem.md) structure in zhaoxuya520/reverse-skill uses an append-only [`timeline.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/timeline.md) log and a mutable [`workitems.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/workitems.md) coverage tracker to maintain state across sessions.
- Case data is isolated in `work/<case>/` directories that are git-ignored, separating operational artifacts from skill definitions.
- Timeline entries use `decision_delta` to log only changes and `carry_forward_refs` to reference static context, preventing log bloat.
- Immutable history is enforced through append-only semantics; corrections are chained via `corrects:` references rather than edits.
- The coverage table and milestone checklist in [`workitems.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/workitems.md) provide granular task tracking and phase-level completion signals.
- Pure text formatting enables diff-based reviews, automated agent parsing, and straightforward integration with tool-index commands.


## Frequently Asked Questions

### What is the exact format for a timeline.md entry?

Each entry begins with an ATX heading `## {ISO-8601} | {role} | {phase}` followed by a bulleted list of fields including `action`, `command_or_ref`, `result_summary`, `artifacts`, `evidence_ids`, `decision_delta`, `carry_forward_refs`, and `next`. This structure is defined in [`skills/ops/timeline-workitem.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/timeline-workitem.md) lines 24-38 and ensures consistent parsing by both humans and automated tools.


### How does the structure handle mistakes or corrections in the analysis?

Rather than editing existing `##` blocks, analysts append new entries containing a `corrects:` field that references the timestamp of the erroneous entry (line 40). This creates an immutable audit trail that preserves the complete analytical history, including corrections, which is essential for forensic reproducibility and maintaining the integrity of the timeline-workitem.md structure across sessions.


### Why use carry-forward references instead of copying the full state?

The `carry_forward_refs` mechanism (lines 36-38) points to unchanged authoritative files like [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) rather than duplicating their contents. This keeps the timeline lightweight and readable while allowing analysts to reconstruct the full contextual snapshot upon session resumption. It prevents the log from ballooning with static data that rarely changes between sessions.


### How does workitems.md differ from timeline.md in tracking progress?

While [`timeline.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/timeline.md) provides an immutable chronological record of every analytical action, [`workitems.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/workitems.md) offers a mutable, tabular view of current task status and phase completion (lines 55-71). The timeline answers "what happened and when," while the work items table answers "what is the current state of coverage," making them complementary tools for tracking analysis progress across sessions.