danmcinerney To Issues
Turn the hardened spec into dispatch-ready issues under the tracking issue. The spec already settles the whole plan — this stage does not quiz the human; a hard stop or an oddity escalation is the only thing that opens a question here.
1. Read before you cut
Load the spec, then hold the codebase-design vocabulary
(skills/codebase-design/SKILL.md) exactly: module, interface, implementation, seam, adapter, depth, leverage,
locality for design; run, tracking issue, issue, slice, frozen check,
check-runner, strategist, builder, orchestrator, factory branch, worktree,
job report, verdict, ruling, digest, hard stop for the factory. Never
substitute component/service/boundary/API for module/interface, or
task/ticket for issue — that drift is a defect, not a style choice.
Look for prefactoring while you read: make the change easy, then make the easy change.
2. Structural before behavioral
Structural (prefactoring) issues land first, with blocking edges into the behavioral issues they unblock. A structural issue's checks prove existing behavior stays green — it changes shape, not outcome.
Oddity rule while scoping: a local wart gets a local patch note, not its own issue. A variation that recurs gets a structural issue blocking the behavioral one. One adapter is a hypothetical seam; two adapters make it real — write the structural issue. Three failed fixes on the same point means stop and escalate the design question instead of cutting a fourth fix.
3. Cut tracer-bullet vertical slices
Each issue is a tracer-bullet vertical slice: a narrow but complete path through every layer the change touches, demoable or verifiable on its own — never a horizontal slice of one layer.
Avoid specific file paths or code snippets in issue prose — they go stale fast. Exception: a prototype snippet that encodes a decision more precisely than prose can (state machine, schema, type shape); trim to the decision-rich parts.
4. Maximize the disjoint parallel frontier
Compute readiness from each issue's file-touch set, not only its blocking edges. Issues dispatched in the same wave share no files, migrations, lockfiles, generated artifacts, config, schemas, or other mutable runtime state. A shared-file collision is a decomposition failure — split or resequence; never hand-merge it later.
5. Interface contracts, not future-code citations
An issue that produces a surface another issue consumes publishes an interface contract block: names, parameters, return types, and behavior. Consumer issues cite that block; they never cite the producer's not-yet-written implementation.
6. Body shape
Every issue carries: acceptance criteria; MAY TOUCH / MUST NOT TOUCH file
sets; its check path; its raw job-report path; blocked-by and parent edges;
a compact change-skeleton (≤30 lines — files, signatures, data flow,
invariants; a contract, not a line mandate). Keep the linked check's RUN
dependencies (the test files, validators, and scripts its commands execute)
out of MAY TOUCH unless the issue explicitly owns them; when it does, name
them in the body as check dependencies. Close every issue body with the
run marker comment: <!-- architect-run: <run> -->.
7. Draft in publish order; the orchestrator publishes
Write one draft file per issue at docs/runs/<run>/issues/<NN>-<slice>.md
(a local run artifact), NN numbered in publish order: structural issues
first, blockers before the issues that cite them. Name blocked-by and
parent edges by slice name — real issue numbers do not exist yet; the
orchestrator maps slice names to issue numbers as it publishes in NN
order, so every blocked-by resolves to a real, already-open issue and
never a forward reference. Do not post to the tracker yourself —
publishing sub-issues, edges, and claims are orchestrator actions
(skills/architect/dispatch.md ## Issue conventions). When the
orchestrator runs this skill directly (/architect-fast), it publishes
the drafts itself in the same order.
Done when every slice in the plan has a draft file — structural-first,
frontier-maxed — whose order publishes with no forward references. End
your reply with one line: ISSUE DRAFTS: <count> at docs/runs/<run>/issues/.