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

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, 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//

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 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, 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). Every entry contains a fixed schema of fields including action, command_or_ref, result_summary, artifacts, evidence_ids, decision_delta, and carry_forward_refs.

## 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 or 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 or 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 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).

| 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 entry, following carry_forward_refs to reload the authoritative snapshot, and applying pending decision_deltas.

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

3. Update coverage by modifying the 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 is strictly append-only and 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, 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 structure in zhaoxuya520/reverse-skill uses an append-only timeline.md log and a mutable 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 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 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 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 provides an immutable chronological record of every analytical action, 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.

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