@jaybeeuu/agent-cortex 1.41.1 → 1.43.0

package/skills/planning/prd-to-tasks/REFERENCE.md

@@ -7,7 +7,7 @@ Body templates used in the Phase 3 and Phase 4 workflow steps of `SKILL.md`.
 Passed as the `--description` when creating an epic bead:
 
 ```bash
-bd create "<Phase Title>" --type epic --description "<epic body below>"
+bd create "<Phase Title>" --type epic --description "<epic body below>" --validate
 ```
 
 ```markdown
@@ -23,7 +23,7 @@ A concise description of this phase. Scope and goal, not implementation details.
 
 End-to-end behaviour for this phase. What a demo would show.
 
-## Acceptance criteria
+## Success Criteria
 
 - [ ] Criterion 1
 - [ ] Criterion 2

package/skills/planning/prd-to-tasks/SKILL.md

@@ -50,17 +50,21 @@ execute. The epic bead is the source of truth — no intermediate plan file.
    complete through all integration layers, demoable or verifiable on its own, and
    covering a specific set of user stories.
 5. For each phase define its **title**, **user stories covered**, **what to build**
-   (end-to-end behaviour, not layer-by-layer), and **acceptance criteria**.
+   (end-to-end behaviour, not layer-by-layer), and **success criteria** — the epic's required
+   `## Success Criteria`. The interview is complete only when every phase has agreed criteria;
+   never invent them.
 6. Present the proposed phases and ask about granularity, merges or splits, and which
    phases can run in parallel. Iterate until the user approves.
 
 ### Phase 3 — Create epics (one per phase)
 
 7. Create epics in dependency order (blockers first) so you can reference real bead IDs,
-   using the epic body template in [REFERENCE.md](./REFERENCE.md):
+   using the epic body template in [REFERENCE.md](./REFERENCE.md). The body must carry
+   `## Success Criteria`; `--validate` rejects it otherwise:
 
    ```bash
-   bd create "<Phase Title>" --type epic --description "<epic body from REFERENCE.md>"
+   bd create "<Phase Title>" --type epic --description "<epic body from REFERENCE.md>" --validate
+   bd lint <epic-id>
    ```
 
 8. Tag each epic with a priority (`p3` default; adjust for p4/p5), and `workflow:ralph`
@@ -127,7 +131,7 @@ Epic: "Phase 2 — Dashboard" (#127) — AFK (blocked by #123)
 - [ ] Phase 1 complete: PRD confirmed, codebase explored, architectural decisions captured.
 - [ ] Phase 2 complete: phases drafted and approved by the user.
 - [ ] Phase 3 complete: epics created in dependency order and tagged (priority, plus
-      `workflow:ralph` under ralph-plan/ralph).
+      `workflow:ralph` under ralph-plan/ralph), and `bd lint` clean.
 - [ ] Phase 4 complete: tasks created via `create-task`; epics carry the aggregate
       `implementation-type` tag.
 - [ ] Phase 5 complete: full bead tree presented and confirmed.
@@ -137,6 +141,7 @@ Epic: "Phase 2 — Dashboard" (#127) — AFK (blocked by #123)
 - [ ] Every phase is a vertical slice covering all layers, not a horizontal layer.
 - [ ] Every task is independently grabbable by a single agent.
 - [ ] All epics are tagged with a priority (and `workflow:ralph` when under ralph).
+- [ ] Epics created with `--validate`; `bd lint` reports no missing sections for the created tree.
 - [ ] All tasks are classified AFK/HITL via `create-task`.
 - [ ] Parent epics carry the aggregate `implementation-type` tag.
 - [ ] No intermediate plan file was created — epics are the source of truth.

package/skills/planning/request-refactor-plan/FORMAT.md

@@ -10,6 +10,11 @@ The problem that the developer is facing, from the developer's perspective.
 
 The solution to the problem, from the developer's perspective.
 
+## Acceptance Criteria
+
+- [ ] <criterion 1>
+- [ ] <criterion 2>
+
 ## Commits
 
 A long, detailed implementation plan in plain English, broken into the tiniest commits possible. Each commit should leave the codebase in a working state.

package/skills/planning/request-refactor-plan/SKILL.md

@@ -32,7 +32,7 @@ description: Create a detailed refactor plan via user interview, split into tiny
    - **description**: the refactor plan formatted with the template in `FORMAT.md`
    - **priority**: P2
 
-   Always invoke `create-task` — never `bd create` directly. `create-task` classifies the bead and expands AFK tasks into pipeline stage beads for ralph.
+   Always invoke `create-task` — never `bd create` directly. `create-task` classifies the bead and expands AFK tasks into pipeline stage beads for ralph. The description must include the template's `## Acceptance Criteria` — the plan's definition of done, agreed in the interview rather than invented — or `create-task`'s `--validate` gate rejects it.
 
 ## Red Flags
 
@@ -81,4 +81,5 @@ Output: a P2 bead filed via `create-task` whose description follows the `FORMAT.
 - [ ] Test coverage assessed; testing plan recorded when coverage is insufficient.
 - [ ] Commit plan written with every commit leaving the codebase working.
 - [ ] Decision Document contains decisions only — no file paths or code snippets.
-- [ ] Bead filed via `create-task` with concise title, `FORMAT.md`-formatted description, priority P2.
+- [ ] Bead filed via `create-task` with concise title, `FORMAT.md`-formatted description, priority P2.
+- [ ] Description carries agreed `## Acceptance Criteria`; the bead was created with `--validate` and lints clean.

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

@@ -0,0 +1,82 @@
+# Spec to Tickets — Reference
+
+Supporting formats for `spec-to-tickets`. Load this when writing the map, drafting tickets,
+or creating them.
+
+## Ticket map format
+
+Written to `.agent-cortex/tickets/<spec-slug>-map.md` at Phase 3 step 8. `.agent-cortex/*`
+is gitignored, so the map is a local review artefact — not a committed plan file.
+
+```markdown
+# <Spec title> — ticket map
+
+- **Source:** <link or path to the PRD/RFC/spec>
+- **Tracker:** <Jira | GitLab | GitHub | beads>
+- **Status:** draft | agreed | created
+
+## Shared decisions
+
+- <schema/API/auth decision every ticket relies on, with a link>
+
+## Tickets
+
+| # | Title | Intent | Touches | Depends on | Ticket ID |
+|---|---|---|---|---|---|
+| T1 | Add grease sampling to the monitor | Read grease levels alongside oil on each poll | `src/monitor/` | — | — |
+| T2 | Surface grease readings in the dashboard | Show grease next to oil on the status panel | `src/web/` | T1 | — |
+
+## Ordering
+
+T1 -> T2, T3    (T2 and T3 can run in parallel)
+
+## Out of scope
+
+- <work the spec mentions that these tickets deliberately exclude>
+```
+
+Set `Status` to `agreed` at Phase 3, and fill `Ticket ID` as each ticket is created in Phase 6.
+
+## Ticket draft format
+
+Written to `.agent-cortex/tickets/<spec-slug>/<NN>-<ticket-slug>.md` at Phase 4 step 10 —
+one file per ticket, numbered in dependency order. Drafts are the review artefact for
+Phase 5 and the source of the created ticket body.
+
+```markdown
+# <Ticket title>
+
+- **Map ref:** T1
+- **Depends on:** T2, T3
+- **Ticket ID:** — (filled at creation)
+
+---
+
+<body from write-a-ticket>
+```
+
+Fill `Ticket ID` at Phase 6. Upload the body verbatim; record `Depends on` in the tracker's
+own link or dependency field when it has one.
+
+## Tracker adapters
+
+The tracker and mechanism are chosen in Phase 1 step 2. These are illustrative examples,
+not a fixed contract — confirm the real command or tool with the human before creating.
+
+| Tracker | Example creation mechanism |
+|---|---|
+| GitHub | `gh issue create --title "<title>" --body-file <draft-body.md> --label <label>` |
+| GitLab | `glab issue create --title "<title>" --description "<body>"` |
+| Jira | the configured Jira CLI or MCP tool for issue creation |
+| beads | `bd create "<title>" --description "<body>" --validate` |
+
+Keep the approved draft verbatim — do not reformat it for the tracker. After creation,
+copy the returned ID into the map's `Ticket ID` column, the draft's `Ticket ID` field, and
+downstream `Depends on` cells.
+
+## Worked run
+
+Input: an approved RFC with eight numbered requirements and a target GitLab project.
+Output: `.agent-cortex/tickets/checkout-v2-map.md` agreed in chat, eight drafts under
+`.agent-cortex/tickets/checkout-v2/` reviewed as a set, then eight GitLab issues created in
+dependency order with real IDs backfilled into the map and the drafts.

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)" |