Ladder Create

Generate a new phase spec in canonical Ladder format.

When to Use

• User says "create phase," "new phase," "add phase," "ladder create," or "/ladder-create"
• User provides a feature description to turn into a phase spec
• Direct mode: /ladder-create "Add SFTP support"
• Q&A mode: /ladder-create (no argument — will ask questions)

When NOT to Use

• .ladder/OVERVIEW.md doesn't exist → "Run /ladder-init first"
• Spec already exists and needs restructuring → use /ladder-refine
• Spec exists and is ready to implement → use /ladder-execute

Quick Reference

Field	Value
Input	Feature description (direct) or Q&A answers
Output	.ladder/specs/L-<N>-<slug>.md
Commits	chore(ladder): add L-<N> spec — <slug>
Prerequisites	.ladder/OVERVIEW.md must exist

Iron Laws

1. Specs are immutable after creation — only progress.md is a living document.
2. Evidence before completion — never claim a step is done without proof.
3. progress.md is the single source of truth for execution state.
4. User approval before persistent actions — always confirm before writing files or committing.

Hard Gates

Workflow

Phase A: Context Loading

1. Load Context

1. Read .ladder/OVERVIEW.md for product context and Phase Registry.
2. Read references/spec-format.md for the canonical format.

2. Gather Input

Direct mode (argument provided): Parse the description for objective and scope.

Q&A mode (no argument): Ask the user:

1. Objective — what does this phase deliver?
2. Prerequisites — what must exist before this phase?
3. Scope — what's included?
4. Exclusions — what's explicitly out?
5. References — any .ladder/refs/ docs relevant?

Phase B: Generation

3. Determine Phase Number

• Standard: Next integer after the highest phase in the Phase Registry.
• Fractional insertion (e.g., L-01.1): When the user requests a phase between existing phases.
  • Update surrounding phases' Entry/Exit Criteria in-place to reference the new phase.
  • Commit surrounding changes: chore(ladder): update entry/exit criteria for L-<N.1> insertion
  • Update OVERVIEW.md Phase Registry.

4. Generate Spec

Generate all 11 required sections (+ section 12 if references exist) per references/spec-format.md:

• Aim for 6–12 steps per phase
• Assign S<N> IDs to each step
• Set Complexity for each step
• Write Acceptance criteria for every step
• Reference predecessor phase in Entry Criteria
• Include "UAT checklist items pass" in Exit Criteria

Phase C: Review

5. User Review

Present the full spec to the user for review before writing to disk. Incorporate any requested changes. Repeat until approved.

Phase D: Persist

6. Write Spec

Write to .ladder/specs/L-<N>-<slug>.md where <slug> is a kebab-case summary.

7. Update OVERVIEW.md

Add the new phase to the Phase Registry table.

8. Commit

chore(ladder): add L-<N> spec — <slug>

9. Summary

Print the file path and suggest:

"Run /ladder-execute <path> to begin implementation."

Common Mistakes

Mistake	Why It Fails	Fix
Writing spec before user review	User can't influence final output	Present full spec, wait for approval (Hard Gate)
Fewer than 6 steps	Phase is too coarse-grained for progress tracking	Split large steps until each is implementable in one commit
Steps without acceptance criteria	/ladder-execute will reject the spec	Every step needs ≥1 testable criterion
Adding scope the user didn't request	Scope creep undermines trust	Only spec what was asked for
Skipping Q&A in interactive mode	Spec lacks user context	Always ask all 5 questions
Vague acceptance criteria	"Works correctly" is untestable	Use observable outcomes: "returns 200," "renders in <2s"

Red Flags — STOP

Thought	Reality
"I'll write the spec and the user can edit it later"	User review is a HARD GATE — present before writing
"This step is simple, it doesn't need acceptance criteria"	Every step needs criteria — no exceptions
"I'll add some extra features while I'm at it"	Only spec what was requested — no scope creep
"5 steps is enough"	Aim for 6–12. Fewer means steps are too coarse
"I can figure out the scope without asking"	Q&A exists for a reason — gather user context

Integration

Direction	Skill	Signal
Requires	/ladder-init	.ladder/OVERVIEW.md exists
Enables	/ladder-execute	Canonical spec in .ladder/specs/
Related	/ladder-refine	If created spec needs restructuring