Use when creating, decomposing, claiming, closing, or blocking on a work item (bead) — and whenever the words "deferred", "out of scope", or "follow-up" are about to leave your mouth. Defines bead anatomy for agent consumers, the standing meta-beads, follow-up capture, dependency hygiene, and the tracker as an inter-session message bus.
81%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Passed
No findings from the security scan
The bead graph is the single source of remaining work. If it isn't a bead, it won't get done — a deferral living only in a close-reason, code comment, or your head has no tracker home and rots silently. Field evidence: a 92-bead port closed 74 of them in four days with near-zero re-litigation, because the tracker carried not just the work but the conversation between sessions.
What-not-how, but "what" done properly is dense. The recurring sections, in order:
Two sections a second field project proved out, worth adding when the work has design risk:
Code sketches in a bead are illustrative, not binding. The implementer may deviate — and must argue the deviation in the commit body ("heeded the bead's Risk guidance: helper functions, NOT a strategy trait; a closed shape in one place beats an open trait").
A ~100-character bead is a backlog stub, not implementable work. Stubs are fine as markers; enrich to the anatomy above before pickup, never implement from a stub.
A bead that names a target location is making a structural claim, and structural claims get verified against the actual dependency graph — twice: by the author at writing time, and by the implementer at start time. When they conflict, the structural rule beats the bead text; override and document the deviation in the commit body, then correct the bead. Field cost of skipping the author-side check: a placement the dep-matrix lint forbade, discovered mid-epic, paid for with an unplanned "slice 1.5" relocation commit. Two specific checks before writing a placement into a bead:
file:fields that encode the project's
reason-for-existing and must never flip, each cross-linked to the gate
that enforces it (quality-gates). An amnesiac reads this bead before it
can regress the one thing that matters; every other bead links it
instead of repeating it.This is how per-bead descriptions stay lean without losing context: shared context has exactly one home.
When you say "deferred", "out of scope", or "follow-up": stop. Either (a) confirm an existing bead covers it — by searching the tracker, never by assuming — or (b) create one, with full anatomy and correct deps, before closing the current bead. Reference the new bead's id in the close-reason. No exceptions; this rule is the difference between a tracker and a diary.
Three field-proven mechanisms:
FOUNDATION WARNING (found while doing X) block to that bead: the
discovered constraint, an explicit "do NOT blindly attempt Y", the
enumerated options (a)/(b) with the decision left to the implementer,
and a pointer to any proven reusable technique.
Mark each claim VERIFIED (with evidence) or SUSPECTED. An unverified
warning recorded as fact once drove a wrong out-of-scope decision that
cost a correction commit, doc rewrites, and two new beads.br ready --json.
A mislabeled dependency hiding ready work is the highest-value thing a
triage pass can find.blocks, parent-child, discovered-from) over
prose provenance where the tracker supports them — prose works but is
unqueryable. In practice discovered-from is the one everyone forgets.scripts/tracker-audit.bb [issues.jsonl] checks the JSONL mirror
directly (no tracker CLI needed): open epics whose children are all
closed, closed deferrals whose close-reason cites no bead id (accepts
short id suffixes — that's how close reasons actually cite), dangling
dependency edges, and still-open stub beads. The deferral check has a
known false-positive mode ("deferred to the render adapter" — placement,
not work); triage by hand, don't tune it away.
Every bead mutation is its own scoped commit (beads: scope): a one-line
JSONL diff with a full rationale body. The tracker's own history becomes
an auditable decision log — who decided what, when, and why, replayable
with git log. Never bundle tracker mutations into feature commits.
igouss/gitweb-rs
9ef2429
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.