@jaybeeuu/agent-cortex 1.41.1 → 1.42.0

package/skills/planning/spec-to-tickets/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: spec-to-tickets
+description: Turn a PRD, RFC, or spec into an agreed map of tickets, then draft each ticket body with the human in dependency order. Use when the user says "break this spec into tickets", "turn this RFC into tickets", or "map out the work".
+argument-hint: "The spec to decompose (path or link) and the target tracker"
+---
+
+# Spec to Tickets
+
+Turn one spec into a reviewed graph of tickets. The map is agreed before any body is
+written, the drafts are reviewed as a set, and only then are tickets created.
+
+## When to use
+
+- A PRD, RFC, ADR, or spec is approved and needs to become tickets in a tracker.
+- The user says "break this spec into tickets", "turn this RFC into tickets", or "map out the work".
+- A large change needs a dependency graph before anyone starts implementing.
+
+## When NOT to use
+
+- A single ticket — use `write-a-ticket` directly.
+- Decomposition into beads for the ralph/bd loop — use `prd-to-tasks`.
+- No spec exists yet — use `write-a-prd` or `grill-with-docs` first.
+
+## Philosophy / rationale
+
+- **Agree the graph before the bodies.** Granularity decisions invalidate bodies, so the human approves titles, edges, and scope first. Bodies are cheap to write once the graph is right.
+- **Draft everything, then create once.** Drafts are reviewable artefacts; tickets in a tracker are not. The human reads the whole set before anything is uploaded.
+- **One ticket at a time, then all at once.** Draft each body with the human so decisions stay in the open; review the finished set together so the boundary between tickets is visible.
+- **Less is more.** Tickets stay scannable; the detail lives in the spec the ticket links to.
+
+## Workflow
+
+### Phase 1 — Ingest the spec
+
+1. Confirm the spec is in context (file, link, or paste). If it is missing, stop and ask for it.
+2. Identify the tracker and how tickets are created there — Jira, GitLab, GitHub, or beads, via CLI, MCP, or manual paste. Ask when unclear; the mechanism only affects Phase 6.
+3. Explore the code the spec touches, enough to name the components each ticket will change. You cannot slice work you have not looked at.
+4. Record the durable decisions that apply across every ticket — schema shape, API conventions, auth, shared models — so bodies link to them instead of repeating them.
+
+### Phase 2 — Draft the ticket map
+
+5. Slice the spec into tickets. Each ticket is a coherent unit of change one engineer can pick up and finish — not a layer, not a phase, not a week of work. Prefer more, thinner tickets.
+6. For each ticket record a verb-first title, a one-line intent, the components it touches, and its `depends-on` edges.
+7. Order the graph so dependencies come first, and mark the tickets that can run in parallel.
+
+### Phase 3 — Agree the map
+
+8. Write the map to `.agent-cortex/tickets/<spec-slug>-map.md` in the format from [REFERENCE.md](./REFERENCE.md), then present it. The map carries titles, intents, touchpoints, and edges — no bodies.
+9. Walk the graph with the human: granularity (merge or split), ordering, parallelism, and what is out of scope entirely. Iterate until they approve. Draft no body before this gate passes.
+
+### Phase 4 — Draft every body
+
+10. Walk the graph in dependency order. For each ticket, draft the body with `write-a-ticket` together with the human, and write it to `.agent-cortex/tickets/<spec-slug>/<NN>-<ticket-slug>.md` in the draft format from [REFERENCE.md](./REFERENCE.md). Create nothing yet.
+11. Settle every open question as you draft: resolve it, split a blocking spike ticket, or send the human to find the answer. A question stays open only if the human explicitly agrees — and then it is recorded under `Open questions` with an owner. Ship nothing unresolved that the human has not agreed to.
+
+### Phase 5 — Review the drafts
+
+12. Present the whole draft set for one read-through: titles, bodies, and edges together, so the boundary between tickets is visible.
+13. Iterate until the human approves the set. Nothing is created before this gate passes.
+
+### Phase 6 — Create and backfill
+
+14. Create each ticket through the agreed mechanism, using its approved draft verbatim. [REFERENCE.md](./REFERENCE.md) lists adapter examples.
+15. Backfill the real ID into the map, the draft file, and downstream tickets' dependency references.
+
+### Phase 7 — Report
+
+16. Present the created tickets with their IDs, edges, and any spikes, and note which can start immediately.
+
+Workflow at a glance:
+
+```
+[Spec: PRD/RFC/ADR]
+        |
+        v
+[P1: Ingest + explore code]
+        |
+        v
+[P2: Draft the ticket map]
+        |
+        v
+[P3: Agree the map] --(revise)--> [P2: Draft the ticket map]
+        |
+     (approved)
+        v
+[P4: Draft every body] --(open)--> [Resolve / spike / ask]
+        |
+      (drafted)
+        v
+[P5: Review the draft set] --(revise)--> [P4: Draft every body]
+        |
+     (approved)
+        v
+[P6: Create + backfill IDs]
+        |
+        v
+[P7: Report the graph]
+```
+
+## Red Flags
+
+- **Drafting bodies before the map is agreed.** A granularity change rewrites bodies; agree the graph first.
+- **Creating before the draft set is reviewed.** Drafts are the review artefact; upload only what the human has read.
+- **Layer tickets.** "All the database work" is not a unit of change — every ticket should be independently useful.
+- **Carrying an unagreed open question into a body.** Resolve it, split a spike, or get the human's explicit agreement to leave it open.
+- **A missing `depends-on` edge.** Ordering is the point of the map; an unmodelled dependency surfaces later as a blocked engineer.
+- **Fat tickets.** If a ticket is a week of work, split it.
+
+## Common Rationalizations
+
+| Rationalization | Rebuttal |
+|---|---|
+| "I'll create all the tickets, then refine" | Granularity is agreed first and drafts are reviewed before creation; tickets edited in the tracker leave the map stale. |
+| "The map is obvious — skip writing it down" | The map is the review artefact. The human approves a graph, not a scroll of bodies. |
+| "I'll note the open question in the ticket" | Only with the human's explicit agreement. Otherwise resolve it or spike it — an unagreed question is a blocked implementer. |
+| "One big ticket is simpler to track" | Big tickets hide scope and block parallel work. |
+
+## Cross-skill references
+
+- **`write-a-ticket`** — invoked for every body; owns the ticket quality bar.
+- **`write-a-prd`** — use first when no spec exists.
+- **`prd-to-tasks`** — use when the output is beads for the ralph/bd loop, not external tickets.
+- **`style-comms`** — invoke when drafting the map's titles and intents.
+
+## Phase-gate checklist
+
+- [ ] Phase 1 complete: spec in context, tracker identified, code explored, shared decisions recorded.
+- [ ] Phase 2 complete: map drafted with titles, intents, touchpoints, and edges.
+- [ ] Phase 3 complete: map written to `.agent-cortex/tickets/` and approved by the human.
+- [ ] Phase 4 complete: every body drafted with `write-a-ticket` and written to the draft directory.
+- [ ] Phase 5 complete: the draft set was reviewed and approved as a whole.
+- [ ] Phase 6 complete: all tickets created and IDs backfilled into the map and the drafts.
+- [ ] Phase 7 complete: graph reported with IDs, edges, and spikes.
+
+## Verification checklist
+
+- [ ] No body was drafted before the map was approved.
+- [ ] Every ticket is a coherent unit of change, not a layer or a phase.
+- [ ] Every dependency is modelled as a `depends-on` edge in the map.
+- [ ] Every draft exists under `.agent-cortex/tickets/<spec-slug>/` and was approved before creation.
+- [ ] Every open question shipped was explicitly agreed by the human and has an owner.
+- [ ] Real ticket IDs were backfilled into the map, the drafts, and downstream dependencies.
+- [ ] The map file exists at `.agent-cortex/tickets/<spec-slug>-map.md`.

package/skills/planning/write-a-prd/FORMAT.md

@@ -23,6 +23,12 @@ A LONG, numbered list of user stories. Each user story should be in the format o
 
 This list of user stories should be extremely extensive and cover all aspects of the feature.
 
+## Success Criteria
+
+The high-level, verifiable outcomes that mean this feature succeeded. This is the epic's
+`## Success Criteria` (required by `bd create --validate`) — distinct from the per-task
+acceptance criteria that `prd-to-tasks` derives later.
+
 ## Implementation Decisions
 
 A list of implementation decisions that were made. This can include:

package/skills/planning/write-a-prd/SKILL.md

@@ -14,18 +14,18 @@ description: Create a PRD through user interview, codebase exploration, and modu
 ## When NOT to use
 
 - The idea is not ready to build yet — use `record-idea` to capture it to the backlog.
-- The output targets a human team's external tracker — use `write-a-ticket`.
-- A PRD already exists and needs breaking into tasks — use `prd-to-tasks`.
+- The output targets a human team's external tracker — use `write-a-ticket` for one ticket, or `spec-to-tickets` to break a spec into many.
+- A PRD already exists and needs breaking down — use `prd-to-tasks` for beads, or `spec-to-tickets` for external tickets.
 - The scope is a refactor needing a safe incremental plan — use `request-refactor-plan`.
 
 ## Workflow
 
 1. **Gather the problem statement.** Ask the user for a long, detailed description of the problem and any potential solution ideas. Ask one question at a time.
 2. **Explore the codebase.** Verify the user's assertions against the repo's current state. Explore instead of asking when the answer lives in code.
-3. **Interview relentlessly.** Walk down each branch of the design tree, resolving dependencies between decisions one by one, until the user's understanding and yours are identical. Every open question at this point becomes ambiguity in the PRD.
+3. **Interview relentlessly.** Walk down each branch of the design tree, resolving dependencies between decisions one by one, until the user's understanding and yours are identical. The epic's required sections — `## Success Criteria` in particular — are the interview's target: it is complete only when there is enough agreed detail to fill every required section. Never invent an answer; surface it as an assumption and confirm it with the user.
 4. **Sketch the modules.** List the major modules to build or modify, actively looking for deep modules — ones that encapsulate rich behaviour behind a simple, stable interface testable in isolation. Confirm the list with the user, plus which modules they want tests written for.
-5. **Write the PRD.** Render the template in `FORMAT.md` (Problem Statement, Solution, User Stories, Implementation Decisions, Testing Decisions, Out of Scope, Further Notes). Make the user-story list extremely extensive so it covers all aspects of the feature.
-6. **File the bead.** Create the epic with `bd create "<title>" --type epic --priority P1 --body-file -`, piping the rendered PRD to stdin, then run the `classify-bead` classifier (`node <this-skill-dir>/../classify-bead/scripts/classify-bead.mjs <epic-id>`, run from the target project's cwd) to label it AFK or HITL. Escalate to the `classify-bead` subagent only when the classifier reports `escalate: true`.
+5. **Write the PRD.** Render the template in `FORMAT.md` (Problem Statement, Solution, User Stories, Success Criteria, Implementation Decisions, Testing Decisions, Out of Scope, Further Notes). Make the user-story list extremely extensive so it covers all aspects of the feature.
+6. **File the bead.** Create the epic with `bd create "<title>" --type epic --priority P1 --body-file - --validate`, piping the rendered PRD to stdin, then run the `classify-bead` classifier (`node <this-skill-dir>/../classify-bead/scripts/classify-bead.mjs <epic-id>`, run from the target project's cwd) to label it AFK or HITL. Escalate to the `classify-bead` subagent only when the classifier reports `escalate: true`. Finally run `bd lint <epic-id>` and fix any missing sections before reporting.
 
 Run the steps in order. Skip a step only when the user confirms it is unnecessary (e.g. the codebase is already explored).
 
@@ -52,12 +52,13 @@ Run the steps in order. Skip a step only when the user confirms it is unnecessar
 
 - [ ] Gate 1 — shared understanding: every design-tree branch resolved and the user confirms the summary.
 - [ ] Gate 2 — modules agreed: the module list and test expectations match the user's model of the solution.
-- [ ] Gate 3 — PRD filed: the epic bead contains the rendered template and carries an implementation-type label.
+- [ ] Gate 3 — PRD filed: the epic bead contains the rendered template, carries an implementation-type label, and lints clean.
 
 ## Cross-skill references
 
 - Use `record-idea` when the idea is not yet ready to build.
 - Use `write-a-ticket` when the spec targets an external tracker rather than a bead.
+- Use `spec-to-tickets` when an approved PRD/RFC must become a map of external tickets.
 - Run `prd-to-tasks` on the filed epic to break the PRD into an executable backlog.
 - Run the `classify-bead` classifier on the new epic — the repo labels every new bead AFK or HITL. Its `scripts/` directory sits next to this skill's directory in every harness, so `<this-skill-dir>/../classify-bead/scripts/classify-bead.mjs` resolves it. Escalate to its rubric subagent only when the classifier reports `escalate: true`.
 
@@ -69,6 +70,8 @@ Output: an epic bead whose description is the rendered PRD — problem, solution
 ## Verification checklist
 
 - [ ] Template in `FORMAT.md` rendered fully, with no placeholder sections.
+- [ ] `## Success Criteria` present and the epic created with `--validate`.
+- [ ] `bd lint <epic-id>` reports no missing sections.
 - [ ] Every user story follows "As an <actor>, I want <feature>, so that <benefit>".
 - [ ] Codebase assertions verified against the repo before writing.
 - [ ] Implementation Decisions contains no file paths or code snippets.

package/skills/planning/write-a-ticket/EXAMPLES.md

@@ -0,0 +1,133 @@
+# Write a Ticket — Examples
+
+Worked before/after rewrites for the `write-a-ticket` skill.
+
+## A whole ticket: padded vs tight
+
+The padded version is the failure mode this skill exists to prevent: it explains the RFC,
+prescribes an implementation, says nothing about scope, and leaves a question open. The
+tight version points at the source material, states the behaviour, draws the boundary, and
+gives an entry point.
+
+### Padded
+
+```markdown
+## Context
+
+We are moving our billing stack to a new provider. The current provider has had several
+outages this year, which has affected customer trust. The Q3 billing review evaluated
+Stripe, Paddle, and Chargebee; Paddle was chosen because of EU data residency. The
+meeting notes are attached. There was also discussion about whether to migrate in one go
+or incrementally, and about how to handle existing subscriptions.
+
+## Description
+
+We need to migrate to Paddle. This involves adding the Paddle SDK, creating a webhook
+handler, migrating the subscription records, updating the pricing page, and changing the
+retry logic. Step 1: install the SDK. Step 2: add a webhook handler that verifies the
+signature. Step 3: write a migration script …
+
+## In scope
+
+- The migration
+
+## Acceptance criteria
+
+- [ ] The migration works correctly
+- [ ] The feature is tested
+- [ ] Payments still work
+
+## Open questions
+
+- Do we migrate annual subscriptions too, or only monthly?
+```
+
+### Tight
+
+```markdown
+## Context
+
+Part of the billing migration epic (BILL-412). Approach and provider decision in
+RFC-018 §2; retry policy in ADR-014. Depends on the Paddle webhook receiver (BILL-420).
+
+## Description
+
+When a Paddle webhook fails with a transient error, the handler retries with the shared
+backoff policy. Non-transient failures are logged and acknowledged without retry. The
+existing provider path is unchanged.
+
+## In scope
+
+- Retry of transient Paddle webhook failures with the shared backoff policy.
+- Provider selection in the payment factory.
+- Structured logging of terminal webhook failures.
+
+## Out of scope
+
+- Subscription record migration (BILL-421).
+- Pricing-page changes (BILL-422).
+- Provider cutover and production enablement.
+
+## Acceptance criteria
+
+- [ ] A webhook returning 503 is retried up to 3 times with exponential backoff.
+- [ ] A webhook returning 422 is not retried and is logged with the payload.
+- [ ] The retry counter is per webhook event, not per process.
+- [ ] The existing Stripe retry specs pass unchanged.
+
+## Testing approach
+
+Integration spec in `test/webhooks/retry.spec.ts` against the Paddle sandbox, asserting
+the 503-then-200 path and the terminal 422 path.
+
+## Technical notes
+
+- **Entry point:** `src/payments/paddle.ts:41` (`handleWebhook`, `shouldRetry`)
+- `retry()` from `@acme/retry-utils`; follow `src/payments/stripe.ts` for the handler shape.
+- `handleWebhook` becomes async — update its call site in `src/payments/index.ts:12`.
+```
+
+The tight version is shorter, answers the reviewer's questions, and still leaves the
+implementation to the implementer.
+
+## Description: states the goal vs explains the RFC
+
+| Instead of… | Write… |
+| "We need to migrate to Paddle. The provider was chosen after a review of Stripe, Paddle and Chargebee, and there was discussion about whether to migrate incrementally. This ticket covers the retry logic, which is important because outages cost us customers. Step 1: …" | "When a Paddle webhook fails with a transient error, the handler retries with the shared backoff policy. Non-transient failures are logged and acknowledged without retry." |
+
+The Description states what the ticket does and the behaviour it produces. It leads into the
+scope bullets — the RFC link and the deliberation stay in Context or the source document.
+
+## Padded context vs linked context
+
+| Instead of… | Write… |
+| "We are moving to a new billing provider because the current one has outages. The provider was chosen in the Q3 billing review (attached meeting notes, see thread in #billing where we discussed Stripe vs Paddle vs Chargebee; conclusion was Paddle due to EU data residency). This ticket tracks the work agreed there." | "Part of the billing migration epic (BILL-412). Approach in RFC-018 §2. Depends on the Paddle webhook receiver (BILL-420)." |
+
+Context is a pointer block: parent, where the approach lives, what it depends on. It does
+not recap the deliberation.
+
+## Vague vs verifiable acceptance criteria
+
+| Instead of… | Write… |
+| "The export works correctly" | "Given a workspace with 1,000 issues, the CSV export returns all rows with no truncation" |
+| "The feature is tested" | "Unit tests cover the retry path for transient HTTP 503 responses" |
+| "The migration runs" | "The migration completes without errors on a staging copy of the production database" |
+
+## Technical notes: entry point vs full inventory
+
+| Instead of… | Write… |
+| "Step 1: install the SDK via `pnpm add @acme/paddle`. Step 2: add a webhook handler that verifies the signature and … (10 more steps)" | "- **Entry point:** `src/payments/paddle.ts:41` (`handleWebhook`, `shouldRetry`)" |
+| "Files to change: `paddle.ts`, `index.ts`, `stripe.ts`, `retry.ts`, `types.ts`, `webhook.ts`, `config.ts`" | "- **Entry point:** `src/payments/paddle.ts:41` (`handleWebhook`, `shouldRetry`)<br>- Follow `src/payments/stripe.ts` for the handler shape." |
+
+Technical notes lead with the entry point and then give only the facts that change how the
+work is done — a signature, a library, a convention. They are neither an inventory of every
+file touched nor a step-by-step guide; either of those means the ticket has become the code.
+
+## Open questions: agreed vs smuggled
+
+An open question is legitimate when the human has agreed to it: it goes under
+`Open questions` with the owner of the answer. A question the human has not agreed to is a
+red flag wherever it appears — resolve it, spike it, or ask.
+
+| Instead of… | Write… |
+| A question buried in `Technical notes` or a `Notes` section, with no owner and no agreement | "## Open questions<br>- Do annual subscriptions migrate too? (owner: Priya)" |

package/skills/planning/write-a-ticket/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: write-a-ticket
-description: Write a well-structured ticket for an external issue tracker (e.g. Jira) that an engineer can act on without follow-up questions. Use when asked to "write a ticket", "file this in Jira", or "create a work item" — not for creating implementation tasks in a ralph/bd loop.
+description: Write a clear, reviewable ticket for an external issue tracker (Jira, Linear, GitLab, GitHub Issues) that an engineer can act on without follow-up questions. Use when asked to "write a ticket", "file this in Jira", or "create a work item" — not for beads in a ralph/bd loop.
 argument-hint: "The work to ticket: goal, epic/initiative, constraints, or paste a draft"
 ---
 
@@ -9,104 +9,122 @@ argument-hint: "The work to ticket: goal, epic/initiative, constraints, or paste
 ## When to use
 
 - Asked to "write a ticket", "file this in Jira", or "create a work item".
-- Drafting an actionable work item for a human engineering audience in an external issue tracker (Jira, Linear, GitHub Issues).
-- Checking an existing ticket for clarity before it goes to the team.
+- Drafting an actionable work item for a human engineering audience in an external tracker.
+- Reviewing an existing ticket for clarity before it goes to the team.
 
 ## When NOT to use
 
-- Creating implementation tasks for the ralph/bd loop — those are beads executed by agents, not tickets read by engineers.
-- Writing a requirements document for a feature that is not yet actionable — run `write-a-prd` first and link the PRD from the ticket.
+- Breaking a whole PRD/RFC/spec into many tickets — use `spec-to-tickets`, which calls this skill per ticket.
+- Creating implementation tasks for the ralph/bd loop — those are beads executed by agents; use `prd-to-tasks` or `create-task`.
+- Writing a requirements document for work that is not yet actionable — run `write-a-prd` first.
 
 ## Workflow
 
-1. **Gather context.** Confirm the goal of the work, the epic/RFC/initiative it belongs to (if any), known constraints or decisions, and relevant code locations, schemas, or prior art. Outcome: you can state the ticket's purpose in one sentence. If you cannot, ask before writing.
+1. **Gather context.** Confirm the goal, the parent ticket or epic, the spec it follows, the decisions already made, and the entry point in the code. Outcome: you can state what this ticket does in one sentence. If you cannot, ask before writing.
 
-2. **Draft the ticket.** Work through the template below. Every section has a purpose — write it only if it earns its place, and never omit a required section without recording why.
+2. **Settle open questions.** Resolve every question with the human while drafting. When a question cannot be resolved now, split a blocking spike ticket and depend on it, or ask the human to find the answer. A question may stay in the body only when the human explicitly agrees to leave it open — record it under `Open questions` with the owner of the answer. Ship no question the human has not agreed to.
+
+3. **Draft the body** from the template below, then check it against the format rules and the verification checklist.
+
+4. **Hand over the draft.** Present the body for review and get the human's agreement before it is created or filed. The draft is the review artefact — nothing reaches the tracker unseen.
 
 ```markdown
 ## Context
 
-<1–3 sentences: why this work exists, and which epic/RFC/ADR it belongs to. Link to it — never copy-paste its content.>
+<1–5 sentences of pointers: parent ticket or epic, where the approach lives
+(RFC/ADR section), the decisions already made, and what this depends on.
+Reference these — do not explain them.>
 
 ## Description
 
-<What to build or change. Describe the outcome, not the implementation steps, and state scope explicitly — what is in and what is out.>
+<2–4 sentences. What this ticket does and the behaviour it produces — the goal,
+stated as the lead-in to the scope bullets. Leave detail to the sections below.>
 
-## Acceptance criteria
+## In scope
 
-- [ ] <Specific, independently verifiable criterion — e.g. "given X, the API returns Y">
-- [ ] <...>
+- <a distinct deliverable this ticket owns>
+- <...>
 
-## Technical notes
+## Out of scope
 
-<Links to relevant code, agreed schemas, architectural decisions, or upstream constraints. A pointer, not a design document — decisions that need more space belong in an ADR or RFC.>
+- <adjacent work explicitly not included — name the ticket that owns it where known>
 
-## Testing strategy
+## Acceptance criteria
 
-<Optional. Only when testing needs are non-obvious or a level was agreed — unit, integration, contract, E2E. Omit when team defaults apply.>
+- [ ] <independently verifiable check>
+- [ ] <...>
 
-## Monitoring strategy
+## Testing approach
 
-<Optional. Only when the change adds metrics, alerts, log events, dashboards, or a phased rollout. Omit when there is no meaningful observability footprint.>
+<Optional. Which specs, what they assert, and any setup gotcha. Omit when team
+defaults apply.>
 
-## Notes
+## Technical notes
 
-<Optional. Genuinely useful details with no other home. If you reach for this often, restructure the ticket.>
+- **Entry point:** `path/to/file.ts:42` (`symbol`, `symbol`)
+- <a decisive fact: a signature that changes, a library or convention to follow,
+  a field injected elsewhere>
+
+## Open questions
+
+<Optional, and only when the human has explicitly agreed to leave a question
+open. One bullet per question, each naming who owns the answer. Omit this
+section when there are none.>
 ```
 
-3. **Review against the checklist.** Work through the verification checklist below before finalising.
+### Format rules
+
+- **Link, don't copy.** Reference the spec by link or section; never paraphrase it. A reader who needs the rationale opens the source.
+- **Point at the entry, not the inventory.** Technical notes lead with the entry point — 1–3 links to where the work begins — plus only the facts that change how it is done. A full list of touched files means you have written the code in prose.
+- **Scope is the contract.** In scope and Out of scope say what the ticket owns; Technical notes only show where to begin.
+- **Every bullet is a distinct deliverable or check.** Merge any two that restate each other, and cut any that add neither.
+- **Bullets over paragraphs, and no tables in the body** — trackers render tables inconsistently and they are slow to scan.
+- **Budgets are guidance, not limits.** Context ≤ 3 sentences; Description ≤ 4 sentences; In scope ≤ 8 bullets; Out of scope ≤ 6 bullets; Acceptance criteria ≤ 12 items; Technical notes ≤ 6 bullets. Extend a section when the work genuinely needs it — a larger scope, or detail that makes the goal clearer — but treat that as the exception, not the rule. Aim for the smallest body that is still complete.
 
 ## Red Flags
 
-- Writing implementation steps into the description — describe the outcome, not the how.
+- Writing the code in prose — listing every file touched, or stepping through the edits.
+- A Description that explains the RFC or the deliberation instead of stating what this ticket does.
 - Acceptance criteria that cannot be verified: "works correctly", "is tested".
-- Copy-pasting context instead of linking to the epic, RFC, or ADR.
-- Padding sections with filler to look complete — a short, accurate ticket beats a padded one.
-- Omitting a required section without recording why.
+- Padding a section to reach a budget, or exceeding one without the work to justify it.
+- Copy-pasting spec content instead of linking to it.
+- Leaving a question, `TBD`, or "we need to decide" in the body when the human has not agreed to it — an unagreed open question is a blocked implementer.
 
 ## Common Rationalizations
 
-| Rationalization | Rebuttal |
-|---|---|
-| "The engineer will figure it out" | Skilled engineers can — but questions are a blocked ticket. The ticket must stand alone. |
-| "More detail is safer" | Detail only helps if it informs the implementer. Every extra sentence is noise to skim. |
-| "We will verify acceptance criteria in review" | Unverifiable criteria cannot be checked. Write given/outcome pairs instead. |
-| "We will discuss the details in standup" | The ticket is the record. If it cannot stand alone, the discussion is lost. |
+| Rationalization                              | Rebuttal                                                                                                                          |
+| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| "The engineer will figure it out"            | Skilled engineers can — but questions are a blocked ticket. The ticket must stand alone.                                          |
+| "More detail is safer"                       | Detail helps only if it informs the implementer. Every extra sentence is noise to skim.                                           |
+| "The reviewer should see every file touched" | The reviewer needs the scope and somewhere to start, not an inventory. The implementer finds the rest.                            |
+| "I'll flag the open question in the ticket"  | Only if the human agrees to leave it open. Otherwise resolve it or split a spike — an unagreed question is a blocked implementer. |
 
 ## Philosophy / rationale
 
-- **Write for clarity, not coverage.** A ticket is not a specification. One well-chosen sentence beats three that say the same thing.
-- **Describe the outcome, not the implementation.** The ticket owns the what and why; the implementer owns the how.
-- **A ticket must stand alone.** Link, don't copy — readers who need the full rationale should open the linked document, not a paraphrase.
+- **Write for clarity, not coverage.** Every line carries a fact; a long ticket of facts beats a short one of filler. Aim for the smallest body that is still complete, and extend a section only when the work demands it.
+- **Scope is the contract.** In scope and Out of scope make the boundary reviewable at a glance.
+- **Describe the behaviour, not the implementation.** The ticket owns the what and why; the implementer owns the how.
+- **A ticket must stand alone.** Link, don't copy — readers who need the full rationale open the linked document, not a paraphrase.
 
 ## Cross-skill references
 
-| When you need… | Use this skill |
-|---|---|
-| Tone, structure, and concision for human-facing writing | `style-comms` |
-| A requirements document that precedes the ticket | `write-a-prd` |
-
-## Examples
-
-### Vague vs verifiable acceptance criteria
-
-| Instead of… | Write… |
-|---|---|
-| "The export feature works" | "Given exports enabled, selecting 'Export CSV' downloads `<account>-export-<date>.csv`" |
-| "Adds tests for the new endpoint" | "POST /v1/orders returns 201 with the created order for valid input and 422 with field errors for schema violations" |
-
-### Context that links vs context that copies
+| When you need…                                          | Use this skill    |
+| ------------------------------------------------------- | ----------------- |
+| To break a spec into a map of tickets                   | `spec-to-tickets` |
+| Tone, structure, and concision for human-facing writing | `style-comms`     |
+| A requirements document that precedes the ticket        | `write-a-prd`     |
 
-| Instead of… | Write… |
-|---|---|
-| Four paragraphs paraphrasing the ADR | "Follows ADR-014 (token refresh). This ticket adds only the retry path — see ADR link." |
+See [EXAMPLES.md](./EXAMPLES.md) for worked before/after rewrites.
 
 ## Verification checklist
 
-- [ ] Context explains why the work exists; the reader needs no other tab open
-- [ ] Description states the outcome, not implementation steps, and defines scope
-- [ ] Acceptance criteria are independently verifiable — no "works correctly" or "is tested"
-- [ ] Technical notes link to code or schemas without prescribing the solution
-- [ ] Testing/Monitoring/Notes present only when they add non-obvious information
-- [ ] Every sentence passes the "does this add information?" test
-- [ ] A skilled engineer can start immediately with zero follow-up questions
+- [ ] Context points at the parent, the approach, and the dependencies without explaining them
+- [ ] Description states the goal and behaviour and leads into the scope bullets
+- [ ] In scope and Out of scope are explicit, with every bullet a distinct deliverable
+- [ ] Acceptance criteria are independently verifiable and none restate another
+- [ ] Technical notes lead with the entry point and give only decisive facts
+- [ ] Testing approach and Technical notes appear only when they add non-obvious information
+- [ ] Every section is within its guidance budget, or the extra is justified by the work
+- [ ] Any open question is one the human explicitly agreed to, listed under `Open questions` with an owner
+- [ ] A skilled engineer can start immediately with zero follow-up questions
+- [ ] The human reviewed the drafted body before it was created

package/skills/productivity/bd-tool/SKILL.md

@@ -43,13 +43,13 @@ For new tasks with pipeline expansion:
 
 ```bash
 # use the create-task skill, or manually:
-bd create "<title>" -d "<description>" -p <0-3>
+bd create "<title>" -d "<description>" -p <0-3> --validate
 ```
 
 For parent-child relationships (create with `--parent`):
 
 ```bash
-bd create "<title>" --parent <parent-id>
+bd create "<title>" --parent <parent-id> --validate
 ```
 
 For blocking dependencies between beads:
@@ -58,6 +58,31 @@ For blocking dependencies between beads:
 bd dep add <id> <blocked-by-id> --type blocks
 ```
 
+### Required sections
+
+Create substantive beads with `--validate` so a section-less bead is rejected before it is
+recorded. `bd create --validate` requires these sections per type (matching is case-insensitive);
+`bd lint` checks the same contract on existing beads and exits non-zero when any are missing:
+
+| Type | Required sections |
+|---|---|
+| `task`, `feature` | `## Acceptance Criteria` |
+| `epic` | `## Success Criteria` |
+| `bug` | `## Steps to Reproduce`, `## Acceptance Criteria` |
+| `chore` | none |
+
+Plan what you write: the type's required sections are the target of the planning interview
+(`write-a-prd`, `request-refactor-plan`, `plan`, `grill-me`, …). Do not invent section content —
+surface an assumption and confirm it with the human. Chore beads carry no required sections; their
+description should reference the parent/requirements bead rather than restating criteria.
+
+Review after creating — lint the beads you just made and fix any flagged ones:
+
+```bash
+bd lint <new-id>...      # scoped to your beads; exits non-zero on missing sections
+bd lint                  # the whole open backlog (may flag pre-existing beads)
+```
+
 ## Completing work
 
 ```bash

package/skills/productivity/grill-me/SKILL.md

@@ -8,3 +8,14 @@ Interview me relentlessly about every aspect of this plan until we reach a share
 Ask the questions one at a time.
 
 If a question can be answered by exploring the codebase, explore the codebase instead.
+
+## Completion: the bead's required sections
+
+When this interview feeds a bead, the bead type's required sections are the target — their
+contract is in the `bd-tool` skill's "Required sections" table (task/feature → `## Acceptance
+Criteria`; epic → `## Success Criteria`; bug → Steps to Reproduce + Acceptance Criteria). The
+interview is complete only when there is enough agreed detail to fill every required section.
+
+Never invent section content. If you must infer an answer, state it as an assumption and get the
+human to confirm it before it becomes bead content. Leave unresolved branches open — an open
+question is better than a fabricated answer.