User Story

user-story

A guided path from "build me X" to integrated, verified work on main. Two ideas run through all of it:

The orchestrator holds the plan; executors hold implementation. Before dispatch, the orchestrator decides what improvement is worth making, its concrete benefit, the approach, and boundaries. Researchers return facts and bounded alternatives for that judgment. Executors use ordinary local coding judgment to implement the selected plan, then return concrete evidence when it cannot work. They do not silently replace the agenda, architecture, or scope.

The ceremony scales to the evidence. A deterministic done-oracle is enough when it covers the contract. Add independent review only for a named untested seam or safety-sensitive risk.

Board mechanics live in the sidequest skill (claim lifecycle, dispatch fields, routing, publish transaction) and its references/. Read ../sidequest/references/orchestration.md before a first wave. This skill is the sequence and the sizing, not a second copy of those rules.

Size it first

Sizing is a call you make and state in a line, not a question you ask the user. Read these signals:

• Independently checkable pieces: one, a handful, or many.
• Surfaces crossed: one module, or store plus CLI plus MCP plus UI plus hooks plus docs.
• Reversibility: a schema, migration, on-disk format, wire format, or public API is expensive to undo. Internal helpers are not.
• Is the approach contested? More than one defensible architecture, with real trade-offs between them, is the single strongest reason to run a design panel.
• Blast radius: does existing behavior change for people already using this?
• Stakes: data loss, auth, money, the release path itself.

Three sizes, and what each dial does at each:

Escalate mid-flight when evidence says so. A spike that comes back reporting the seam is worse than expected raises the size; write that in the story log so the jump is on the record and not a vibe. De-escalating is equally fine: if the panel converges on one obvious answer, stop paying for the panel.

Planning checkpoint

Before dispatching a substantial or ambiguous feature, put one visible, pinned contract on the story, a planning ticket, or the ticket descriptions. It is the handoff from planning to execution, not a second design process. Pin:

• Outcome and explicit non-goals, so later work has a boundary to cut against.
• Smallest authority and intervention, the actual call flow and source of truth that decide behavior. Question whether a change is needed; reuse local code, stdlib, native features, or installed dependencies; make one minimal shared-root fix. Prefer measured deletion over hypothetical guards, forced extractions, and unrelated cleanup. Preserve validation at trust boundaries, data-loss prevention, accessibility, permissions, and immutable candidate/review authority.
• Surgical boundaries, the files each piece may change and every public surface it may expose or deliberately leave alone.
• A bounded executable done-oracle per piece, the behavior it observes, and the named consumer or regression input that would fail if the piece were wrong.
• Review budget, from the sizing table, including the exact reason an oracle alone is enough or the lens a review ticket must cover.
• Design-reopen evidence, concrete findings that would invalidate the contract, such as a consumer that cannot use the pinned seam, a required compatibility break, or an oracle that cannot observe the claimed outcome.

Exact small work keeps its lightweight path: state the outcome and oracle and dispatch one ticket. A pinned contract does not earn proposal theater. Write one authored contract for settled work; use two or three bounded proposals only when the approach is genuinely contested.

The shape

1. Frame the outcome, check this flow applies, and state the size.
2. Recon, bounded, at the depth the size calls for.
3. One question round, or none.
4. Design: write the contract, or run a panel and merge the winner.
5. Story plus the complete backlog for every planned wave, filed before anything dispatches.
6. Dispatch each ready wave in full, go quiet, re-plan between waves.
7. Review at the sized depth, integrate by oracle, publish, close out.

Track these with the task tools so the user can see where the feature is.

1. Frame it

Say back the outcome in a line or two, name the surfaces it touches, and state the size with the signal that drove it ("multi-wave: this changes the on-disk format, so the migration has to land before anything reads it"). That framing is what every later step is cut against, so a vague frame produces vague tickets.

Drop out of this flow when it does not fit, and say so plainly:

• Operational asks (run the build, start the dev server, open the dashboard, answer from what is already on screen): just do them.
• A trivial edit to one or two files the user named, with no investigation: edit inline.
• A single bug with a known cause: that is one ticket, not a user-story flow.

2. Recon, bounded

Recon answers exactly one question: what does the contract need to say? Stop the moment you can write the shared interfaces, the file boundaries, and a verify command per piece.

In the orchestrator, bounded recon may Read, Glob, or Grep named anchors and make one narrow location sweep. Route unfamiliar path tracing, deep investigation, or multi-angle research through the live taxonomy: use a read-only codebase-exploration ticket for repository behavior, source-lookup for a bounded external question, or evidence-research when sources need reconciliation. Give each ticket one distinct angle and run independent investigations in parallel. At multi-wave size the angles that earn their keep are the closest existing feature traced end to end, the extension point and who else depends on it, and the convention plus test pattern to match.

Give an exploration ticket a deliverable, not a topic. It should come back with anchors as file:line, the seam to extend, the convention to copy, the existing verify command, and the consumers that would break. Findings return as compressed comments of roughly one to two thousand tokens.

Then build the contract from those findings. Do not go read every file they named. That habit is what makes the expensive loop expensive, and it buys nothing the finding did not already carry. When a finding is too thin to write a contract from, the fix is a sharper deliverable on the next exploration ticket, not the orchestrator crawling the tree itself.

3. One question round, or none

Collect every genuinely contract-changing ambiguity and ask them together in a single AskUserQuestion (up to four). Ask only when the answer changes user-visible behavior, compatibility, migration, public API, dependencies, or expensive-to-reverse scope. One round respects the user's attention and gets better answers, because they see the whole shape of the decision at once. Asking one question per ambiguity trains them to stop reading.

Worth asking: a user-visible behavior with two defensible answers, a scope boundary that changes how much gets built, a compatibility break, a data migration, anything else expensive to reverse.

Not worth asking: naming, file layout, test placement, error copy, ordering, and every other call you can make and change later. State the assumption in the contract and keep going. Explicit phrases such as "do your thing", "use your judgment", or "whatever you think" delegate the current feature: pick, record the pick, and move on. They do not create a durable standing preference.

This is where the generic flow is deliberately narrowed. It waits for answers before designing; Sidequest defaults autonomous, because a stalled feature costs the user more than a decision they can correct at review.

4. Design: contract, or a panel

The output of this step is always the same artifact: one contract. What changes with size is how much you spend arriving at it.

When the approach is settled, write it. Three proposals for a foregone conclusion is three tickets of cost for an answer you already had.

When the approach is genuinely contested and hard to reverse, run a design panel. Two or three spike-investigation tickets, readonly: true, same problem, deliberately different mandates:

• Smallest change: maximum reuse of what already exists, least new surface.
• Cleanest seams: what you would build if this area took three more features after this one.
• Risk-first: what breaks, what is hard to reverse, what the migration and rollback actually cost.

They run in parallel, on category-appropriate routes, with a bounded deliverable: the seam it introduces, the signatures it pins, file boundaries per piece, what it costs, and what it forecloses. Cap each proposal at roughly two thousand tokens. Three uncapped design docs landing in the orchestrator's context is the failure mode the panel is supposed to avoid.

Then do the orchestrator's planning work: judge the plans and merge them. Pick a spine, graft the parts of the runners-up that are better than the winner's version, and write one contract out of the result. A panel whose output is "we went with proposal B" wasted the other two; the point is that the merged contract beats every individual proposal. Record in the story log why the losers lost, because the next session will otherwise re-propose them.

Whatever the route, a contract that makes fan-out safe pins:

• Shared surface: the types, interfaces, and function signatures pieces hand each other, written out. This is the whole reason parallel executors compose instead of producing five conflicting interpretations of the same seam.
• File boundaries per piece, the blast radius each piece may touch, and any committed build output. Content-hashed output gets one rebuild ticket per wave.
• Dependency order, so ready partitions the backlog into waves by itself.
• The exact scoped verify command per piece, runnable and deterministic. The integrator runs the full merged-tree gate once per wave.
• Shared runtime resources: fixed ports, servers, databases, fixture paths. Worktrees isolate files, not runtime, so two tickets sharing a port serialize even inside one wave.

Present the chosen approach and its main trade-off in a few lines. Ask for approval only when the choice is expensive to reverse: a schema or migration, a public API, a user-visible default, a new dependency. Otherwise state what you picked and proceed.

Cannot pin a multi-item contract at all? File concurrent read-only investigation tickets, one investigation ticket per independent item, then pin a separate fix wave from their compressed findings. A shared runtime serializes writes and live reproduction, never read-only investigation; one combined ticket is only for exactly one item or a provably single defect. Claiming a one-item contract is unpinnable needs either a completed planning ticket that names the interface that resisted, or no written contract surface in the request. "Feels coupled" is a reason to file planning first.

5. Story plus the whole backlog

One ticket and one executor covers small coherent work, exactly one item, or items provably one defect. This never means the orchestrator implements it.

Everything larger gets a story, the contract pinned on it, and every ticket for every planned wave filed under it before the first dispatch: category from the live taxonomy, file scope, anchors, exact scoped verify, and depends-on links. Never hand-pick a model or effort.

Filing the whole thing up front is what makes the plan steerable. The user sees the entire feature on the board and can cut, reorder, or reshape it while that is still cheap. Drip-filing one ticket, dispatching, waiting, then filing the next hides the plan and serializes work that had no reason to be serial.

At multi-wave size the shape that usually works:

• Wave 1 pins the shared surface in code: the types, the schema and its migration, the seam itself. Once this is real, wave 2 physically cannot diverge from it.
• Wave 2 is the wide parallel wave: every independent piece built against that surface.
• Wave 3 is the work that can only exist once the pieces do: end-to-end tests, UI wiring, the performance pass, the docs.

You do not declare those waves anywhere. Dependency links make them, and ready hands you each one.

Each description is a developer-to-developer spec: anchors, behavior and edge cases, bounds, decisions already made, the reproduction if it is a bug, and the verify command. Front-load evidence so the executor starts from the selected plan rather than re-deciding it.

A feature almost always has a docs piece. Any change to what a user sees or does either updates the affected prose page inside the story or gets a linked ticket classified from the live taxonomy. Decide that here, while the backlog is being written, not at ship time.

Flag the tickets that deserve highStakes: true now: data loss, auth, money, the release path, an irreversible migration. That flag is what pulls deeper verification and a required review pass into the ticket instead of relying on you to remember at the end.

6. Run the waves

Fresh dispatch <ref> per ticket, every spawn field passed through unchanged, all of it in one message so the wave actually runs in parallel. Dispatch everything whose dependencies are met. Same-file overlap across isolated worktrees deserves a look, not automatic serialization.

Then stop touching it. No pulses, no comment reads, no worktree peeks between dispatch and submission. Each peek costs a full-context turn at the top model rate and returns nothing you can act on, since a half-finished executor's state is not a decision point. Executors report on their own, and changes --since is the read when you do need one. Steer instead of restarting: answer scope requests, use SendMessage for what a message can fix, and never stop-then-redispatch work that is still moving.

Between waves is where re-planning belongs. Close the wave (every ticket integrated or explicitly deferred), read the story log for what the wave learned, then promote each finding needed by the next executor into that ticket's description, dependency contract, comment, or the story execution contract before dispatching it. The story log is orchestrator planning history, never executor orientation. Adjust the next wave's tickets after that promotion. That is legitimate precisely because those tickets already exist and the user could see them; it is the opposite of inventing the plan one ticket at a time. New discoveries become normal tickets, linked into the wave they belong to.

A wave that straggles on one ticket while you sit idle is a sizing error, not a reason to poke it. Note it, and cut thinner slices next time.

7. Review at the sized depth, then integrate

The floor is always the same: read the submission report, deliver the range, and run the merged-tree full gate once for the wave. On green, finish the publish transaction under the publish lock.

How much review sits on top of that floor scales with the work:

• One ticket, deterministic oracle: the oracle is the review. Adding a review pass to a passing deterministic verify buys nothing.
• Named uncertainty or safety-sensitive seam: add a review-audit only when the done-oracle cannot exercise a stated seam, such as a consumer the wave did not test. The contract names the seam and the review mandate. A safety-sensitive contract can make that review required.

Give reviewers an adversarial mandate: try to break the named seam, identify the failing input or broken consumer, and record evidence. Review verifies the pinned contract and its oracle, never silently expands the active feature. Route unrelated concerns into separately prioritized tickets; they block this ship only when the contract or a proven regression requires it. Findings that do block ship become fix tickets, and their verdicts land as comments starting reviewed-by:.

After two independently rejected candidates in one defect chain, stop local patching. Re-plan, narrow the contract, or replace the authority or architecture before another candidate. Involve the user when the current feature was not delegated.

Through all of it, do not reopen the diff yourself. Judging code you did not write, on the priciest model in the loop, is slower and less reliable than the verify command the ticket already carried and the reviewer whose whole job it was. You judge plans and route fixes.

Close out

• Docs: the prose page updated, or the linked docs ticket on the board. A user-facing change with no docs ticket is not done.
• Decisions: log the contract calls, the rejected proposals and why, and the assumptions you made without asking, on the story, so the next session inherits the reasoning instead of re-deriving it.
• A short report: what shipped, the refs, the decisions that matter, and anything deferred with the reason.

Coming from a generic feature-dev flow

Same beats, different owner for each, and every one of them sized:

Failure modes worth naming

• "I already have the context, I'll just write it." The cheapest-looking move in the moment and the most expensive over the feature. Loaded context is not a reason to inline.
• One size for everything. A blanket review panel on a new flag is theater; an untested seam on a format migration needs named scrutiny. Both are the same mistake.
• A panel that picks a winner and discards the rest. Merge, or do not run the panel.
• Reading the whole subsystem before filing anything. Recon has a stopping condition: the contract is writable.
• A backlog that grows one ticket at a time. Nobody can steer a plan they cannot see.
• Polling. Pulses, worktree peeks, or a shell loop waiting on an executor. Reports arrive on their own.
• Re-reviewing the wave's diffs yourself. That is what the verify command and a contract-required review ticket are for.
• Shipping without the docs decision. Cheap while the backlog is open, annoying at ship time.