author-brief
Author and structure a phase plan as self-contained briefs organized into dependency waves, with a critical path and mappings to delivery milestones. Use this WHENEVER the user wants to plan multi-step work and split it up: "break this into briefs and waves", "create a phase plan", "do for phase N what we did for phase 1", "this brief is too big, split it", "turn this into tasks with dependencies", or when scoping a body of work that several people/agents will pick up. Encodes a brief format (Wave / Depends-on / Unblocks / Effort / Deliverables / DoD), a phase-README status-table + critical-path + dependency-wave layout, and the lesson that you must verify the REAL blocker at the head of the critical path rather than assume it. Prefer this over inventing an ad-hoc plan shape.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-15
- Stars
- ★ 7
- Forks
- 5
01 前言 Front Matter
- name
- author-brief
- description
- Author and structure a phase plan as self-contained briefs organized into dependency waves, with a critical path and mappings to delivery milestones. Use this WHENEVER the user wants to plan multi-step work and split it up: "break this into briefs and waves", "create a phase plan", "do for phase N what we did for phase 1", "this brief is too big, split it", "turn this into tasks with dependencies", or when scoping a body of work that several people/agents will pick up. Encodes a brief format (Wave / Depends-on / Unblocks / Effort / Deliverables / DoD), a phase-README status-table + critical-path + dependency-wave layout, and the lesson that you must verify the REAL blocker at the head of the critical path rather than assume it. Prefer this over inventing an ad-hoc plan shape.
02 资源文件 1
- 参考文档component.yaml572 B
03 SKILL.md 正文
Author Brief
A stream board's Briefs table is a derived, generated surface once statusgen is wired up — a
brief states the authoring facts and the edges
(why:, depends, unblocks, gate, risk); it never states the lifecycle cell, and no one
hand-edits the generated table.
Model-tier gate (check BEFORE anything else)
Brief authoring and work decomposition are design-tier work: this is where risk gates are derived, dependencies mapped, and the critical-path head verified — errors made here COMPOUND through every downstream implementer and review cycle, unlike implementation errors, which gates catch. Therefore:
- If you are a fast/cheap-tier model (a haiku-class or equivalent economy tier): STOP. Report which model you are and tell the user to switch to a strong-tier session or escalate the authoring to one. Do not author anyway — not for "just a small brief set", not as a "draft for review", not because the user seems in a hurry. A cheap draft anchors the strong model that reviews it; refusing is the cheaper path.
- If you are dispatching this work to a subagent: use the most capable model available for authoring/decomposition — never an economy tier. (Implementation is the inverse: cheap implementers behind strong gates.)
Planning multi-step work follows a consistent shape: a phase README that holds a status table, a
critical path, and dependency waves, plus one self-contained brief per unit of work. The
point of the structure is that any single agent can pick up a brief and execute it without re-reading
the whole plan, and the reader can see at a glance what blocks what. Match the phase docs already in
the repo — don't invent a new format. If a project-level author-brief skill exists in the current
repo (.claude/skills/author-brief/SKILL.md), read it after this skill and apply its specifics —
paths, docs-regen commands, and local examples layer on top of this methodology.
Bind implementation pickup to current context
Read the implementation pickup procedure. Specs and briefs identify the selected target/transition, semantic contracts and applicable project engineering guidelines by canonical pointer. Include their pickup/resume assessment in the implementation handoff; record revisions, coverage and continue/adapt/hold rather than assume the authoring snapshot is still current. Use the shipped context operation where the installed version supports it (see the supported version below); otherwise use the explicit manual bootstrap. Do not rewrite completed Evidence or let a draft proposal veto approved work.
Consume the context handoff before opening the PR
When the spec hands over a context receipt, the brief PR answers it:
- Recheck the receipt against the current snapshot with
statusgen context recheck --snapshot DIR receipt.json. Reconcile (exit 1) or resolve the hold (exit 3) before authoring on it. - For each impact you dispose
amend, write the candidate brief patch, a single-file unified diff against the brief's current revision, and record the obligation in the receipt'samendmentswith that patch's base revision and digest. Bind every obligation in anamendment-manifest-v1file: owning brief, action, delivery paths, test commands, active-work treatment, and the patch or follow-up brief it binds to. - Run
statusgen context check --snapshot DIR receipt.json manifest.json PATCH...and open the PR only on exit 0. Anamendobligation without a patch is a failure, not a note: the receipt's own validation refuses it. Fix a refusal (exit 1) or a hold (exit 3); never waive it in the PR body. - The existing rules still apply: author
consumers:,depends:/unblocks:and the Verify table as below. A patch never edits populated Evidence or a dated source account, and a delivered brief takes a linked follow-on instead of a patch. - Keep product and architecture bindings separate: carry each brief's
outcomeandoutcome-revisionunchanged unless the spec moves them, and never drop the revision the work was first selected against.
Supported version. statusgen context discover, statusgen context recheck and
statusgen context check, with the context-handoff-v1 and context-handoff-v2 receipts and
the amendment-manifest-v1 file, ship in Assay v1.0.55 and later. The product-binding
extension, context-handoff-v3, ships in v1.0.63 and later. statusgen context --help
lists the verbs an install has.
Manual bootstrap. When the installed statusgen lacks the verb, or lacks the
product-binding extension while briefs bind outcome-revision, follow the
implementation pickup procedure by hand: record
the impacted briefs, their revisions, coverage and each amendment obligation in the handoff,
and say that it is a manual bootstrap. Never invent a receipt or a schema version the
install does not ship.
Map work to delivery milestones
When the source defines delivery milestones or the request needs staged outcomes,
read the shared milestone authoring procedure,
including its support check and Author-brief section. Map existing/new briefs to
<stream>:m-<NN> outcomes and criteria; prefer <stream>:b-<NN> for new briefs
with optional @<brief-version> on references; use full
<cell>:<repo>:<stream>:b-<NN> IDs in brief definitions. Once the pinned generator
and required readers support brief §3.8, write colon-only forms and preserve legacy
aliases as compatibility reads. Until then use
supported legacy IDs for executable briefs and b- labels in scoping proposals;
disclose the limitation. Do not rewrite existing identities or Evidence. Membership is
owned by the milestone, not a second brief field. Separate actual brief start needs
from prerequisites for final outcome acceptance. If the source lacks a consequential
outcome/scope decision, reconcile it with author-spec before committing affected work;
continue independent authoring. Unsupported declarations remain proposals, not live YAML.
For a source using simulated dependencies, apply the shared procedure's Outcomes delivered with simulated dependencies section. Preserve its real/substitute matrix and evidence limits in the affected briefs. Separate profile setup, contract/fake work and the joined real-consumer qualification where they have different owners; record actual producer prerequisites rather than adding another controller to hide a gap.
The most important judgment call: find the REAL head of the critical path
The critical path is the chain that, if it slips, slips everything. The recurring failure is putting the wrong item at the head — sequencing work behind a step that is itself blocked. (Concrete shape of the failure: a plan listed Brief B → Brief A as the unblock, but both were dead-on-arrival until an upstream bug — tracked elsewhere — was fixed; that bug was the true head and wasn't even in the path.) Before you finalize the order: for each "smallest unblocking move," verify it actually works — check the code/config/bug tracker, don't assume. If a proposed first step depends on something unproven, that something is the real head. Say so explicitly. The requester's stated edges are a claim to check, never the evidence for the head, and the check is done now, while you author — never left to brief 01's Task. Do it against what you can read in this session: the code, config or tracker when you have them, and always the requester's own words and the material you were handed. Test each stated edge there: does the step it puts first rest on anything that text does not establish? A run without repo access still has that text, so "I could not read the repo" names what you did not look at; it is never the check. State the head in one passage, in your own prose, that names it, quotes the line the check rests on with where it came from, and says what that line showed, in one of two forms: "I verified <X> is the real head by reading <source>: '<line>'; it showed <what>", or "<source> says '<line>', which does not establish <what>. <X> is unproven, so it is the real head: brief 01 settles it". "That makes 01 the head", "established from the stated edges", and an "unproven" with no line read and quoted state no check.
Carry quality obligations into execution
Carry applicable quality attributes and cost-model obligations from the controlling spec into the brief's existing Context, Task, DoD and Verify fields. Name the affected path or quality scenario, operating conditions, acceptance target or unresolved decision, behaviour to preserve, and evidence owner and method. For performance, retain workload and budget. Cite the source; do not silently invent or relax budgets. If the source omits a consequential constraint, surface the gap before committing work that depends on it. Keep unrelated briefs free of boilerplate quality checklists.
Where algorithm or data structure choice is consequential, state what needs comparison and why. An unresolved choice that could invalidate downstream work needs a bounded spike ahead of that work, with a decision criterion and explicit dependencies. Verification should cover applicable resource budgets and scaling as well as functional equivalence; a faster result that skips required behaviour does not pass. Reuse the spec's workload and measurement conditions so that the evidence answers the original requirement. Keep cross-cutting obligations traceable to the briefs that implement them and the brief that verifies the end-to-end result; passing isolated component checks is insufficient for a system target.
Brief structure (one file per unit of work)
docs/<phase>/brief-<NN>-<slug>.md (or whatever your repo's convention is — match existing phase docs).
Conceptually every brief carries the same handful of things: Wave, Depends on, Unblocks, Effort
(the scheduling metadata), Context (why + the exact facts needed), Read first (required
reading), Deliverables (concrete outputs), the Interface contract (the seam other briefs rely
on), and a Definition of Done.
Older brief sets narrated all of this in prose — a header line plus paragraphs. That drifts in two specific ways once a plan has more than a few briefs: dependencies written as free-text arrows that don't survive a rename or a re-numbering, and DoD items with no runnable check attached, so "done" is whatever the implementer felt like asserting. The template below is the current standard — use it for every new brief. It carries the same concepts as data (YAML frontmatter fields, tables) instead of only prose, so a script — or the next agent, or you in six months — can rely on the structure without re-reading the whole plan to extract it.
Start here: don't hand-type a brief — generate it. statusgen newbrief --stream <s> --title <t>
emits this skeleton with every derivable field already correct: the gate computed from the four risk
answers (it refuses a supplied gate, and in non-interactive mode refuses an unanswered risk question
rather than defaulting it), the wave computed from --depends, the inverse unblocks: edge written
into each named dependency in the same change, and a freshness stamp from a fetch it performs. Hand-
authoring stays valid (fix a typo without re-running a tool); the generator just removes the fields an
author can otherwise get wrong. Run statusgen newbrief --help for the flags.
Brief file template (data-first)
Select the identifier/schema pair before writing. With negotiated prefixed-label
support, write brief: <cell>:<repo>:<stream>:b-<NN> and keep the authored revision
in version:. Dependency refs may use :b-<NN>@<version>; no suffix binds the selected
source snapshot. Use that supporting schema for references
and dependency fields. The template below shows the currently supported legacy
brief-v2 pair; do not combine its schema with an unsupported b- identifier.
The unprefixed label is deprecated for new authoring after adoption, not invalid for
legacy consumers. Existing canonical fullIds and filenames remain unchanged (brief §3.8).
---
brief: <cell>:<repo>:<stream>:<NN> # current brief-v2 fullId; board label is <stream>/<NN>
title: <one line>
why: <prose> # REQUIRED for every NEW brief — one to three lines a non-engineer
# could read and justify the work from. Not the WHAT (that's title
# + Task), but WHY it matters: what problem, whose pain, what the
# outcome unlocks. Quality bar: "all 22 pages are eagerly imported
# into a single JS chunk, so every user pays a multi-MB first load;
# splitting cuts the initial payload ~5×." (frontend/05 exemplar).
# Omit only on legacy briefs being backfilled later — statusgen
# NOTICEs a missing why: (non-fatal this phase; hard error once
# backfill lands — same pattern as gate-why).
wave: <int>
depends: [] # typed IDs only: ["<stream>/<NN>", ...] — NEVER prose arrows
unblocks: [] # typed IDs
effort: S | M | L # closed scale — L is the CEILING (rule 12); XL is not a size,
# it is the signal to split into multiple briefs, each ≤ L.
gate: model | human # from the four risk questions below
risk: {regulatory: no, customer: no, irreversible: no, sensitive-data: no}
issues: [] # GH issue numbers this brief closes
regression-of: <issue ref or sha> # OPTIONAL — fix/bug briefs only (rule 14): the PRIOR fix this
# defect re-opens — its issue reference or its commit sha.
# Omit when no earlier fix exists (a first occurrence); never
# invent one to fill the field. No lint reads it yet: the key
# is tolerated as an unrecognised frontmatter key, not validated.
schema: brief-v2 # required in a v2 tree;
# --lint PROBLEMs a tree of v2 briefs missing it. Reserved,
# OPTIONAL keys parsed under brief-v2 (shape-validated only,
# gating behaviour deferred to the graph stream): id (uuid,
# minted once at authoring, never reused), supersedes ([]),
# version (int, bumped on every Task/Verify edit after first
# dispatch), gates ([{on, type, reason}]), feathers ([...]).
# NO status: KEY — the lifecycle cell is DERIVED by statusgen
# from PR trailers, verifyrun witnesses and App approvals, never
# hand-asserted in frontmatter or the stream README table.
authored: <YYYY-MM-DD> by <who/session>
sources: [] # provenance: scoping doc, finding IDs, intake IDs this derives from.
# F-<slug>/I-<slug> references should be links: "[F-ws-token-expiry](../findings/YYYY-MM-DD-example-finding.md)"
gate-why: <prose> # REQUIRED when gate: human OR any risk answer is yes — what about THIS
# brief makes it risky and what the human is confirming (a line or two).
# Omit only when gate: model and all four risk answers are no.
decision-trigger: creation | start | spec # OPTIONAL, gate: human only (absent = start) — WHEN this
# brief's self-contained decision issue is filed by the
# `<decision-issue filer>` your repo's instructions file names
# (see rule 4; the same shape as `human:<name>` — a capability the
# adopter binds, not a tool this skill ships). A JUDGEMENT recorded
# per brief, not a global rule: `creation` = the options are already
# enumerable as authored (file on landing); `start` = the decision is
# concrete once a worker first picks the brief up — the default,
# filed by the dispatcher; `spec` = the options only become
# well-formed after the pickup-time design/plan step — the executor
# authors `## Human decision` from that step, and THAT files it.
exec-tier: any | strong # OPTIONAL (absent = any) — minimum execution-model tier.
# DERIVED from four complexity questions (see rule 9); any yes → strong.
exec-tier-why: <one line> # Recommended when exec-tier: strong — which question(s) it answered yes.
domain: clear | complicated | complex | chaotic # OPTIONAL (absent = complicated) — the work's Cynefin
# domain. Governs which diagnostic to reach for: Ordered
# (clear/complicated) → Theory of Constraints; Complex →
# probe-sense-respond / enabling constraints; Chaotic → act first,
# then sense. `statusgen --lint` PROBLEMs an unrecognized value;
# `statusgen --cynefin` shows the distribution and lists an
# absent-domain brief as Disorder. A repo that keeps a longer
# treatment binds it as `<cynefin-lens explainer>` in its own
# instructions file; the four values above are the whole contract.
parallel-streams: [] # OPTIONAL (absent = one worker per brief — the default, and what
# nearly every brief uses). Declares that this brief's work
# decomposes into concurrent SHARDS, each scoped to file globs:
# parallel-streams:
# - {name: engine, files: ["statusgen/**"]}
# - {name: docs, files: ["docs/<stream>/**"]}
# Presence is a REQUEST, never a permission — `statusgen shardcheck`
# decides. See "Intra-brief splits" below before writing it.
consumers: [] # OPTIONAL — list of consumer sites when this brief changes a shared
# value. Each entry: "<path>: fixed-here | follow-up <stream/NN> |
# out-of-scope (<why>)". Absent = no shared value changed (the default).
# An AUTHORING PR declares future consumers, it does not edit them:
# route a path this brief's implementation will LATER touch as
# `follow-up <stream>/<NN>` at THIS brief, not `fixed-here`.
# See rule 6. Authoring convention — no lint enforces it yet
# (tracked as a planned follow-up).
---
# Brief <NN> — <title>
## Context
files: <exact paths the implementer touches>
out-of-repo files: <exact paths outside the repo (e.g. ~/.claude/skills/...), if any —
see rule 7; omit the line entirely when none>
facts: <the 3-5 project facts needed — key: value, no narrative. The implementer
must never need to explore the repo.>
layering: <REQUIRED for a new component/service/tool or a substantial boundary change
(domain extraction/dissolution, added adapter/entrypoint, logic crossing a process or
trust boundary); omit otherwise. One or two lines: simplest justified structure +
meaningful rules vs external effects (or why no extraction is warranted) + current
reason + Task/Verify references. Defaults (domain-core / flat tool), contract placement,
interface/purity rules, boundary checks and existing-brief amendment policy: brief-v1 §4.1.>
design-fit: # REQUIRED on every NEW brief; its two rules: brief-v1 §4.1
owner: <the one module that owns the meaning this brief touches, or n/a>
contract: <S-<slug> row id of the semantic-owner index, or none — <why>>
retires: [<mechanism/refusal/flag/test this brief removes>, ...] # [] is an answer
weight: <signed delta per dimension: verbs, flags, refusals, rule-text lines>
why-add: <required when any delta > 0: why it cannot live in the owner, and what
removal was considered instead; n/a otherwise>
oracle: docs/investigations/<file> # ONLY on a design brief a brittle `redesign` raised: its refactor
# oracle, whose five §5 rows Verify copies. Such a brief without it is not authored
## Human decision
<!-- gate: human only — omit the section entirely otherwise. Lifted VERBATIM into the
brief's decision issue by the `<decision-issue filer>` your repo's instructions file
names, so write it SELF-CONTAINED: the reader sees ONLY this text, never the brief —
no links, no URLs (a conforming filer refuses both), no repo paths, no references to
other briefs or docs. REQUIRED at authoring time when decision-trigger is creation or
start; when decision-trigger: spec, the EXECUTOR authors it at pickup from the
design/plan step and commits it into this file. -->
<3-10 lines: what is being decided and why it needs a human — enough to decide from
this text alone>
Options:
1. **<option>** — <what it means; consequences; what happens next if chosen>
2. **<option>** — <same>
Default if no answer: <option N after <date/window>, or "none — blocks until answered">
## Ground rules
- NEVER git push / trigger workflows / run mutating kubectl. Leave commits per
the task instructions only.
- Stop at `implemented` — you do not set verified/done.
- If anything is unclear or contradicts repo state: report NEEDS_CONTEXT, don't guess.
## Task
<what to build/change — explicit steps>
## Verify (executable — no prose-only DoD items)
| # | Command | Expect |
|---|---------|--------|
| 1 | <literal command> | exit 0; output contains "<literal>" |
## Evidence
<!-- appended at implementation time: one row per Verify item —
(command, exit code, output line(s) or hash, date, runner).
"verified" status in the stream README requires this section filled
by someone who did NOT implement. -->
## Review
Gate: <model|human> (from frontmatter). Reviewer records verdict + date in the
stream README table. Human gate is MANDATORY when any risk answer is yes.
Fill every frontmatter field — an empty sources: [] or a missing risk: answer is not a shortcut,
it's a gap the reviewer will bounce back. gate is derived, not chosen: if any of the four risk
questions is yes, gate must be human; only when all four are no may gate be model.
Rules behind the template
-
Load-bearing facts live in islands, not prose. Frontmatter, tables, and Verify rows are the record; prose explains and motivates but never solely carries a fact a script or a reviewer needs.
-
References are typed IDs (
stream/NN,F-<slug>,I-<slug>, legacyF-NN,I-NN, …) — no fuzzy names ("the pricing brief"), no arrow notation (←12a). A typed ID survives renumbering and greps cleanly. Register IDs are letter-prefixed slugs:F-<slug>for findings,I-<slug>for intake — the slug is 10–20 chars,[a-z0-9-], derived from the title (example:F-ws-token-expiry,I-model-mix-tiers). Older entries use numeric IDs (F-01,I-01) — those are frozen legacy and remain valid; new entries must use the slug form. **Going forward, register references SHOULD be clickable links pointing at the per-entry file:[F-ws-token-expiry](../findings/YYYY-MM-DD-example-finding.md). The typed ID remains the primary key (link text); the link is for readers. The mapping is each entry file's frontmatterid:— never guess slugs. Bare (unlinked) IDs stay legal but are not the preferred form for new briefs. -
Verify rows must be runnable by someone who didn't do the work. A DoD/Verify item with no literal command and no expected exit/output is not a DoD item — it's a hope. Prefer POSIX commands (
grep -F, forward-slash paths) for portable checks. For a genuinely native Windows command, add aShellcolumn and explicitly mark the rowcmdorpwshwhen authoring it. Never emitfindstr /c:"…"with backslash paths under implicitsh: bash reinterprets those arguments. Shell selection belongs in the reviewed Verify table; an Evidence-only edit must not change the command or its shell to make a failing row pass. Say where each row runs. When a row needs anything beyond the checkout, add anEnvcolumn (| # | Class | Env | Command | Expect |):tree,host[:<name>],service:<name>for a named NON-PRODUCTION instance (a database, an API, a staging deployment, described in## Context), orcluster:<name>. A row whose Env is nottreeis nevercheck:ci, since no CI job reaches it; class itcheck. A row needing a project secret or a live service is witnessed by a non-implementer where that environment exists, never by the implementer's own report. The grammar and itsstatusgen --lintrules are rule 45 in the brief-rules reference. -
gate: humanis mandatory when any risk answer isyes. Record all four risk answers (regulatory, customer, irreversible, sensitive-data), not just the resulting gate — the answers are what a reviewer audits, the gate is just their conclusion. A risk-gated brief (gate: humanOR any risk answeryes) MUST carry agate-why— a line or two naming what about this brief trips the wire and what the human is actually confirming at the sign-off. A risk boolean with no rationale is an unfalsifiable assertion; the verify-gate card surfaces thegate-whyverbatim. (statusgen NOTICEs a missinggate-whytoday; it becomes a hard lint error once the backfill lands.) A gate:human brief also gets a filed DECISION ISSUE. The human gate is only real when there is a concrete, self-contained tracker issue for the human to act on. Two halves, and only the first ships with this methodology:statusgen --decision-issuesemits the newly-eligible set as JSON — title,needs-decisionlabel, composed body, and a hidden<!-- needs-decision: <stream>/<NN> -->marker that dedupes, so a brief that ever had one never gets a second — and the<decision-issue filer>your repo's instructions file names is what actually files it. (Same shape ashuman:<name>: a capability the adopting repo binds, because filing depends on the tracker.) Record the resulting number back in the brief'sdecision-issue:frontmatter field;statusgen --lintNOTICEs a gate:human brief in flight without one. WHEN it files is a per-brief judgement you record asdecision-trigger:(see the template): ask "could the reader pick an option from what I can write down right now?" — yes at authoring →creation(author the## Human decisionsection now and file as the brief lands); yes once a worker frames the work →start(the default; the dispatcher files it, from your authored## Human decisionsection, or by deriving a fallback fromgate-why/whywhen the section is absent); only after real design exists →spec(the executor authors the section at pickup, which is what ripens the filing). The issue body must let the human decide WITHOUT opening the repo — inline everything, since a conforming filer refuses links and URLs in the composed body. -
Provenance is required. A brief with an empty
sources:— no scoping doc, no finding ID, no intake ID it derives from — is untraceable: no one can tell why the work exists or whether it's still needed. -
A brief that changes a SHARED VALUE must enumerate its consumers, and verify the FLOW — not just the site. (Cost that forced this rule: an API response field was renamed and verified green at its own site — "the endpoint returns the new field name" — while a frontend that still read the old field name silently broke the whole end-to-end flow; no dashboard row ever rendered. The change was correct locally and broken across components.) A shared value is anything another component reads: a party/identity, an env-var NAME, a ConfigMap/Secret key, a field's MEANING, a wire/JSON format, or a default. The trigger is cross-component: when the brief's Context
files:references multiple top-level directories (k8s/, api/, frontend/, services/, docs/, docs-site/, scripts/, .github/, tools/) or its Task touches a shared-surface keyword (party, identity, env-var, ConfigMap, Secret, wire format, JSON format, a default).- Enumerate consumers as a structured frontmatter field:
consumers:— an optional YAML list in the brief-v1 frontmatter (absent = the brief asserts it changes no shared value). Each entry is<path-or-component>: <routing>where routing is one offixed-here/follow-up <stream>/<NN>/out-of-scope (<why>). An unlisted consumer is how you strand an assumption. Project wrappers (this repo's.claude/skills/author-brief/SKILL.md) carry the full format spec. The lint enforces this field —statusgen --consumersis the diff-aware gate (it exits non-zero on a routing claim the diff disproves), andstatusgen --lintalone already makes one class fatal: afollow-up <stream>/<NN>naming a brief that exists in no stream README is a hard PROBLEM. The rest of the field's checks are advisory NOTICEs. See the generated Enforcement status of these rules table below for the exact per-rule status; do not restate it here (it drifts — spec §4 B9). - Never reclassify an entry to make it fit the grammar. The routing token is a commitment
record —
follow-upsays work is still owed,out-of-scopesays it isn't — so swapping one for the other to satisfy a regex destroys the fact the field exists to hold. Afixed-herewanting a(<why>)parenthetical is already legal — the grammar is tolerant of trailing detail (fixed-here (bumps the pin in the same commit)), so write it. The remaining awkward case is afollow-upwhose target is an intake entry or an unauthored brief with no<NN>to cite: do not leave a barefollow-upon the belief nothing enforces it — afollow-upwith no target is a NOTICE, and inventing a<stream>/<NN>that does not exist is a fatal PROBLEM. Route it truthfully asout-of-scope (<why — deferred to an unauthored brief / intake entry>), which records the deferral without a false or missing target. Same reason existing briefs are not backfilled: the record's truth outranks the grammar, and the grammar has a truthful form. - An authoring PR routes its OWN future deliverables to the deferred disposition, never
fixed-here. A brief-authoring change declares where a change will land; it does not land it — the authoring diff adds the brief and touches none of the paths the brief's own implementation will later edit.fixed-hereis a claim about THIS diff, legitimate only when THIS diff actually edits the named path; asserting it on an authoring-only diff is a claim the routing gate correctly disproves — "no path it resolves to appears in the diff" — reddening the PR on its first push. So route each path this brief's own implementation will later touch to the deferred disposition:follow-up <stream>/<NN>targeting THIS brief. The implementation change that lands the path then replaces that routing withfixed-here, in the same change. A self-targetingfollow-upcorroborates by construction — the brief's own file contains its own ID, so the gate's back-reference check is satisfied the moment the brief exists. Every entry still ends in exactly one of the three routing tokens; an entry with none claims nothing and can corroborate nothing. Worked example — the same consumer written wrongly then rightly on an authoring PR that only files the brief:- wrong (asserts a fix this diff did not make; the gate disproves it):
- "src/pipeline/router.go: fixed-here" - right (deferred to this brief until its implementation lands):
- "src/pipeline/router.go: follow-up <stream>/<NN> (this brief; flips to fixed-here when the implementation edits the path)"Run your project's consumers check — the diff-awarestatusgen --consumersgate — over the branch before pushing an authoring change, so the deferred routing is confirmed locally rather than by a red check in CI.
- wrong (asserts a fix this diff did not make; the gate disproves it):
- The consumers Verify row works after the merge too: the bare
statusgen --consumers --brief <stream>/<NN>row re-runs on merged main with no hand-pinned commits. It pins itself to the delivery and that commit's first parent, read locally: the committed Evidence'sVerification-Table:marker if there is one, otherwise the one first-parent commit whose message (or a commit it merged) carriesBrief: <stream>/<NN>. So the implementation PR's commits carry that trailer, and a later PR for the same brief should not repeat it: zero or several candidates is exit 2 (COULD-NOT-CHECK), and the remedy is an explicit--delivery <full-sha> --base <its first parent>. - Flow Verify row: a shared-value brief's Verify table must carry at least one row exercising the cross-component flow end-to-end (e.g. frontend submits form → API persists → dashboard row appears), not just the changed site. Site-green does not imply flow-green. This one stays a judgement call even after the planned check ships — prose Verify rows cannot be perfectly classified, so the check is an advisory NOTICE, never a hard gate.
- Cross-repo pairing: when a change crosses a repo boundary in addition to a component
boundary, it carries BOTH a
consumers:list (this rule) AND a sibling-repo SHA — note the pair in both places. This applies to issue-driven work too — a change to a shared value that skips a brief skips this analysis entirely, which is the highest-risk path in the system. Promote such a change to a brief, or at minimum run the consumer grep and record it.
- Enumerate consumers as a structured frontmatter field:
-
Out-of-repo files must be declared — the declaration is the claim. A brief whose scope touches files outside the repo (user-level skills/settings, e.g.
~/.claude/**) MUST list the exact paths in Context underout-of-repo files:. These files have no worktree isolation and no branch-as-claim, and an edit takes effect in every running session the moment it's written — review is post-hoc. So: the dispatcher serializes on the declaration (at most ONE such brief in flight at a time, across all streams), and the implementer stages the edit as a diff in the PR, applying it to the live file only as the LAST step beforeimplemented— never incrementally. Where the out-of-repo surface is itself a git repo (e.g. the~/.claudestopgap repo), commit the applied edit there too. A brief that touches this surface without the declaration is scope drift — bounce it. -
Freshness check — before authoring a fix/change brief, verify the site isn't already fixed. Read the target site on fresh
origin/main(git fetch origin && git log origin/main --oneline -- <path>+ read the code) and record the check in the brief'ssources:asfreshness-checked <YYYY-MM-DD> @ <short-sha>. If the deliverable is already satisfied, the brief is NOT authored — resolve or re-scope the finding/issue instead. That is the only reason to withhold it: a read stated to you as done counts as done (stamp its sha), and a result you cannot fully see is no reason to hold — author the brief, with a first Task step that re-checks. The output is the brief or a "do not author — already fixed" determination, never a held draft or "not authored yet". The check is light; the waste it prevents (re-writing a fix that already landed, claiming a vuln closed that was never open) is heavy. -
exec-tier: complexity signals a minimum execution-model tier.
exec-tieris DERIVED, not chosen (mirror of the gate/risk rule). The author answers four complexity questions; any yes →exec-tier: strong(absent/any-no →any, the default): (a) Does the Task require design decisions the facts do not fully pre-specify? (b) Does correctness depend on cross-component/cross-artifact reasoning (shared values, end-to-end flows, sweeping a pattern across sites)? (c) Is it code where a subtle implementation error survives the brief's own tests (auth, funds, concurrency, safety plumbing)? (d) Is this a design brief raised by an error-class trigger? (A recurring defect class, not one symptom, has accrued enough counted instances or merged fixes to be owed a design.)strongSHOULD carry a one-lineexec-tier-whynaming the question(s) (lint: PROBLEM if unknown, NOTICE if missing). Honest limitation: statusgen never verifies which model actually ran — pickup-side compliance is honor-system self-report; the enforced surface is desk dispatch + the review gate. -
Defense in depth is the DEFAULT design posture. When a brief's Task has design alternatives, prefer the LAYERED one: no single control standing between a fault and the damage. Mandatory for core-system briefs — each project layer defines what "core system" means for its own repo (typically: anything touching money, auth/identity, or an irreversible external write); recommended everywhere else. Three authoring obligations:
- (a) Single-point-of-failure note in
## Context— one or two lines answering "what is the ONE control this design depends on?". If the honest answer is a single thing, the design needs another layer BEFORE the brief is authored, not after a reviewer bounces it. - (b) At least two INDEPENDENT layers in the Task, where feasible. The independence test: two layers are independent only if they fail for DIFFERENT reasons in DIFFERENT components. The same check pasted into N call sites is one layer — it fails once and everywhere. A typical independent set: an enforcement point at the trust boundary (the system itself rejects the operation) + validation in the service that calls it + an out-of-band monitor/reconciler that notices when both were bypassed.
- (c) Verify rows exercising each layer INDEPENDENTLY, including at least one NEGATIVE-PATH row — break or bypass the upper layer and prove the lower one still catches the fault. A Verify table that only walks the happy path through every layer at once has verified exactly one layer: the outermost. Boundary — this is NOT "add more assertions". Layers are DESIGNED controls at DISTINCT trust boundaries, not one check duplicated for reassurance. Where a project's constraints say invariant checks are closed-form math rather than runtime assertions, that constraint stands; the independence test in (b) is what distinguishes a real layer from assert-spam. Adding a "layer" that fails for the same reason as the layer it backs up costs review time and buys nothing.
- (a) Single-point-of-failure note in
-
A brief whose deliverable makes checkable factual claims needs at least one DEREFERENCING Verify row, not only presence/formatting checks. Two rows can both go green without proving the same thing:
- Presence/formatting —
grep -c,wc -w, "section exists" — proves the deliverable is well-formed. It CANNOT fail on a wrong-but-well-formed document: a confident falsehood sitting in the right section, at the right length, passes exactly like the truth. - Dereferencing — fetch a link and check what it actually serves; run a documented command and compare its real output/exit code to the specific claim; check a documented ID or property against the live system it names. This CAN fail on a wrong-but-well-formed document.
Rule 3 above ("Verify rows must be runnable by someone who didn't do the work") still stands — this rule doesn't relax it. It says that when the deliverable itself carries checkable facts (a setup/config guide, a market or competitive analysis, a spec — anything asserting "X is true" that a reader could act on), a presence gate can't be the whole mechanical floor: at least one row has to be capable of catching a wrong claim, not just a missing section. Skip this only for genuinely presence-only deliverables with no factual claim to dereference (a docs reformat, a template scaffold) — manufacturing a dereferencing row against a deliverable with nothing to check is its own kind of checkmark-DoD.
It is a DIFFERENT AXIS from the row-runner rules and the unfailable-row lint: those read the command TEXT and are enforced by
statusgen --lint; this one needs to know what the deliverable claims, so no lint enforces it. A row can pass every one of them and still measure only presence.The triggering evidence (an all-presence table that passed 8/8 on a factually wrong guide) and why a link-resolution lint would cover only link-shaped dereferencing are in the brief-rules reference, rule 43. Don't wait for such a lint to exist before writing the row this rule asks for.
- Presence/formatting —
-
Sizing limits — L is the hard ceiling; prefer M for strong-tier / risk-gated work. The
effort:scale is closed at S | M | L, and the top of it is a rule, not a convention: no brief may be larger than L. A unit of work that would be XL (or bigger) MUST be split into multiple briefs, each ≤ L, sequenced withdepends:/unblocks:(or sharded viaparallel-streams:when the intra-brief split rules below hold). XL is only ever a signal-to-split, never an emitted size —statusgen --lintalready PROBLEMs any effort outside S/M/L.Preference, explicitly NOT a rule: when a brief is
exec-tier: strongOR risk-gated (gate: human/ any risk answeryes), prefer M as the ceiling — lean toward splitting an L into Ms. An L remains permitted for strong/high-risk work when there is a real reason to keep the unit whole; the default lean is M-or-smaller. Rationale: strong-tier work (cross-artifact correctness) and high-risk work are exactly where a large brief most degrades review quality, so smaller, more-reviewable units are preferred there — the review gate is the control the risk answers lean on, and it only bites on a diff a reviewer can actually hold. -
A Verify row MAY declare an OBLIGATION alongside its class — the prose MUSTs of rules 6, 10 and 11 carried as typed data. The optional
Classcell (rule 45 in the brief-rules reference) answers WHO EXECUTES a row (check:ci/check/gate:model/gate:human). A second, orthogonal axis answers WHAT OBLIGATION the row discharges, written as+-prefixed tokens appended to the same cell — a compound cell,<execution> +<obligation> …, so the table's column set is unchanged and a legacy column-less table is untouched. Four obligation values, each an example row:Obligation What the row must do Example Classcell+mutationbreak the thing the change guards and prove the guard reddens (rule 10c, spec D1) check:ci +mutation+flowexercise the cross-component path end to end, not just the changed site (rule 6) check +flow+dereferenceresolve a claim rather than count its presence (rule 11) gate:model +dereference+neighbourexercise a sibling site the change did not touch check +neighbourstatusgen --lintderives which obligation a brief OWES from the shape of its change (the branch diff, its declared paths, its task prose) and reports one owed-but-absent — it checks the PRESENCE of the typed row, never its ADEQUACY, which stays the reviewer's call (spec §3 D7). An unknown+tokenis a hard PROBLEM, exactly as an unknown class is. Enforcement status: the derivation lands advisory (a NOTICE);+mutation's promotion to a hard gate is a follow-up. This status line is deliberately minimal — the authoritative per-obligation enforcement state is generated, not hand-copied here (a hand-written status becomes the next stale second copy). -
A fix/bug brief closes the defect CLASS, not the one instance. A defect repaired at one site comes back at another when the fix closed the instance and left the class open: a second caller reaches the same hazardous primitive by a different path, a test stub hides it, and the regression reads as a new bug. So a brief whose Task fixes a defect carries two things beyond the ordinary template:
regression-of:in the frontmatter, when an earlier fix for the same defect exists — that fix's issue reference or commit sha. It records that the class has escaped once already, and it points the reviewer at the guard that failed to hold. Omit it for a first occurrence; never invent a value to fill it. Run the freshness check (rule 8) over the earlier fix's site as well as the new one.- A MANDATORY class-guard Verify row. Name the class in
## Contextfacts:— the shape every instance shares, not the one line that failed — and add a row whose check covers EVERY site the defect can recur at, not only the reported one. The model is an allow-list structural test: enumerate every caller of the hazardous primitive (exampleRawToken()) and fail on any caller outside a short committed allow-list (exampleSafeToken()). A lint rule, a type that makes the hazardous call unrepresentable, or a single choke point serves equally. A test of the reported instance may sit beside it; it never replaces it. - The class-guard row is FAIL-FIRST. Before the fix lands, the implementer plants a
deliberate SECOND instance of the defect at a site the fix does not touch and shows the row
RED on it; the Evidence records that red run, naming the planted site, beside the green one.
A guard shown red only against the reported instance proves it sees that instance, which the
instance test already did. Where the guard's matcher could silently stop matching, keep the
plant as a committed positive-control fixture the guard must flag, so the red stays
re-runnable after merge. Tag the row
+mutationin itsClasscell (rule 13) — breaking the guarded property and proving the guard reddens is exactly that obligation.
Worked example (neutral names) — the frontmatter line and the two class-guard rows:
regression-of: <the earlier fix's issue reference or commit sha> | # | Command | Expect | Class | |---|---------|--------|-------| | 2 | `go test ./examplepkg/ -run 'TestExampleRawTokenAllowList$' -count=1` | exit 0 — every caller of `exampleRawToken()` in the tree is on the allow-list | check:ci +mutation | | 3 | `go test ./examplepkg/ -run 'TestExampleRawTokenAllowListFlagsPlant$' -count=1` | exit 0 — the guard, run over `testdata/example-plant/` (one planted caller outside the allow-list), reports that caller | check:ci +mutation |Row 3 is the positive control that keeps the fail-first re-runnable; the pre-fix red run with a planted second caller in the real tree goes in the Evidence. Enforcement status: no lint enforces this rule yet —
regression-of:is tolerated as an unrecognised frontmatter key rather than validated, and whether a class-guard row is present and truly covers the class is the reviewer's call. A defect with no mechanically checkable shape (a one-off logic error nothing else can repeat) states that in## Context, with the reason, in place of the row; the reviewer weighs it, and it is not available for a defect that has already reached a second site.
Keep a brief self-contained: if executing it requires knowledge from another brief, either link it
under "Read first" / facts: or state the dependency in depends: — never assume the reader has the
whole plan in context.
Enforcement status of these rules (generated — do not hand-edit)
Regenerate with statusgen enforcement-status piped through the skillslint sync
(go run ./tools/skillslint --sync); the byte-diff gate in the skillslint CI job fails
if this block drifts from the lint's rule registry. Hand-edit it and the gate reddens.
This table reports what statusgen --lint enforces, not what the methodology
requires. A rule enforced only by a tool outside the lint — a CI workflow, a desk-side
guard — reads as not enforced here unless it is registered. The three statuses are
exact: fatal is a --lint PROBLEM that makes the run exit non-zero; advisory is
a NOTICE that is printed but never gates; not enforced means no lint rule checks it —
it is an authoring convention only.
| rule | what it checks | status |
|---|---|---|
bre-alternation |
a pipe in a basic-regex grep pattern (no -E/-P) is an ordinary character, so the pattern matches the Verify row itself — fatal for a closure this branch makes (verified/done, and not so at the merge-base); a NOTICE on every other brief |
fatal |
cmd-marker-ambiguous |
a Command cell carrying more than one cmd:-marked code span, so which command the row names is ambiguous |
advisory |
cmd-marker-not-honoured |
a cmd: span verifyrun ignores because the rendered cell may not show it as code (backslash-escaped backticks; raw HTML, a link, an image, a dollar in any spelling or a character reference in the cell's prose; a span fused to the text before it; or a marker not set apart by whitespace), so the row runs its first span |
advisory |
cmd-marker-overrides-command |
a cmd: marker that replaces a first code span which reads as a command itself (multi-word), so the row runs something other than the span a reader sees first |
advisory |
cmd-marker-vacuous |
a cmd:-marked command that cannot fail (true, :, exit 0, a lone echo), so the row passes whatever the tree holds |
advisory |
consumers-flow-verify-row |
that a shared-value brief's Verify table carries at least one row exercising the cross-component flow end-to-end — a judgement call no lint decides | not enforced |
consumers-followup-missing-brief |
a consumers: follow-up <stream>/<NN> whose target is not a brief in any stream README — the routing claim is false |
fatal |
consumers-followup-no-target |
a follow-up routing that names no <stream>/<NN> target — a deferral with no holder |
advisory |
consumers-followup-one-way |
a follow-up target that exists but never references the deferring brief back — the coverage claim is one-way |
advisory |
consumers-missing-list |
a brief whose prose reads as changing a shared surface but enumerates no consumers: (a heuristic prompt, never a verdict) |
advisory |
consumers-no-verify-row |
a brief carrying consumers: but no Verify row that runs statusgen --consumers to corroborate the routing |
advisory |
consumers-out-of-scope-no-reason |
an out-of-scope routing with no substantive reason for the reviewer who must weigh the exclusion |
advisory |
consumers-prose |
a consumers: written as a prose paragraph rather than a routed list, so nothing can corroborate it |
advisory |
consumers-unrouted |
a consumers: entry that names no routing token (fixed-here / follow-up / out-of-scope) |
advisory |
eligibility-could-not-check |
a gates: edge (or unsatisfied depends:) the eligibility evaluator could not resolve offline — an unregistered/unpublished alias, an absent sibling checkout, or a forge-backed target — which HOLDS the brief out of Next-up | advisory |
ere-literal-pipe |
a | inside a grep -E pattern is a literal pipe, not alternation, so the row matches almost nothing and passes blind — fatal for a closure this branch makes (verified/done, and not so at the merge-base); a NOTICE on every other brief |
fatal |
fail-first-closure |
a risk-bearing Verify row of a closure this branch makes (verified/done, and not so at the merge-base) has no current fail-first witness, is unproven or non-discriminating, was run for an earlier command, or names a base that is not the merge-base or an ancestor of it that already holds the brief at its current path (only the merge-base itself when the brief was created or renamed on the branch) (docs/verify-row-strength.md) | fatal |
gnu-only |
a GNU-only shell construct that fails on the BSD/macOS userland a reviewer may run the row on — fatal for a closure this branch makes (verified/done, and not so at the merge-base); a NOTICE on every other brief | fatal |
gorun-exit |
a go run in the Command cell flattens the program's exit code, so a non-zero result reads as success — fatal for a closure this branch makes (verified/done, and not so at the merge-base); a NOTICE on every other brief |
fatal |
gotest-run-vacuous |
a go test -run selector with no --- PASS assertion in the same command, so the row passes whether or not the named test exists, is built, or was ever renamed away (open briefs only; a closed brief's rows are summarised, not individually flagged) |
advisory |
grep-pipe-zero-count |
a grep feeding a later pipeline stage under a zero-count Expect fails on its own success path under pipefail (grep exits 1 on no match), and passes on exit status alone when a match is present | advisory |
grep-zero-count |
a grep -c whose pass bar is satisfied by a zero count measures nothing — fatal for a closure this branch makes (verified/done, and not so at the merge-base); a NOTICE on every other brief |
fatal |
moving-ref |
a diff base pinned to a moving ref (a branch name, not a SHA) makes the row's result drift under it — fatal for a closure this branch makes (verified/done, and not so at the merge-base); a NOTICE on every other brief | fatal |
no-output-assertion |
an Expect of exactly exit 0 on a command whose output nobody asserts on (use exit 0; output contains "<literal>" or exit 0; <N> lines) |
advisory |
pattern-containment-set |
a containment list that is not exactly the five containment values, on a node that is not an effect-free human decision, with a pre-selected default, or a signal pattern without exactly one containment node — containment could become an automated act | fatal |
pattern-culprit-record |
a culprit record whose fields are not the fixed six, or whose default or withheld class is not judgement, or whose withheld file is not null — a withheld or unresolved culprit could route to the mechanical exit | fatal |
pattern-decision-options |
options, default or containment on a node that is not a decision, a default outside the node's options, or a duplicate option — a non-decision node would carry a person's choice |
fatal |
pattern-effect-exceeds-role |
a pattern node whose declared effect kind is not permitted for its role, per the role-to-effect-kind table in spec/workflow-pattern-v1.md §7 — a generated instance would carry a permission its role does not hold | fatal |
pattern-effect-target-not-owned |
a non-effect-kind pattern node declares an effect whose target is not among its own outputs — a node claiming a consequence outside its own declared output boundary | fatal |
pattern-join-not-check |
a pattern's join names a node whose kind is not check — the pattern has no independent integration check |
fatal |
pattern-judgement-no-default |
a signal class whose judgement exit is not a human decision with options and a default among them — the person closing the decision gets no recommended next step | fatal |
pattern-remedy-set-open |
a signal class listing a remedy outside the closed remedy set, a mechanical exit with no remedy or not kind effect, or no .github/ refused-path while any node declares effects — an automated fix could touch gate configuration |
fatal |
pattern-replay-not-mandatory |
a signal pattern with no node producing the reserved replay-fixture artifact, or a producer that owes it under no mandatory command claim — a fix could land with no reproduction of the failure |
fatal |
pattern-review-same-role |
a pattern node whose evidence includes a review claim but shares its role with the node that produced its input — the implementer<->reviewer separation is not machine-checked | fatal |
pattern-risk-input-missing-verdict |
a pattern's risk-input omits one of the four risk-class verdicts (low/standard/elevated/human) — an instance of that risk class has no declared mandatory gates |
fatal |
pattern-signal-admission-open |
a signal class admitting a trigger outside schedule/push, push from a ref other than refs/heads/main, or no admission at all while any node in the pattern declares effects — a run of unchecked provenance could reach an automated effect | fatal |
pattern-signal-input |
a signal pattern whose signal input is malformed or off an entry node, whose input classes differ from the declared signal classes, that has a node unreachable from the signal input, or whose class names a missing exit or an incomplete gate-red record — a class could escape the rules that range over the input | fatal |
pipeline-exit-sunk |
a shell pipeline whose real exit status is sunk by a later stage, so the row cannot fail — fatal for a closure this branch makes (verified/done, and not so at the merge-base); a NOTICE on every other brief | fatal |
prose-led-command |
a Command cell whose lift — the cmd:-marked command, else the first code span — is not a command: a prose mention (a file, a path, an owner/repo, a code identifier, a word ahead of the real command), a shell comment, or a shell no-op (:, a cmd.exe REM / :: remark); verifyrun and the desk executors record the row could-not-run. Fix a mention by marking the real command with a cmd: code span; fix a comment or no-op, marked or not, by replacing it with the command that performs the check |
advisory |
rE2-literal-pipe |
a | inside a go test -run/-bench selector is a literal pipe in RE2, not alternation — fatal for a closure this branch makes (verified/done, and not so at the merge-base); a NOTICE on every other brief |
fatal |
runtime-resource-claim-without-principal |
a runtime resource claim (or a release of a claimed resource) not authorized by a human or organization principal, or ownership no succeeded claim backs | fatal |
runtime-resource-credential-not-rotated |
a runtime resource claim with no recorded rotation of the agent credential, or a release with no recorded revocation | fatal |
runtime-resource-credential-outlives-ttl |
a runtime resource whose agent credential lifetime exceeds the resource's ttl | fatal |
runtime-resource-expired |
an unclaimed runtime resource past its ttl, or a claimed one past its retention, still recorded as live | fatal |
runtime-resource-receipt-missing |
a runtime resource effect recorded succeeded with no adapter receipt | fatal |
runtime-resource-schema-violation |
a runtime resource record that breaks runtime-resource-v1's shape, repeats an effect id, or carries a ttl, lifetime or timestamp the rules cannot evaluate | fatal |
runtime-resource-state-unsupported |
a runtime resource record whose state is not the one its receipts support, read in order (the latest authoritative observation wins), or whose receipt time is outside its effect's window | fatal |
runtime-resource-ttl-exceeds-bound |
a runtime resource requested for longer than its adapter's registered max-ttl | fatal |
runtime-resource-unknown-adapter |
a runtime resource record whose adapter is not in the adapter registry, is not registered for the record's class, or does not implement a verb the record uses | fatal |
runtime-resource-unreconciled-effect |
a runtime resource effect with outcome unknown left unreconciled, or another effect issued while one is pending | fatal |
runtime-resource-unreconciled-release |
a runtime resource release counted done with no later reconcile receipt observing the resource absent | fatal |
shredded-cell |
a raw ` | ` in the Command cell is read as a table delimiter, truncating the command and shifting every later column — fatal for a closure this branch makes (verified/done, and not so at the merge-base); a NOTICE on every other brief |
stream-cap |
a change that adds an active stream past the per-root active-stream cap (ASSAY_STREAM_CAP) with no offsetting park — no net new streams past the cap | fatal |
stream-source |
a change that adds an active stream README citing no spec:, or a spec: whose header is not **Status:** approved — a stream is scaffolded only from an approved spec |
fatal |
table-touches-no-files |
no Verify command references any path the brief's files: declares, so the table may prove nothing about the change (an unparseable files: is COULD-NOT-CHECK) |
advisory |
trivially-green |
a command that exits 0 whatever the tree holds — true, echo ok, a trailing ` |
|
unsubstituted-metavar |
an unsubstituted <metavar> placeholder left in the Command cell, so the row cannot be run as written — fatal for a closure this branch makes (verified/done, and not so at the merge-base); a NOTICE on every other brief |
fatal |
verify-row-portability |
a Verify row hardcodes /tmp, sh/bash -c or findstr without an explicit OS marker (TMPDIR fallback is exempt) | advisory |
verify-unplaced-rows |
a closure this branch makes whose ## Verify section holds text statusgen verifyrun cannot place and that looks like Verify rows: a numbered row that lost its table header (a prose paragraph split the table), a table headed Expect with no Command column, or a row too short to reach Command. A `Failure mode |
Caught by` map, a mutation map or a legend is not Verify-shaped and is not reported |
Before dispatch — mistake-proofing the brief itself
The rules above shape the brief. The three steps below test it, at the one pause point the flow
already has: the brief is authored and the Verify table is written; nothing is dispatched yet. All
three are zero-tooling — no lint reads any of them, which is exactly why they are procedure and not
schema. The doctrine, the evidence, and the WHY live in docs/mistake-proofing.md (the public
tool home) §§B5–B8; that document is the one home for them. What follows is only the procedure.
Pre-mortem → detection map (B5)
Spend one prompt on prospective hindsight, about the brief you just wrote (not about the product):
"This work shipped and was wrong — what went wrong?"
Then map every failure mode it names to the Verify row that would catch it:
| Failure mode of the work | Caught by |
|---|---|
| Worker edits the source but never regenerates, so the committed output is stale | row 3 — <regen> --check, exit non-zero on drift |
| The new lint rule ships but never fires; no input in the suite trips it | row 4 — deliberate bad input, expect exit 1 |
| The version pin in the guide is written from memory and is already wrong | no row |
A failure mode with no row IS the finding. Either add the row (here: dereference the pin against the live release), or record in one line why it is review-only — adequacy, taste, and materiality stay with review by design, and saying so is an answer. What you must not do is leave the third column blank and dispatch. The rows are the deliverable; the map is the generator that produced them, and may be kept in the brief beside the table or discarded once the rows land.
The dispatch checklist (B7)
Run it at the pause point, do-confirm style — the work is already done, you are confirming the
killer items — in under a minute. It covers ONLY what statusgen --lint cannot read. It stays this
short: a checklist that grows becomes a document, and a document is the weakest device there is.
DISPATCH CHECKLIST — brief authored, before dispatch
[ ] 1. Rows DISCRIMINATE. Picture a wrong-but-plausible deliverable — right shape, right
sections, a confident falsehood inside. Does at least one row go red on it? (B6)
[ ] 2. Facts dated and checkable. Every `facts:` entry is dated, or carries the command that
re-establishes it. Nothing written from memory.
[ ] 3. Self-contained. Executable without reading another brief and without exploring the repo.
[ ] 4. Risk answers match `files:`. Read the four answers against the declared paths — do those
paths trip a risk every answer says no to?
[ ] 5. `gate-why` is substantive — names what about THIS brief trips the wire.
[ ] 6. Effort and exec-tier honest. Not an L wearing an M; not `any` on work that needs `strong`.
[ ] 7. Shared value → a FLOW row, not only a site row, and `consumers:` enumerated (rule 6).
[ ] 8. Every new brief → `design-fit:` answered; any weight delta > 0 → `why-add` names what
removal was considered. New component or substantial boundary change → `layering:`
records justified structure; contract placement and verification follow brief-v1 §4.1
for any claimed boundary, new or changed (or check flat-tool behavior).
[ ] 9. Pre-mortem run; every failure mode has a row or a recorded review-only reason.
Item 1 is the negative control: a Verify table that cannot fail is a green lamp wired to nothing. Expect the list to be wrong at first — revise it against misses you actually observe, and keep it at single digits by dropping the item that stopped earning its place, not by appending.
Comprehension probe (B8)
Optional — reach for it when a brief's self-containedness is genuinely in doubt (dense subject, unfamiliar surface, a draft you compressed hard).
- Write 3–5 questions a competent executor must be able to answer to do the work — pointed, not trivia: "which file does the second Task step edit, and what does it currently contain?", "which Verify row fails if the generator is not rebuilt first?"
- Hand a fresh, cheap-tier agent the brief text ALONE — no repo, no plan, no sibling brief — and have it answer. (The model-tier gate at the top of this skill bars a cheap tier from authoring; answering a probe is not authoring. A cheap answerer is the point: it tests whether the brief carries the work rather than whether the reader is strong.)
- A wrong or hedged answer is a defect in the brief. Fix the brief. Never fix it by enriching the worker's dispatch prompt — the brief is what the next reader gets.
A failed probe is a defect caught before it crossed the boundary, and it costs less than one failed worker run.
Intra-brief splits — parallel-streams:
A large brief whose parts are genuinely independent can be worked by several concurrent workers
instead of one. The optional parallel-streams: field is how a brief declares that. Absence is the
default and always will be — nearly every brief omits it and dispatches to exactly one worker.
Write it only when all four hold. Otherwise leave it out; a serial brief is never wrong.
-
Effort: L, or the brief says why an M pays.
statusgen --lintNOTICEs a split on an S brief: coordinating two workers, two claims and a recombine costs more than an S brief contains. -
The parts are separable in the deliverable, not just in the file tree. "These touch different directories" is a statement about paths; the question is whether either half can be reviewed and merged without the other.
-
No shard owns a shared surface. A numbering space, a row table, a generated artifact, a module graph, a pin set: two shards editing different lines of one of these still collide, because what they contend on is not the bytes. The declared list — with the reason each surface earns its place — is
sharedSurfacesinstatusgen/shardcheck.go; that is the one source, so do not restate the list here or in a brief. Edits to those files belong to the coordinating worker, after the shards land. -
statusgen shardcheckapproves it. Declaring the field is a REQUEST. Runstatusgen shardcheck --brief docs/<stream>/brief-<NN>-<slug>.md --root .before dispatch; it is also runnable on a candidate split with no brief written yet (
--shard engine=statusgen/** --shard docs=docs/<stream>/**). Three states, and only the first permits a split: 0 checked-clean · 1 checked-failed (a named collision) · 2 could-not-check (something it could not analyse). 1 and 2 are the same instruction — dispatch ONE worker, serially.
What the check prevents, and what it does not. It is a precondition on the split, not a merge gate, and saying so plainly is the point:
| Class | Prevented? | By what |
|---|---|---|
| Two shards editing the same file | yes | path-overlap — glob disjointness, checked against the real tree rather than asserted |
| Two shards editing one numbering/row/generated space | yes | shared-surface — the surface is withdrawn from every shard |
| Shard A changes a declaration shard B calls | yes, within one Go package | symbol-coupling — the class with no textual conflict, where both shards stay green alone and main goes red on merge |
| Any other cross-shard file pair (non-Go, or Go across packages) | NO | reported as a COVERAGE-GAP, which forces could-not-check → serial |
| A collision between this brief and a different branch | NO | out of scope by construction — one brief's shards are all it sees; that is merge-time detection, which is statusgen mergecheck's job |
| A branch that is stale relative to main | NO | merge-currency, also mergecheck's |
The middle row is the one that matters. The collision this was built for was a function growing an eighth parameter on one branch while another still called it with seven — different files, both green independently. A partition that only checks paths would have looked at those two files and seen a clean split. So a path partition is necessary and not sufficient, and the gap is named rather than defaulted away: any pair the checker cannot reason about produces could-not-check, and could-not-check runs serial.
Phase README structure
docs/<phase>/README.md ties the briefs together. It carries each numbered item below that
applies under its own ## heading (## Briefs, ## Critical path, ## Dependency waves, …).
The ## Dependency waves section is never folded into the ## Critical path section, even
though both show the critical path:
- Briefs table — generated, not hand-written, once
statusgenis wired up. The table lives between<!-- statusgen:briefs:begin -->/<!-- statusgen:briefs:end -->markers, and the README's own frontmatter carriesboard: generated;statusgenwrites the Status / Verified / Reviewed cells from PR trailers,verifyrunwitnesses and App approvals — a hand edit inside the markers is a lint PROBLEM, the same as hand-editingSTATUS.md. Columns:| # | Brief | Wave | Effort | Status | Verified | Reviewed |, Status a bare lifecycle token (todo/in-progress/implemented/verified/done, the hold tokenblocked, or the off-pathwithdrawn— see "Withdrawing a brief" below). A project not yet wired tostatusgenhand-maintains the older| # | Brief | Wave | Status | What's deployed/landed |shape as a stopgap — ✅ / ⚠ / ❌ with a terse, honest "what's actually true" note (not aspirational) — but the moment generation is live, the table is derived, never hand-edited. Withdrawing a brief. A brief retired by a later decision, or merged into another brief, is never parked asblockedwith prose in its title. Set its Status cell towithdrawn(the link text keeps the original title; preserve existing Verified/Reviewed stamps), switch its frontmatter toschema: brief-v3(the withdrawal keys remain unknown on brief-v1/v2), and add:withdrawn-date: "YYYY-MM-DD",superseded-by: ["<stream>/<NN>" | "<cell>:<alias>:<stream>:<NN>"]([]= won't-fix) and a one-sentencewithdrawn-reason:. Put the banner> **Withdrawn YYYY-MM-DD — superseded by <successor>.** <reason>. Not executable.under the H1. Never delete the file or erase partial implementation, Evidence, stamps or receipts. Keep the existing human decision gate: withdrawal is not permission to bypass it. A withdrawn brief leaves the done ratio, Next-up and the bottleneck views; dependencies remain unsatisfied until explicitly amended. Validate successor chains and review each dependent's scope before re-pointing it. Use a shared, revision-boundwithdrawal-contexthandoff where the amendment has one; preserve observed claims with acknowledged treatment. Runstatusgen withdrawal-auditover the candidate board and an open-PR snapshot before rollout, then reconcile affected implementation and evidence PRs with their owners. Do not auto-close them. Upgrade readers before authoring v3; seedocs/withdrawal-rollout.md. - Critical path — an ASCII chain showing the blocking order, with a one-line "smallest unblocking move" and a warning if any tempting-but-wrong first step is a dead end.
- Dependency waves —
Wave 0: [..] Wave 1: [..]←0 …, plus the one-line critical path (0→8→1→2→5). - Delivery milestones when applicable — link the canonical records and show outcome, contributor wave span, remaining work, acceptance outstanding and prerequisite holds per the shared procedure. Keep generated projections in their own supported region; do not add milestone rows to the Briefs table or hand-edit generated cells. Until supported, put the proposed mapping in the scoping document and link it from authored prose.
- (Optional) "Before starting" prereqs and "Shared conventions" the briefs inherit.
When a spec is approved: file the authoring follow-on in the same motion
A spec or scoping doc reaching approved is not yet work — nothing pulls it forward until
briefs exist, so an approved-but-unrouted spec is exactly the thing that gets forgotten.
Close that edge in the landing motion: whoever lands the PR that marks a spec approved
files, in the same motion, ONE work-ready issue on your tracker titled "Author briefs for
<spec path> into <destination stream> (strong tier)", naming this
assay:author-brief procedure and the strong tier requirement in the body so it rides
your existing issue → work-dispatch lane to a strong-tier author. "Same motion" means the
landing PR is not complete without it: file the issue immediately after the merge, or
reference it from the PR body before merging. Landing those briefs later flips the spec's
status to routed in the citing PR. (An automated emitter may back this floor as a second
layer; the floor does not wait on one.)
Working method
-
Reconcile outcomes and inventory the work — preserve the source's milestone promises; map criterion coverage to existing briefs before adding new units. Follow the shared procedure for milestone dependencies, versions and reader support. Each new unit becomes a brief; keep them roughly equal- sized (split anything too big — e.g. one brief doing two distinct roles becomes two).
-
Map dependencies — for each unit, what must exist first (
Depends on) and what it enables (Unblocks). This gives the waves (Wave 0 = no deps; Wave N = depends only on <N). -
Derive + verify the critical path — for each selected milestone, include its contributing work, actual execution dependencies and final acceptance prerequisites. Validate mixed-graph cycles and qualify paths with unknown root/evidence coverage. Verify the head per the judgment-call section above; a wave summary alone is not readiness.
-
Write the README first (table + path + waves), then the briefs. Cross-link both directions. Minimal skeleton, one
##heading per section:## Briefs ## Critical path ## Dependency waves -
Convert relative dates to absolute (e.g. "by next week" → the actual date) — these docs outlive the conversation.
-
Author the facts and the edges, not the cell. Status is DERIVED, not chosen: write
why:,depends,unblocks,gate,riskaccurately and letstatusgenread the PR trailers, witnesses and approvals into the Status / Verified / Reviewed cells. A project not yet wired tostatusgenkeeps the honesty rule in spirit by hand — "⚠ Workaround" / "Blocked by #X" beats a green checkmark that isn't true — but once generation is live, a hand-edited cell is a lint PROBLEM, not a courtesy. -
Handoff to execution: a brief is a scope-and-DoD contract, not a step-by-step plan — don't write one here. When a brief (especially Effort: L) is picked up for execution, consider running
superpowers:writing-plansagainst that brief's Deliverables/DoD to produce a bite-sized TDD plan before touching code. That's a separate step, done at pickup time by whoever executes it — not part of authoring the brief. -
Link the authoring PR with
Authors:, neverBrief:. The PR that writes brief files carries exactly one link lineAuthors: <stream>/<NN>[, <stream>/<NN> …]naming every brief it adds (orIssue: #<N>when the authoring answers an issue, orFixes: #<N>when merging the authoring PR should close it — never for an issue carryingneeds-decisionorhuman-decided, or any decision-gate issue; those link withIssue: #<N>).Brief: <stream>/<NN>means the PR DELIVERS that brief: the dispatcher's phantom check, the planner and the derived board all read it that way, so an authoring PR carrying it makes the brief it just wrote look delivered the moment it merges, and the brief is never dispatched.deskpr createrefuses aBrief:line on a branch that only authors that brief and names theAuthors:line to use, and refuses anAuthors:line unless the branch adds every listed brief's file and touches nothing but board READMEs, brief files and changelog fragments. A PR that authors a brief AND delivers work in the same change keepsBrief:.
Conventions to inherit
- Briefs are reference docs, not narration — terse, imperative, link to the authoritative source rather than duplicating it.
- When a brief's work lands, fill its Evidence section (one row per Verify item, filled by someone who did NOT implement) and update the README status row + critical path in the same change, so the plan never drifts from reality.
- Docs regeneration: if this project has auto-generated docs or a docs-site that must be regenerated when the public-facing architecture, API surface, user flow, or operational tooling changes, every such brief MUST carry a docs-regeneration item in its DoD naming the specific pages/areas to update. State the project's concrete regen command in the project-level skill (or the repo's instructions file).
- Changelog fragment: if the target repo enforces a per-PR fragment (a
changelog/directory carryingchangelog/README.md), LISTchangelog/<slug>.mdin the brief'sfiles:line —files:is the implementer's contract, and a path absent from it will not get written. The fragment is human-legible highlight bullets, not a restatement of the Task; a genuinely non-notable brief says so in itswhy:and leaves thechangelog:skipwaiver to the desk or a human. Do NOT add a Verify row for it — the repo's CI changelog check IS that row. - Short identifiers: keep identifiers a brief asks for (test function names especially) under 32 characters, and in a PR body describe a long identifier rather than quote it: the desk secret scan reads any 32+ character alphanumeric run as a possible secret.
- If executing a brief surfaces a NEW non-obvious gotcha, fold it into the repo's instructions file (CLAUDE.md / AGENTS.md / etc.) so the next person doesn't rediscover it.
04 同仓库更多 Skills
Bad--Name
A valid description.
not-the-desk
A valid description.
skill
abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde abcde
skill
字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字字 字字字字
skill-9
This is a filler sentence used only to push the summed bundle description character budget over its threshold for the fixture. This is a filler sentence used only to push the summed bundle description character budget over its threshold for the fixture. This is a filler sentence used only to push the summed bundle description character budget over its threshold for the fixture. This is a filler sentence used only to push the summed bundle description character budget over its threshold for the fixture. This is a filler sentence used only to push the summed bundle description character budget over its threshold for the fixture. This is a filler sentence used only to push the summed bundle description character budget over its threshold for the fixture. This is a filler sentence used only to push the summed bundle description character budget over its threshold for the fixture. This is a f
skill-8
This is a filler sentence used only to push the summed bundle description character budget over its threshold for the fixture. This is a filler sentence used only to push the summed bundle description character budget over its threshold for the fixture. This is a filler sentence used only to push the summed bundle description character budget over its threshold for the fixture. This is a filler sentence used only to push the summed bundle description character budget over its threshold for the fixture. This is a filler sentence used only to push the summed bundle description character budget over its threshold for the fixture. This is a filler sentence used only to push the summed bundle description character budget over its threshold for the fixture. This is a filler sentence used only to push the summed bundle description character budget over its threshold for the fixture. This is a f