Auto Spec

Auto Spec

Overview

Produce the spec a strong engineer would write before touching code: grounded in what actually exists, precise about behavior, testable in its criteria, honest about scope and risk — arrived at autonomously through recon + draft + an adversarial completeness loop. The output is a spec downstream phases can plan and test against without re-interviewing the user.

Phase 0: Intake — capture the request, detect blocking ambiguity

• Capture $request verbatim as the source of scope. The request IS the scope; don't silently narrow or widen it.
• In a pipeline run, require and read the pre-plan intake snapshot; copy its selectedScope[] ids/titles/sources verbatim into a Binding selected scope checklist and record the snapshot path/hash. Do not accept the plan/spec's own copy as its authority. In a standalone run, if the caller supplies selectedScope[], preserve it verbatim; if the user selected a named bundle, itemize it first. The checklist is authoritative over the draft and must not be regenerated from what the spec includes.
• Judge whether it's answerable from the repo + reasonable inference, or whether a genuine product decision blocks it (a fork where building the wrong branch is expensive). Only for the latter, ask a FEW targeted questions (AskUserQuestion) — never a long interview, never scope questions you could answer by reading the repo.
• Open a checkpoint-resume run.

Success criteria: the request is captured; at most a few genuinely-blocking questions asked; recon can proceed.

Phase 1: Recon — ground the spec in reality

Before drafting, learn what exists (fan out with fan-out-work for a large repo):

• the relevant existing code, modules, data models, and interfaces the change touches;
• prior art / patterns in the repo to stay consistent with;
• constraints that are real: the stack, existing contracts, invariants in CLAUDE.md/docs, data shapes, auth/security boundaries;
• the domain facts the request assumes;
• prior-run lessons already in your loaded context — auto-learn routes them into CLAUDE.md, .claude/rules, and auto memory (which Claude Code loads automatically), so constraints and failure patterns already paid for are in front of you: fold them into the spec's constraints/risks, don't rediscover them.

Record what's grounded vs. what's an assumption — the draft will mark assumptions explicitly.

Success criteria: a grounded picture of the current state and constraints the spec must respect.

Phase 2: Draft the spec

Write .ulpi/spec/<name>.md covering (omit a section only when truly N/A, and say so):

• Objective — the problem and the outcome, in one or two sentences.
• Users & context — who this is for and when it's used.
• Behavior / user stories — what the system does, from the user's view; the happy path AND the error and edge paths.
• Acceptance criteria — a checklist, each item TESTABLE (a condition you could assert). These become the plan's per-task criteria and the tests' targets.
• Binding selected scope — every intake id, unchanged, with the behavior/criteria that implement it.
• Scope & non-goals — explicitly in and explicitly OUT. Non-goals may contain only things the intake selection never included. Never put a selected id here.
• Constraints & interfaces — stack, contracts, data shapes, public interfaces affected, backward-compat.
• Assumptions & open questions — everything not grounded, named as such.
• Risks — security, data, irreversibility, performance — with the mitigation direction.

Success criteria: a complete first draft; every acceptance criterion is phrased testably; assumptions are marked, not hidden as facts.

Phase 3: The completeness-critic loop (converge until stable)

Run converge-loop in until-dry mode with an adversarial critic as the finder — this is what makes the spec strong:

• each round, adversarial-verify-style critics attack the draft: missing behavior/edge/error case? an acceptance criterion that isn't testable? an ungrounded requirement? contradictory or ambiguous wording? a non-goal that should be stated? an unstated assumption? any selected-scope id missing, weakened, deferred, or placed in non-goals?
• apply the smallest fix per finding (tighten a criterion, add the missing case, mark the assumption, cut the invented requirement);
• re-critique; exit when a round finds no material gap (dry) OR it stalls. A stalled loop reports the remaining open gaps — it does not claim completeness.

Use AskUserQuestion only if a surfaced gap is a real product decision; otherwise the critic resolves it against the repo.

Success criteria: no material gap/ambiguity/untestable criterion remains, or the open ones are explicitly listed as open questions.

Phase 4: Finalize

Write the stabilized spec to .ulpi/spec/<name>.md, close the checkpoint, and report where it lives + the open questions (if any). This spec is the input to auto-plan.

Success criteria: the spec file is written and self-consistent; open questions (if any) are flagged for the user.

Common Rationalizations

Red Flags

• Requirements, paths, or endpoints in the spec that don't exist in the repo and aren't marked assumptions.
• Acceptance criteria you couldn't write a test for.
• A spec with in-scope items but no non-goals.
• The critic loop ran exactly once.
• Long clarification interviews for things readable in the repo.
• A "complete" verdict with unresolved contradictions still in the text.
• A selected-scope id missing from the spec, weakened into a non-goal, or pre-emptively deferred.

Guardrails

• Never invent requirements/paths/constraints; ground them or mark them assumptions.
• Never emit an untestable acceptance criterion.
• Never omit explicit non-goals.
• Never put a selected-scope id in non-goals or deferred work. If it cannot be completed, keep it selected and surface it as BLOCKED; record a drop only after an explicit user decision naming that id.
• Never resolve a real product decision silently — ask (briefly) or flag it open.
• Never report the spec complete while the critic still finds material gaps.

When To Load References

• fan-out-work (skill) — parallel recon across a large codebase in Phase 1.
• adversarial-verify (skill) — the completeness critics in Phase 3.
• converge-loop (skill) — the until-stable critic loop (termination + anti-thrash).
• checkpoint-resume (skill) — durable spec-run state.

Output Contract

Report:

1. the spec file path (.ulpi/spec/<name>.md), independent intake snapshot path/hash, and objective
2. selected-scope coverage (N of M) against that snapshot with every selected id, then the acceptance-criteria count and explicit non-goals
3. any per-id user-approved drops, assumptions made, and open questions surfaced for the user
4. critic-loop outcome (rounds to stable, or the honest remaining gaps)