clarify

Clarify a Specification

Find where a specification is ambiguous or silent, ask the smallest number of questions that resolve the highest-impact gaps, and write every answer back into the spec so the document — not the chat transcript — carries the decision.

This runs after a spec exists and before anyone builds against it. Ambiguity caught here costs one question; ambiguity caught during the build costs a rebuild.

The person answering is a product manager, business owner, or domain expert — expert in the business, not in software construction. Every question must be answerable from what they know about their own operation. A question they'd need an engineer to answer is a question you shouldn't be asking.

Never invent a specific number, threshold, name, or percentage they haven't given you. Turning a vague adjective into a number is the single most valuable thing this skill does — but the number has to come from them. Proposing "under two seconds" to someone with no target in mind produces agreement, not information, and a figure you made up is then indistinguishable in the spec from one the business actually committed to. Ask what they'd expect, or what they measure today; if they genuinely don't know, record the shape and leave the figure as [NEEDS BASELINE].

[NEEDS BASELINE] is a sanctioned marker meaning "not currently measured", written by this skill and by write-spec. It is the legacy spelling of [NEEDS MEASUREMENT], defined canonically in ../../CONVENTIONS.md; treat the two as identical and never rewrite an existing one. Resolve it only with a figure the person supplies. Never fill one in yourself, and never treat one as a lingering vague placeholder to be cleaned up.

Find the spec

Locate the specification in this order:

1. If the person attached a spec to the conversation, work from that and hand back an updated copy when you're done. Everything below about reading and writing files applies to that working copy instead. Check this first — it costs nothing and saves hunting for a file that was handed to you.
2. Otherwise establish which folder holds the spec: use the connected folder if there's exactly one, and ask which if several are connected. If no folder is connected, don't go looking in a temporary or scratch directory — ask them to attach the spec to the conversation instead, and tell them how to connect a folder so it's found automatically next time.
3. Settle the project root: if a .specify/ folder exists at that folder or anywhere above it, the folder containing it is the root; otherwise the connected folder is. Everything below is relative to that root, and feature_directory is read relative to it — someone may have connected a sub-folder of a larger project whose .specify/ sits higher up.
4. .specify/feature.json at the root — read feature_directory, and use <feature_directory>/spec.md. If the file can't be read, or the folder it names no longer exists, ignore it and fall through to the next step. Don't report that as an error — someone renaming a folder in Finder is a perfectly ordinary thing to do, and they have no idea a file was tracking it.
5. If that's missing or stale, list the specs/NNN-* folders under the root and use the highest-numbered one, confirming with the person which spec they mean if there's any doubt. Once resolved, quietly update .specify/feature.json's feature_directory to point at the folder you settled on, preserving any other keys — leaving a stale pointer in place means every later run repeats this search, and it silently breaks write-spec's ability to revise a spec rather than starting a new one.
6. If no spec file exists at all, don't create one — say plainly that there's no spec here yet and offer to write one with them first.