Refine Spec

Refine Spec

Loop the spec review pipeline over a spec file until no new findings are accepted. Writes back to the spec file in place.

Task Tracking

At the start of every invocation (including re-runs from Step 5), use TaskCreate to create a task for each step:

1. Resolve the spec file
2. Run /review-spec skill
3. Run /evaluate-findings skill
4. Run /apply-findings skill
5. Re-run /refine-spec skill if changed

Step 1: Resolve the Spec File

Determine which spec file to refine using these rules in order:

1. Explicit path — If an absolute or relative path was passed, use it
2. Explicit slug — If a slug was passed (e.g., photo-sorter-v2), resolve to .turbo/specs/<slug>.md
3. Single file — Glob .turbo/specs/*.md. If exactly one file exists, use it
4. Most recent — If multiple files exist, use the most recently modified
5. Legacy fallback — If .turbo/specs/ does not exist but .turbo/spec.md exists, use it
6. Nothing found — If no spec file exists, tell the user to run /draft-spec first and stop

If multiple files exist and the most-recent choice is non-obvious (e.g., several specs were modified within the same minute), use AskUserQuestion to let the user pick from the candidates.

State the resolved spec path before continuing.

Step 2: Run /review-spec Skill

Run the /review-spec skill on the resolved spec file. Pass the full spec text.

Always run this step even if the spec looks polished.

Step 3: Run /evaluate-findings Skill

Run the /evaluate-findings skill on the review findings from Step 2.

If zero actionable findings survive evaluation, skip to the end and report the spec as stable.

Step 4: Run /apply-findings Skill

Run the /apply-findings skill on the evaluated results. The target file is the spec file resolved in Step 1. Apply accepted findings by editing the spec in place.

Step 5: Re-run /refine-spec Skill if Changed

Check whether the spec file was edited during Step 4. Any edit counts.

If changes were made, classify what Step 4 edited:

• Structural edits (added or removed sections, new or removed requirements, rewired cross-references, changed acceptance criteria) — run /refine-spec again via the Skill tool, passing the resolved spec path. If the round contains both structural and prose-only edits, treat it as structural and re-run automatically.
• Prose-only edits only (reworded sentences in place, fixed stale examples, clarified existing text without changing meaning) — output a summary of what changed, then use AskUserQuestion to ask whether to run one more round or stop here. Do not silently continue or silently stop.

If changes were made but you believe re-running is unnecessary, use AskUserQuestion to ask for skip permission. Do not skip silently.

If this is iteration 3 and changes were still made, the hard cap is reached. This replaces the classification gate above. Output a summary of what is still changing and whether it is structural or prose-only. Then use AskUserQuestion to offer three options: continue for another iteration, stop here and accept the spec as-is, or escalate to /consult-oracle for a different perspective on the remaining issues.

The re-invocation is a full, fresh run of this skill. Every step (1-5) executes with its own task tracking and skill invocations.

Check your task list for remaining tasks and proceed.

Rules

• Every step must run in every iteration. /evaluate-findings is a judgment gate that must run before /apply-findings touches the spec. Each step must invoke its designated skill via the Skill tool.
• Re-invocations from Step 5 are full runs with fresh task tracking and complete skill invocations.
• The spec file is the only file that should change.
• If /review-spec returns no findings on the first pass, report the spec as stable and stop.