Skip to content

Where things live

The big picture: Blueprint follows one rule: decisions and progress live on the tracker; reviewed artifacts live in the repo. If a decision, deferral, follow-up, finding or progress point is not on an issue (or on an MR that closes one), it is not recorded. Local files and transcripts are scratch.

Why it matters: State kept only on your laptop or in a chat is lost when the session ends, and a teammate or a second machine cannot see it. The rule is recorded in ADR 0008.

The bottom line: Ask “would a teammate need this?” If yes, it belongs on an issue or in a doc, never only in a transcript, a local file or auto memory.

“Today” is what the current release does. “Decided home” is where the record goes once the 0.8 work lands. Rows marked ships in 0.8 describe tracker-side behavior that does not exist yet.

Thing Today Decided home Survives the session? Visible to a teammate?
Spec, features, acceptance criteria docs/specs/*.md, tied to issues by Issue: #N / Spec: lines Same (repo) Yes Yes
Architecture decisions docs/adr/, spec D-nn rows Same (repo) Yes Yes
Docs and changelog fragments docs/, website/, changelog.d/ Same (repo) Yes Yes
Follow-ups and deferrals Open issues (the mr-followups lint and the completeness-check rule enforce it) Same (tracker) Yes Yes
Gate outcomes The MR’s ## Gates ledger Same (MR) Yes Yes
Release plan ~/Downloads/dotplanning-<v>-<date>.html only A Plan: <v> issue linked from the milestone description, kept current after each kickoff question; the HTML report is an optional view of the same data (ships in 0.8) Today: on that laptop only. After: the tracker Today: no. After: yes
Plan decisions after kickoff The same HTML report, or nowhere Comments on the Plan: <v> issue (ships in 0.8) Today: no Today: no. After: yes
/wave progress The orchestrator’s transcript, plus a 🔒 checked out comment on each issue (no progress after that) One comment per issue the wave touches: spawned, model and effort, commit, MR, handed back (ships in 0.8) Today: no Today: only the check-out comment. After: yes
/pre-release findings The skill’s report, in the transcript (a deferred security finding is already filed as an issue) Filed as issues as each is confirmed, plus, for /pre-release full only, a dated summary comment on the Plan: <v> issue (audited commit, 🔴/🟡 counts, issues filed, full: true); targeted runs post nothing; /release checking it is separate (ships in 0.8) Today: no Today: no. After: yes
/voc blockers The panel report, in the transcript One comment on the feature’s issue, headed as a simulated persona panel: evidence tier, 🔴 blockers with their falsification lines, 🟡 concerns. Never the score, a per-persona verdict or an in-character quote; posted only after you confirm (ships in 0.8) Today: no. After: the tracker Today: no. After: yes
/sunset-check verdict The report, in the transcript (a Remove already ships with an issue) A comment on the issue that records the decision, or a new Sunset check: <surface> issue: the recommendation, the Step 0 state, the falsification lines; keep-and-fix gaps filed as issues as each is confirmed (ships in 0.8) Today: no. After: the tracker Today: no. After: yes
/kaizen findings The ranked report; findings filed one at a time if you said yes Each top-5 finding gets an answer: filed as an issue at once, declined in .claude/kaizen-declined.json, or left. A left finding and the report are not recorded, because the next run recomputes every signal (ships in 0.8) Filed and declined: yes. The report: no Filed and declined: yes
/incident-postmortem follow-ups A memory entry (the lesson), plus an optional process-fix issue; the report stays in the transcript Same memory entry for the lesson; every follow-up filed as an issue as it is found, and the report posted on the incident issue (ships in 0.8) Today: the lesson only. After: the tracker too Today: no. After: yes
/voc-audit boost candidates and regression classifications The report, in the transcript (its “file new” list is filed once you confirm) A boost candidate is a simulated-panel comment on the tracked issue (the priority label stays your call); a regression or new instance of a closed issue is a new issue linking it, labeled escaped-from::<MR iid> when the MR that introduced the regression is known. Each once you confirm; “already decided” needs no record (ships in 0.8) Today: no. After: the tracker Today: no. After: yes
/kickoff answers mid-run A git-ignored file, .claude/state/kickoff.json, in that checkout Same: the one allowed local state file, because the tracker does not exist yet Yes No
Lessons and traps Auto memory, per person Same, but never work state: anything a teammate needs goes to an issue or a doc Yes No
  • Tracker means issues, their comments, and the MRs that close them. It is shared and survives any session, and it needs a network.

  • Repo means files reviewed with the code and versioned with it. A spec, an ADR, a docs page and a changelog fragment each link to the issues they came from.

  • Local state files are allowed only before the tracker exists. /kickoff writes its answers locally because the GitLab project is not created yet. Everywhere else a local file is disposable.

  • Offline, tracker-backed rows in make status show ?, never a guessed ✓. make status ships in 0.8.

  • A skill that finds something files it as it goes. A finding left only at the end of a transcript is lost when the session closes.

  • Project rules do not belong in your global ~/.claude/CLAUDE.md. It loads into every session and most subagents in every project, so a copy of the fast-paths table there contradicts the repo’s own. make doctor warns when it finds one, reporting only the file’s size and never its contents.

  • Glossary for the terms used here.
  • Harness gates for the checks that enforce parts of this (the follow-up lint and the gate ledger).