Ladder Refine
Rewrite a spec file in-place to match the canonical Ladder format without altering intent or scope.
When to Use
-
User says "refine spec," "fix spec," "reformat phase," "ladder refine," or "/ladder-refine"
-
/ladder-execute reports spec validation failures
-
Spec exists but is not in canonical format
-
Invoke with a file path argument
When NOT to Use
-
.ladder/OVERVIEW.md doesn't exist → "Run /ladder-init first"
-
No spec exists yet → use /ladder-create
-
Spec is already canonical and ready → use /ladder-execute
-
User wants to add new features to a spec → use /ladder-create for a new phase
Quick Reference
Field Value
Input Spec file path (.ladder/specs/L-<N>-<slug>.md )
Output Rewritten spec file (same path, canonical format)
Commits chore(ladder): refine L-<N> spec to canonical format
Prerequisites .ladder/OVERVIEW.md , existing spec file
Iron Laws
-
Specs are immutable after creation — refinement is the ONE exception, and it only restructures, never changes intent.
-
No content added or removed — restructure only. Refinement preserves meaning.
-
progress.md is the single source of truth for execution state.
-
User approval before persistent actions — present the rewritten spec before overwriting.
Hard Gates
Workflow
Phase A: Analysis
- Load Context
-
Read .ladder/OVERVIEW.md for product context.
-
Read references/spec-format.md for the canonical format and validation rules.
-
Read the provided spec file.
- Analyze Gaps
Check the spec against the canonical format:
-
Which of the 11 required sections are present/missing?
-
Does the Step Sequence use enriched S<N> format?
-
Do steps have Acceptance criteria?
-
Do Entry/Exit Criteria follow the rules?
Present findings to the user as a gap summary.
Phase B: Clarification
- Clarify Ambiguities
Ask the user to resolve ALL ambiguities in a single message. Typical questions:
-
Missing UX or accessibility requirements
-
Unclear scope boundaries
-
Steps that need splitting or merging
-
Missing acceptance criteria for steps
If there are no ambiguities, skip this step.
Phase C: Rewrite
- Rewrite Spec
Rewrite the file in-place to the canonical format:
-
Do NOT alter intent or scope
-
Do NOT add features or new requirements
-
Do NOT remove content — restructure only
-
Do NOT create separate files
-
Assign S<N> IDs to all steps sequentially
-
Add Complexity, Deliverable, Files, Depends on, Details, and Acceptance to every step
-
Ensure all 11 required sections are present
Present the rewritten spec to the user for approval before writing.
Phase D: Finalize
- Write & Commit
Write the approved spec to disk (overwrite in place).
chore(ladder): refine L-<N> spec to canonical format
- Confirm
Print:
"Spec refined to canonical format. Ready for /ladder-execute ."
Common Mistakes
Mistake Why It Fails Fix
Adding features during refinement Scope creep — refinement only restructures If new features needed, use /ladder-create for a new phase
Rewriting from scratch Loses original author's intent Transform existing content into canonical sections
Skipping gap analysis User doesn't know what changed Present gaps BEFORE rewriting (Hard Gate)
Not validating after rewrite Spec might still fail validation Run all 5 validation rules before writing
Expanding scope of steps Steps grow beyond original intent Match original scope — restructure, don't expand
Red Flags — STOP
Thought Reality
"This spec is so bad I should start over" Transform existing content — never rewrite from scratch
"I'll add a few extra requirements while I'm here" NO scope changes is a HARD GATE
"The user probably meant X" If ambiguous, ask during clarification phase
"I'll just write the new spec without showing the gap analysis" Gap analysis presentation is a HARD GATE
"This step is too big but I'll leave it" Split it — refinement includes structural improvements
Integration
Direction Skill Signal
Requires /ladder-init
.ladder/OVERVIEW.md exists
Requires Existing spec File at provided path
Triggered by /ladder-execute
Spec validation failure
Enables /ladder-execute
Canonical spec ready for implementation