| name | plan-tracking |
| description | Use when starting or ending a work session in saminn-background-check, after finishing a phase or a source/subsystem branch, or whenever the project's current phase, branch, or next step changes — so docs/plan/ never goes stale. |
Plan Tracking
Overview
docs/plan/ is the project's living memory across sessions. Three files, three roles. The
core rule: append a dated entry to last-point.md every session (newest first, never
overwrite) and tick the dated Daily work log in execution-map.md, so the accumulated
history shows progression and the next session resumes without guessing.
| File | Holds | Each session |
|---|
docs/plan/plan.md | goal, locked architecture/stack, dev process (the pipeline), phase roadmap | rarely — only when the strategy changes |
docs/plan/execution-map.md | session playbook + CURRENT PHASE + the dated Daily work log | tick the Daily work log; update CURRENT PHASE when the phase advances |
docs/plan/last-point.md | dated state checkpoints (append-only, newest first) | append a new dated entry (never overwrite) |
When to use
- Session START: read
last-point.md → execution-map.md → plan.md to orient (do this
before touching code).
- Session END, phase/branch change, or after finishing a source or subsystem: update the docs (below).
How to renew (the procedure)
last-point.md — ALWAYS append a new dated entry at the TOP. A ## <YYYY-MM-DD> block
with: Branch, Phase, a short State summary, Done this session, Next,
Blockers/notes. Never overwrite older entries — the accumulated history is the point.
Use today's real date; be concrete (file paths, branch names, source/pipeline-stage, test status).execution-map.md — ALWAYS tick the Daily work log. Mark completed items - [x] (start a
new ### <YYYY-MM-DD> block if it's a new day; carry unfinished items forward). AND if the
phase advanced, update the CURRENT PHASE section + its next-action checkboxes.plan.md — ONLY if the strategy/roadmap itself changed (e.g. a phase was added/reordered,
a process rule changed, a locked stack/architecture decision changed). Transient state never goes here.- Consistency check: the phase named in
last-point.md, execution-map.md, and plan.md
must agree. Locked architecture/stack/source decisions live in the docs/ reference files
(ARCHITECTURE.md, TECH_STACK.md, SOURCES.md, ADDING_A_SOURCE.md) — link, don't restate.
- Commit the doc updates following
.claude/skills/commit-style/SKILL.md
(docs(repo): ... or docs(sources): ..., explicit git add docs/plan/...).
Quick reference
- Resuming work? → read
last-point.md first.
- "What phase are we in / what's next?" →
execution-map.md → CURRENT PHASE.
- "What did we decide and why?" → the
docs/ reference files (architecture, stack, sources), not these.
- "How do I add a county?" →
docs/ADDING_A_SOURCE.md (the pipeline), not these.
Common mistakes
- Overwriting
last-point.md instead of appending a dated entry → you lose the progression.
Always add a new ## <date> block at the top and leave older ones intact.
- Ending a session without updating the docs → the next session is lost. Always append + tick.
- Putting transient state in
plan.md → it belongs in last-point.md; plan.md is stable.
- Letting the three docs disagree on the current phase → run the consistency check.
- Restating architecture/stack/source detail here → link to the
docs/ reference files instead.
- Forgetting to commit the renewed docs → the memory only helps if it's committed.
