| name | factory-spec |
| description | Turn a ready-to-spec queue item into an approved plan through explicit human gates. Use when an item needs scope decided before code exists, when planning a feature, or before starting a migration. Runs interactively - not for unattended routines. |
Factory spec
This skill exists because the cheapest place to fix a decision is before any code encodes
it. Once a model has written a thousand lines, changing direction is expensive and every
instinct is to patch instead.
This skill is interactive. It stops and waits for a human. Do not run it inside an
unattended routine; a routine that approves its own spec has no gates at all.
Read docs/factory/CONTRACT.md and docs/factory/CHARTER.md before gate 1.
Gates
Four, in order. Stop at each one. Never merge two gates into a single pass. Never proceed
on an inferred approval: "looks good" on gate 1 is not approval of gate 2.
Write each gate's output into docs/factory/specs/FQ-<n>/ as its own file, and track
approvals in docs/factory/specs/FQ-<n>/00-status.md.
Gate 1 - Product (01-product.md)
No technical content whatsoever. If you find yourself naming a file or a function, you are
in the wrong gate.
- The user problem, stated as a person's problem
- What success looks like, measurably
- A short announcement written as if the change already shipped
- Plain HTML mockups for any screen involved, in
mockups/
- What we are deliberately not doing
That last item is the one people skip and the one that saves the most time. It is also
where the kill decision lives: if the honest answer to "should this exist" is no, this gate
is where that is cheap to say.
STOP. Ask for approval.
Gate 2 - Architecture (02-architecture.md)
- Which existing systems and modules this touches
- New endpoints, data structures, and their shapes
- The end-to-end call flow, in order
- External dependencies, and whether each is genuinely required
- Which
LOAD_BEARING paths are involved
- What could break elsewhere
STOP. Ask for approval. For anything touching a load-bearing path, also run the
factory-critic subagent against this document before asking, and include its output.
Gate 3 - Program design (03-design.md)
- Exact file paths, new and modified
- Type signatures and function contracts, no implementations
- The call stack for the main flow
- The test list: what will be tested and what each test proves
- The three decisions you are least confident about
That last section is the highest-value part of this gate. It is where a reviewer can
intervene before the uncertainty is buried under working code.
STOP. Ask for approval.
Gate 4 - Slices (04-slices.md)
Decompose into vertical slices. Each slice must be independently shippable, independently
testable, and small enough to review in one sitting.
- Slice 0 is a tracer bullet: end to end, mostly mocked, proving the shape works.
- Each later slice replaces one mock with real behavior.
- Each slice gets its own queue entry with its own
done_when.
Once approved, create or update one GitHub issue per slice and apply
factory:ready-to-implement. Create or update its factory-handoff:v1 comment with the
approved done_when, expected files, gate level, and confidence. Also write each slice into
the QUEUE.md snapshot. The issue label and comment are the handoff back to the unattended
part of the factory.
STOP. Ask for approval before writing the queue entries.
After the approved handoff, write a unique spec run record under docs/factory/runs/.
Status file
00-status.md tracks state so the spec survives a context reset or a week away:
item: FQ-<n>
gate_1_product: approved 2026-08-16 | pending | rejected
gate_2_architecture: pending
gate_3_design: not-started
gate_4_slices: not-started
slices_completed: 0 / ?
open_questions:
- <anything blocking, with who owns the answer>
For migrations specifically
If this spec covers a migration, gate 2 must answer one question before anything else:
What is the oracle?
An old or unlaunched project usually has the thinnest test coverage in the portfolio, which
means a migration can compile, typecheck, pass every existing test, and still behave
differently. Green does not mean equivalent.
So the first slices are not migration slices:
- Make it build on the current stack
- Make it typecheck
- Pin current behavior with characterization tests and golden-master snapshots
- Only then migrate, wide and fast, against the oracle you just built
This inverts the usual reading of back-pressure. Instead of accepting the verification
budget you have and limiting autonomy to match, you go build a bigger budget first and
claim the autonomy it buys. Each of those four steps is itself a clean factory job.
If gate 2 cannot name the oracle, the migration is not ready and no amount of agent
throughput fixes that.
