track-session

Session Progress

Overview

Track multi-session work in SESSION_PROGRESS.md at the project root so work can pause and resume without a context rebuild. The file is only worth having if it matches reality, so checkpoint as work happens — after a completed task, a plan change, a failure, or before asking the user a question — rather than waiting to be told to save.

The cc-dash dashboard ingests this file, which is why the frontmatter schema and the HTML id markers below are load-bearing rather than decorative.

File format

---
schema: cc-dash/session@1
project: project-name
session_id

## Plan and ## Current Status are load-bearing; ## Decisions, ## Failed Attempts, and ## Completed Work are optional — add them when there's something real to record.

Length: one line per task; Decisions and Failed Attempts get 1–2 sentences each. The file is a state record, not a narrative — no filler sections, no restated summaries, no recap of work already listed under Completed Work.

What must survive a context reset, in priority order: problems that came up and how they were resolved (Failed Attempts); options raised, tried, or set aside, and why (Decisions); anything the user asked for, ruled out, or set as a constraint, stated close to their own words; exactly where things stand (Current Status); what is still open or promised (Plan); and details that are hard to reconstruct — names, numbers, exact wording, links — kept exact. Be complete on these even at the cost of length. Condense your own reasoning to what it concluded.

IDs: t_ (task) or f_ (failed attempt) plus 1–20 [a-z0-9_-] chars — five random chars by default, or a mnemonic slug (t_redis-mw, t_authfix). The same shape applies to task: and ref:, which each take exactly one id. roadmap_ref takes exactly one roadmap id; when a session advances several features, name the others under ## Current Status. Keep an id stable once written, because dep: references point at it. Every plan item carries an id and a dep (dep:none or dep:t_XXXXX).

Log every failed approach with its reason so it isn't blindly retried. When a failure was environment-scoped — an MCP server not connected, missing credentials, a service down — say so in the entry; a later session may have a different environment, so re-checking it is correct rather than a repeat.

Workflow

Routing a bare invocation

On /track-session with no argument, take the first branch that matches and stop:

1. No SESSION_PROGRESS.md at the project root → Start. Don't rebuild one from the roadmap or git history; that is recover, and only on request.
2. File exists and this conversation has produced work the file doesn't record yet (edits, test runs, decisions since its last_updated) → checkpoint, then keep working.
3. File is status: completed → say the last session closed and what it finished, then hand off to /track-roadmap resume to pick the next feature, or to Start if the user already named the new work.
4. Otherwise — fresh context, the file is the only record → Resume.

The discriminator is unrecorded work in the current conversation, not how finished the file looks. Use it as a tiebreak whenever branches 2 and 4 both seem to fit: checkpoint. Writing a near-empty delta costs one turn, whereas resuming on top of unrecorded work drops it from the file and hands the next session a stale plan.

Start mode

Derive project: from the repo (folder name, package.json, pyproject.toml) rather than inheriting it from a file you're about to overwrite. Stamp started and last_updated from the clock (see Checkpoint), set status: in-progress, and write at least ## Plan and ## Current Status.

If a SESSION_PROGRESS.md already exists, read it, then check whether git tracks it — that determines whether replacing it is reversible:

• Same work, unfinished → this isn't Start, it's Resume. Stop here.
• Tracked, and the prior session is completed/paused and unrelated → confirm with the user, then replace the file; git holds the old copy.
• Untracked or gitignored → archive to SESSION_ARCHIVE_<topic>.md first, then write the clean file. Replacing an untracked file destroys it permanently; public repos commonly gitignore SESSION_PROGRESS.md on purpose. When they do, offer to add SESSION_ARCHIVE_*.md to .gitignore too, so the archive doesn't become the thing that leaks.

Checkpoint (bare invocation) and Save

Both write the current state into the file: tick completed tasks, update ## Current Status, append decisions and failed attempts, re-stamp last_updated. The only difference is what happens next — a bare /track-session checkpoints and keeps working, while /track-session save checkpoints and stops.

Take every timestamp from the clock rather than estimating it, because a guessed stamp drifts by hours and the dashboard's staleness view trusts it:

When the last plan task is ticked, set status: completed in the same write and tell the user the session is closed. A finished file left in-progress shows as active work on the dashboard indefinitely.

Resume mode

Read the file, then lead the reply with where things actually stand — status, tasks done out of total, working-tree state, last commit, and the next action — before any fresh analysis. Handoffs that open with narration ("I'll read the session file now, then look at the tests") bury the state the user came back for, and they end up re-deriving it themselves.

Resume is also the natural reconciliation point: if project: or status: have drifted from reality, fix them in place while you're there.

Verify and Recover — load on demand

• /track-session verify confirms [x] tasks actually meet their requirements — read the files, run the tests, tie each claim to evidence from this run, and append a ## Verification Results section, which cc-dash renders on the session page. Load reference/VERIFICATION.md when the user asks to verify, or when ticked boxes are the only evidence the work is done.
• /track-session recover rebuilds a deleted SESSION_PROGRESS.md from the Claude Code transcript. Load reference/RECOVERY.md when the file is missing and the user wants it back — it carries the transcript-slug derivation and a tested Python reconstructor, which the reference explains is necessary because jq mis-parses these transcripts.

Examples

✅ Specific and resumable:

❌ Too vague to resume:

✅ A resume reply that opens with state:

❌ A resume reply that opens with narration:

✅ A failed attempt that won't be blindly retried:

❌ A failed attempt that will be retried:

✅ Every good version names the file, the id, and the reason; every weak one makes the reader rebuild context from scratch.

Gotchas

• Only the top frontmatter block is parsed. Anything below a second --- is invisible to cc-dash, so a file with stacked sessions silently reports only the newest one.
• SESSION_PROGRESS.md is gitignored in many public repos, which makes "just replace it, git has the history" false there. Check git ls-files --error-unmatch before replacing, and archive first when it comes back non-zero.
• cc-dash drops an entry whose id doesn't match, with a warning, and keeps the rest. A comma list in ref: or roadmap_ref, or an id with a space or capital, loses that one entry or link from the dashboard. Fix the malformed value, but don't rewrite valid mnemonic ids into random tokens — renaming an id orphans every dep: pointing at it.
• Re-stamp last_updated on every write. The dashboard's staleness view keys off it, so a checkpoint that skips the stamp makes active work look abandoned.
• save stops work. Users who type it mid-flow expecting a checkpoint then wonder why you halted; a bare /track-session is the one that checkpoints and continues.
• save with subagents still running doesn't stop them. Their results arrive after you've said you stopped. Name each in-flight agent and what it's doing under ## Current Status, and tell the user results will still land, so the next session knows to look for them.
• Other headings are kept but not shown. cc-dash displays Plan, Current Status, Decisions, Failed Attempts, Completed Work and Verification Results; a ## Notes section survives on disk but never reaches the dashboard. Put a finding that should outlive the session on the linked roadmap item as a quoted note (see track-roadmap) rather than in an invented section.
• One file per repo, at the root. Work in a subdirectory (a godot/ or web/ folder) still checkpoints to the root file; a second SESSION_PROGRESS.md deeper in the tree splits the record and the dashboard reads only one.
• Write the file with Edit or Write, not a Bash heredoc or sed -i. recover rebuilds the file by replaying Edit and Write calls from the transcript, so an update made through Bash is invisible to it.
• Recovery rarely finds a clean blob. Because updates are incremental Edits, the transcript usually holds no full Write — expect to replay edits over the latest snapshot rather than lifting one copy out.

Integration

• track-roadmap — pick a feature from the roadmap, then link its implementation here via roadmap_ref: r_XXXXX. Research, open questions and rejected alternatives that matter beyond this session go back to that roadmap item as quoted notes before the session closes.
• Checkpoint between commits and test phases, so the file's state lines up with a commit boundary a later session can git show.

See reference/TROUBLESHOOTING.md for resume failures, oversized session files, and verify edge cases.