Skip to content

Issues are the unit of work

The big picture: Nothing starts from a prompt. Every change starts from a tracked issue.

Why it matters: An issue is the written agreement about what “done” means. Without one, nobody — human or agent — can later check whether a change did what was asked. And three separate mechanisms in this harness key off the issue number.

  • scripts/wt new 1234 looks up the issue title and derives the branch name (feat/1234-<title>) and worktree path from it.
  • scripts/check-issue-collision.sh reads the issue number back out of the branch name on every push, and blocks the push if that issue already has an open MR from another branch. It works however the branch was created, including a plain git checkout -b.
  • Closes #1234 in the MR description is what actually closes it on merge. Without the keyword the issue stays open and the tracker silently drifts from reality.
Terminal window
glab issue list --assignee @me # what is mine
glab issue view 1234 # read it — including the COMMENTS
scripts/wt new 1234 # branch + worktree; labels it status::wip
cd ../<repo>-wt/1234-short-slug && source .envrc
# ... work, with the gate chain from the fast-path table ...
/mr # opens the MR with Closes #1234
# ... merge when green ...
scripts/wt prune # from the main checkout

Read the comments before starting, not just the description. A stale branch or a half-done attempt is usually recorded there and nowhere else.

  • One issue, one acceptance criterion set. If a discussion surfaces a second problem, file it. A facet recorded as a comment on an open issue is not tracked — it dies the moment the host issue closes on a different facet. The test is simple: does it need its own acceptance criteria? Then it needs its own issue.
  • Labels are load-bearing, not decoration. The claim label (status::wip by default) is applied by scripts/wt new / wt claim and cleared by wt prune, wt remove (once the issue is closed) and wt release; /wave skips issues that carry it unless they are your own leftovers, which its resume step (Step 1b) classifies first and offers to resume, hand back or release. The collision gate (WIP_LABEL) and wt (WT_LOCK_LABEL) read the same default — if you rename it, set both. The gate warns when a pushed branch’s issue carries it but has no MR yet. Priority labels are read by /voc-audit when it decides between “file new” and “boost priority”.
  • Beware label gates that read the tracker rather than the repo. If you add a CI job that fails on a forbidden label, remember its input is not your diff — someone else’s label edit can redden the default branch, in a job log the next person to push has no reason to read. Scope such gates narrowly and say so in the job comment.
  • Milestones drive /dotplanning. It resolves a milestone’s scope into a feature→asset map and flags every screen, endpoint, or decision with no issue behind it. An empty milestone gives you an empty plan.
  • Blueprint itself uses plain committed / uncommitted labels and no dated milestones; an agent asks before moving an issue between them. Projects that do run dated milestones can add the scheme below.
  • A dated milestone is a promise, so every issue in one states its share of it. One scoped label per issue — release::committed (ships or the release slips, and the only issues that become roadmap bullets), release::reserve (a slot held for inbound work from real users), release::stretch (ships if there is time, moves at feature freeze). Scoped labels are mutually exclusive, so the tracker enforces the “exactly one” part. An agent asks which applies on every move into the milestone and never infers it: a guessed committed is a promise nobody made, and a guessed stretch quietly drops work someone meant to ship. Unanswered means unlabeled and said out loud — an unlabeled issue in a dated milestone is a visible gap, a guessed label is an invisible one.

Tagging escapes, and what the yield numbers show

Section titled “Tagging escapes, and what the yield numbers show”

When a bug turns out to have been introduced by a merged MR, label the issue escaped-from::<MR iid> (a scoped label, one per issue). The Bug template and /incident-postmortem both ask for the originating MR, and /tracker-hygiene lists bugs that name an MR without the label.

scripts/gate-yield.py (called by /kaizen) reads the ## Gates ledger of recent merged MRs and joins those labels to it. It reports per gate how often the gate ran, how often it found something, and on MRs that later escaped a defect, whether it ran and reported 0 findings. It also reports cost and turns per merged MR by change class, from the optional cost: usd <N>, turns: <N>, subagent-tokens: <N>, orchestrator-tokens: <N>, est-cost-usd: <N.NN> (a list-price estimate) and budget-exceeded: <N> ledger lines (the last counts agents that exceeded their /wave budget) and a blockers <k> field in a gate line’s parenthetical (reported as blocker-yield). Per-MR estimated cost is not read from the est-cost-usd: line: it is the sum of the MR’s windowed ## Cost of this MR records (each record’s Allocated: figures when it has that line, its Total row otherwise; see below), and an MR without a usable record is excluded and counted. gate-yield.py also reports the MRs whose subagent-tokens: is above twice the median of the MRs read, as an outliers block, once at least 5 MRs carry the line. Run it offline against saved MR data with --from-json <file>.

Escapes are also reported per fast-path class. An MR declares its class with a change-class: <slug> line in its ## Gates section (for example bugfix, docs, feature; a, b for a union). The script reads which gates that row requires from the fast-paths table in CLAUDE.md, so each gate shows, over escaping MRs, whether it was required and ran, required and clean, or required and did not run. An MR without the line is reported as unmapped, not guessed from its title. python3 scripts/gate-yield.py --check-fastpath fails when the table and the slug list drift.

python3 scripts/gate-yield.py --spec-trace reads the same merged MRs for the spec intake: per imported spec, the issues imported with an Override:, the share of MRs whose ## Requirements table differs from the spec’s acceptance criteria at the version the issue names (read from git history, so a spec edited after the import is not drift; an MR with no Requirements table, one closing several spec-traced issues, or a version missing from history is listed and left out of the share), and the spec-review find-rate. Drift is a prompt to read the texts, not a defect count.

What the numbers do not show:

  • Yield is not value. A gate that has never found anything may be deterring the defect by existing, and a high-yield gate can still be missing the class that matters.
  • An escape nobody tagged is invisible. The escape column is only as complete as the tagging. With no tagged escapes the report says “0 tagged escapes — escape rate not yet measurable”; that is not a 0% escape rate.
  • A gate never required for a class reads 0 escapes there by construction, and the declared class is the author’s own claim. The backticked pre-MR gate batch expands to regression-check only; the diff-conditional perf-check, rbac-check and the like read 0 for the backend, feature and trust-boundary rows.
  • req-notrun is the process escape, with a caveat. A conditional gate (such as test-scaffold “if no coverage”) counts as required, so an absent one shows as req-notrun even when its condition was false.
  • The slug list is a hand-maintained hint. python3 scripts/gate-yield.py --print-fastpath is the authority.
  • Cost is what the MR reported, not a bill. MRs without a cost: line are left out of the cost columns rather than counted as free.
  • A disabled ledger is not 0 and not a drop in cost. An MR with cost-ledger: off has no cost or token lines; it is left out of those columns, so a stretch of off MRs shows as disabled, never as cheaper work.
  • The ## Cost of this MR comments are the per-MR cost record. The PostToolUse hook posts record 1 with scripts/cost-table.py when the MR is opened, so a person can read one MR’s tokens and estimated cost at a glance, and each later window of work on the MR (a fix round, a /fix-mr pass) adds a numbered record with a running total, never an edit of an earlier one. gate-yield.py reads the ## Gates lines for gates, turns and subagent-tokens:, but takes per-MR estimated cost from the windowed records themselves (notes by the token user or the MR’s author only, strictly parsed; macrodream/blueprint#390), so a ## Cost of this MR note by anyone else excludes the MR: it is left out of the cost means and counted. So does a record posted with no session cost state (a session’s first record, or a state file that was lost), which says its window starts at the session’s start and may count tokens another MR’s record counts (macrodream/blueprint#391). The comments follow the same cost-ledger setting and are absent when the ledger is off.

People who use Blueprint, and are not in your tracker’s daily flow, can file a Feedback issue from the template in .gitlab/issue_templates/Feedback.md. The Giving feedback guide shows them the steps.