ericrisco/rsc-harness/specify

Specify — intent becomes a spec

This is the specify phase of the rsc-sdd chain: constitution → `specify` → clarify → plan → tasks → analyze → implement → verify → review → ship. Its single job is to turn a fuzzy intent into a written specification that states WHAT the change is and WHY it matters — and nothing about HOW it gets built.

A spec is a contract about behaviour and outcomes, readable by a non-technical stakeholder and precise enough that a plan can be derived from it. The output is one file: 02-DOCS/wiki/sdd/specs/<slug>.md, indexed in 02-DOCS/wiki/index.md (the Knowledge map; root CLAUDE.md keeps only a short pointer).

Detect the moment — and hold the gate

Fire on the faintest sign the user is thinking about a new feature or change — not just "spec this", but any musing: "I want to add…", "can we build…", "it should also…", "wouldn't it be nice if…", "what if we…", "I've been thinking about…", "let's brainstorm…", "tengo una idea", "se me ha ocurrido", "¿y si…?", "estaría guapo que…", "quiero añadir…", "necesito que haga…". This phase owns that moment, even if a stack skill (nextjs/fastapi/flutter…) also fired and is itching to build it. Catch it here first — being too eager to brainstorm is cheap; skipping it is expensive.

The hard gate — every feature, including the "obvious" ones:

No implementation starts — not a stack skill, not plan-to-code, not "just a quick version" — until the user has approved a design (the spec at step 9 below) and plan has produced the technical plan + task list. If the user says "just build it", do not; name the gate in one friendly line and run the loop. "Too simple to need a design" is the rationalization that wastes the most work — every feature gets the loop. The only thing that skips it is a literal one-line, zero-risk change (typo/copy/config) — say so out loud and do it.

You are not slowing them down; you make the intent reviewable before code exists, which is far cheaper than discovering the misunderstanding in a PR. End every spec by handing to clarify/plan — never to implement.

Your first sentence is not a verdict on the idea

Catching the intent eagerly, above, is right. What comes after catching it is where this phase has been failing: the opening line validates. "Great idea", "makes sense", "that would be really useful" — or, since half this catalog's work happens in Spanish, "buena idea", "qué gran idea", "me encanta", "tiene todo el sentido" — is a verdict you do not have the evidence for, delivered at the cheapest possible moment to be wrong, to someone who still believes you. The ban is on the judgement, in any language, not on any particular wording: the list above is what it looks like, not what it is limited to. A spec built on a validated premise is coherent, plannable, testable and pointed at the wrong thing; nothing downstream can catch that, because every later gate compares artifacts to each other and they all agree.

So the first response to an intent carries exactly two things:

1. A restatement of what you understood, in one sentence, so a misread surfaces now.
2. The strongest objection you can actually articulate from what you already know or can cheaply check — why this might not be worth building, or might be the wrong shape.

Never a judgement of the idea's quality, in either direction. And go look before you object: an objection sourced from the repo, the wiki or a prior spec is worth ten sourced from your priors.

If, having looked, there is no real objection, say so in one line and move on — silence is a valid result. Manufacturing an objection to look rigorous is the same failure wearing the opposite coat, and a doubt that fires on every idea measures you, not the idea. A typo fix does not get a restatement and an objection; it gets fixed.

And the objection never blocks. It is a divergence, not a veto: the user often holds context you do not — a business reason, a conversation elsewhere, a constraint nobody wrote down. If they choose to proceed anyway, do not re-argue. Write the reason into the spec and continue. That is what keeps this from being decorative without giving it power it should not have: it cannot stop the decision, it can only stop the decision from being tacit. If the thing later goes wrong, the record says the doubt was raised and overridden — not that nobody looked.

Offer autopilot once, right here. At this boundary, propose how to run the rest of the chain:

"¿Quieres que lo lleve hasta el final yo solo — spec → plan → código → verify, parando solo si algo es ambiguo — o prefieres que pare a que apruebes en cada fase?"

A yes engages autopilot (../sdd/SKILL.md): you still write the spec and every artifact, but you auto-advance through the phases without re-asking — that up-front yes is the approval that satisfies the hard gate above, for the whole run. A no (or silence) keeps the default gated flow: write the spec, hand to clarify/plan, stop for approval before code. Either way the spec gets written; autopilot only changes whether you pause between phases — and it still stops for genuine ambiguity, hard failures, or destructive/outward actions (ship still confirms). If sdd.autopilot: true in config, autopilot is the default — still surface it once.

The one rule that defines this skill

A spec is a contract: what the system will observably do, and why that matters. Every line either belongs in the contract or belongs to how the contract gets honoured — and the second kind is plan's, not yours. Framework, table schema, library, endpoint shape, file path, algorithm: all of them are how, so the moment one appears the document has stopped being a contract.

One question settles every judgement call in this skill: is this a clause of the contract, or a detail of how it gets met?

If you cannot state a requirement without naming the technology, that is a real open question — record it as a typed point to clarify, do not guess the answer.

Model tier — balanced (opt-in routing)

This phase's default model tier is `balanced` — it drafts the what/why spec through dialogue, not architecture. Routing is off unless models.enabled: true in 02-DOCS/wiki/sdd/config.yaml. When on: resolve this phase's tier (models.overrides wins over models.phases), map it to a model via models.tiers, and apply per ../sdd/references/model-routing.md — announce the switch in one line when it differs from the session model, and dispatch any Task/parallel subagents on that model. Routing off or no profile → honor the session model silently. Never fake a switch a tool can't make; skip routing on a one-line change.

Read the room first (register)

Before asking anything, read technical_level in 02-DOCS/wiki/harness/user-profile.md. It picks the register — technical terms, or plain words with everyday analogies — and nothing else; the method is the same for every reader:

• Infer aggressively from the intent and any existing wiki/constitution. Ask only the questions whose answer would change the contract — one round per frontier, never crossing a dependency.
• Give one line of why per question, in the orient voice; record each requirement with the trade-off you inferred.
• For a non-technical reader, say in one sentence what a spec is, and phrase each option as a concrete example to react to.

If no profile exists, use analogies and keep questions plain. Never assume fluency.

FRAME before you ask anything — from idea-refinement

Before the frontier round, write five lines. They are the FRAME block of ../idea-refinement/SKILL.md, a skill this catalog ships and the README advertises, and that until now no phase invoked:

• Actor — who is struggling, and in what situation?
• Current workaround — what do they do today, including doing nothing?
• Desired progress — what observable change would make this useful?
• Constraints — time, money, trust, regulation, the product that already exists.
• Known vs assumed — separate what you have actually seen from what merely sounds plausible.

Then name the directions worth considering, and "don't build it" is one of them — enumerated, with its consequence, not offered as a courtesy. A direction you can dismiss in one line still had to be written down first; the ones that never get written are the ones that never get weighed.

If the idea arrives phrased as a feature ("an AI dashboard"), FRAME is where it turns back into a problem and an outcome ("operators need to spot failed jobs before customers report them"). The original phrasing stays as one candidate, not as the conclusion.

Ceremony scales with the stakes here as everywhere: FRAME earns its five lines on anything with real scope, and on a small change it collapses to the one line that matters.

Questioning discipline — ask the frontier, never cross a dependency

The failure mode of specs is the wall of twenty questions. The cure is not one question per turn: that spends a turn of the user's time per question even when the questions do not touch each other. The cure is the frontier.

1. Infer first. Read the constitution (02-DOCS/wiki/sdd/constitution.md), the existing wiki, and sibling specs. Fill every section you reasonably can from what already exists.
2. Ask only the gaps that change the contract. A gap earns a question only if a different answer would move scope, a goal, a user, or an acceptance criterion. Cosmetic gaps become typed points to clarify, not questions.
3. Ask the whole frontier in one round. The frontier is every remaining gap whose prerequisites are already settled — the questions you can ask now without guessing at answers you have not heard yet. Number them, give each your recommended answer, then wait. Where the harness offers a native question selector, use it; where it does not, emit the same round as numbered text.
4. Never cross a dependency. A gap whose answer depends on another question open in this round belongs to a later round. Recompute the frontier after every set of answers: settled decisions push it outward and unblock what waited on them. If an answer redefines a question you already emitted in the same round, discard that question out loud and re-ask it next round rather than using an answer given under a premise that just moved.
5. Facts are your job; decisions are the user's. When a frontier question needs a fact from the environment, go find it — and do not block on it. A running search is an unsettled prerequisite, so only the questions downstream of it wait; ask the rest of the frontier now.
6. When inference and asking both fail, type it. Anything unresolved becomes a typed entry in Points to clarify — the handoff contract to clarify, not a defect.

A frontier of one is one question, and needs no apology. A frontier of zero is no question at all: never invent one to look diligent.

What a good spec contains

Write these sections into 02-DOCS/wiki/sdd/specs/<slug>.md using references/spec-template.md. Keep every line about behaviour and intent.