Spec Phase

/meridian:spec-phase — Spec Phase Type

Clarifies WHAT a phase delivers through a Socratic interview loop with quantitative ambiguity scoring. Produces SPEC.md in the phase artifact directory with falsifiable requirements locked before implementation decisions begin.

Position in workflow: spec-phase → discuss-phase → plan-phase → execute-phase

Arguments

• (no args) — spec the current pending/planned phase
• --phase — spec a specific phase by ID
• --auto — skip interview if ambiguity already ≤ 0.20; otherwise Claude selects best answers
• --skip-spec — bypass gate warning in /meridian:plan (emergency only)

Keywords

spec, specification, requirements, clarify, ambiguity, scope, boundaries, falsifiable, what, deliverable, acceptance criteria, pre-plan, contract

Ambiguity Model

| Dimension | Weight | Minimum | What it measures | |-----------|--------|---------|-----------------| | Goal Clarity | 35% | 0.75 | Is the outcome specific and measurable? | | Boundary Clarity | 25% | 0.70 | What's in scope vs out of scope? | | Constraint Clarity | 20% | 0.65 | Performance, compatibility, data requirements? | | Acceptance Criteria | 20% | 0.70 | How do we know it's done? |

ambiguity = 1.0 − (0.35×goal + 0.25×boundary + 0.20×constraint + 0.20×acceptance)

Gate: ambiguity ≤ 0.20 AND all dimensions ≥ minimums → write SPEC.md.

Procedure

Step 1: Find Target Phase

PYTHONPATH=$MERIDIAN_HOME uv run --project $MERIDIAN_HOME -- python -c "
import json
from scripts.db import connect, get_db_path
from scripts.spec_phase import get_spec_context
conn = connect(get_db_path('.'))
ctx = get_spec_context(conn, phase_id=)
print(json.dumps(ctx, indent=2, default=str))
conn.close()
"

Pass the --phase value as phase_id, or None if not specified.

If result contains "error", display it and stop — tell the user to run /meridian:plan first.

Store: phase_id, phase_name, description, acceptance_criteria, tech_stack, phase_dir, slug, initial_scores, initial_ambiguity.

Step 2: Check for Existing SPEC.md

PYTHONPATH=$MERIDIAN_HOME uv run --project $MERIDIAN_HOME -- python -c "
from pathlib import Path
from scripts.spec_phase import check_spec_artifact
result = check_spec_artifact(Path(''))
print('exists' if result else 'missing')
"

If exists:

• --auto: proceed with "Update it" automatically. Log: [auto] SPEC.md exists — updating.
• Otherwise: use AskUserQuestion:
• header: "Spec Phase"
• question: "SPEC.md already exists for Phase : . What do you want to do?"
• options: ["Update it", "View it", "Skip (use existing)"]

If "View": display the SPEC.md content, then offer ["Update it", "Skip"]. If "Skip": print Existing SPEC.md unchanged. Run /meridian:discuss --phase to continue. and exit. If "Update": continue.

Step 3: Scout Codebase

Before any questioning, understand current state:

1. Read .planning/PROJECT.md, .planning/REQUIREMENTS.md, .planning/ROADMAP.md (or check if they exist at those paths)
2. Read the phase's description and acceptance_criteria from context
3. Grep the codebase for code/files relevant to this phase goal — look for:

• Existing implementations of similar functionality
• Integration points where new code will connect
• Test coverage gaps relevant to the phase
• Prior phase artifacts (SUMMARY.md, VERIFICATION.md, RESEARCH.md) in phase_dir

Synthesize: what exists today vs what the phase must deliver. Hold this internally — use it to ask precise, grounded questions.

Step 4: Initial Ambiguity Assessment

Use the initial_scores from Step 1 context. Display:

## Initial Ambiguity Assessment — Phase : 

If --auto AND initial_ambiguity ≤ 0.20 AND all minimums met: Skip interview — derive SPEC.md from roadmap + requirements context. Log: [auto] Phase requirements are already sufficiently clear — generating SPEC.md. Jump to Step 7.

Step 5: Socratic Interview Loop

Run up to 6 rounds. Each round: 2–3 focused questions. One AskUserQuestion call per round.

Track current scores (start from initial_scores). Track round_number (starts at 1).

Interview perspectives by round:

• Round 1: Researcher — ground in current reality
• "What exists in the codebase today related to this phase?"
• "What's the delta between today and the target state?"
• "What triggers this work — what's broken or missing?"

• Round 2: Researcher + Simplifier — surface minimum viable scope
• "What's the simplest version that solves the core problem?"
• "If you had to cut 50%, what's the irreducible core?"

• Round 3: Boundary Keeper — lock the perimeter
• "What explicitly will NOT be done in this phase?"
• "What adjacent problems are tempting to solve but shouldn't be?"
• "What does 'done' look like — what's the final deliverable?"

• Round 4: Failure Analyst — find invalidating edge cases
• "What's the worst thing that could go wrong if we get requirements wrong?"
• "What does a broken version of this look like?"
• "What would cause a verifier to reject the output?"

• Rounds 5–6: Seed Closer — lock remaining undecided territory
• Focus questions on the lowest-scoring dimensions
• "We have at — what would make it completely clear?"

For each round:

1. Ask questions via AskUserQuestion:

• header: "Spec Round — "
• question: ""
• (free-text response — use the freeText: true option or plain question if AskUserQuestion doesn't support free text; display questions as text and await user response)

1. After user answers, update dimension scores based on what was clarified:

• Each clear answer to a boundary question → increase boundary_clarity
• Each clear constraint → increase constraint_clarity
• Each testable AC → increase acceptance_criteria
• Clearer goal statement → increase goal_clarity

1. Display updated scores:

After round :

1. Gate check:

PYTHONPATH=$MERIDIAN_HOME uv run --project $MERIDIAN_HOME -- python -c "
import json
from scripts.spec_phase import gate_passed, compute_ambiguity
scores = 
passed, failing = gate_passed(scores)
ambiguity = compute_ambiguity(scores)
print(json.dumps({'passed': passed, 'failing': failing, 'ambiguity': ambiguity}))
"

If gate passes:

• --auto: jump to Step 7.
• Otherwise: AskUserQuestion:
• header: "Spec Gate Passed"
• question: "Ambiguity is — requirements are clear enough to write SPEC.md. Proceed?"
• options: ["Yes — write SPEC.md", "One more round", "Done talking — write it"]

If "Yes" or "Done talking": jump to Step 7. If "One more round": continue.

If max rounds (6) reached and gate NOT passed:

• --auto: proceed to Step 7, flagging unresolved dimensions in Ambiguity Report.

Log: [auto] Max rounds reached. Writing SPEC.md with dimensions below minimum.

• Otherwise: AskUserQuestion:
• header: "Max Rounds Reached"
• question: "After 6 rounds, ambiguity is . Dimensions still below minimum: . What would you like to do?"
• options: ["Write SPEC.md anyway — flag gaps", "Keep talking", "Abandon"]

If "Write": proceed to Step 7. If "Keep talking": continue (no round limit). If "Abandon": print Spec abandoned. No SPEC.md written. and exit.

Step 6: Derive SPEC.md Content

Before writing, synthesize from everything gathered:

Goal statement (1-2 sentences, specific and measurable):

• Based on phase description + interview clarifications

Requirements (list of 3-8 items):

• Each must be: one specific testable statement
• Format: "Current state: X. Target state: Y. Verified by: Z."
• No vague requirements ("should be fast", "improve UX")
• Good: "CLI command exits code 1 + stderr on invalid input"
• Good: "API responds '),

phasename='', phaseid=, goal='''''', requirements=, inscope=, outofscope=, acceptancecriteria=, constraints=, finalscores=, unresolveddimensions=, ) markspeccomplete(conn, , , ) conn.close() print(str(path)) "

### Step 8: Display Summary

Spec Complete:

Artifact: /SPEC.md Requirements locked: Ambiguity: (gate: ≤ 0.20) [PASS / PASS with gaps]

Next: /meridian:discuss --phase discuss-phase will detect SPEC.md and focus on implementation decisions only.

## Gate Behavior

`/meridian:plan` and `/meridian:execute` can check for SPEC.md using `spec_gate()`:

```bash
PYTHONPATH=$MERIDIAN_HOME uv run --project $MERIDIAN_HOME -- python -c "
import json
from pathlib import Path
from scripts.spec_phase import spec_gate
result = spec_gate(Path(''))
print(json.dumps(result, indent=2))
"

• passed: true → proceed normally
• passed: false → print the warning string; user can bypass with --skip-spec

This is a soft gate — it warns but does not block execution.

Critical Rules

• Scout codebase BEFORE the first question — grounded questions only
• Max 2–3 questions per round — never frontload all questions at once
• SPEC.md is NEVER written if user selects "Abandon"
• Do NOT ask about HOW to implement — that is discuss-phase territory
• Every requirement must have current state, target state, and acceptance criterion
• Boundaries section is MANDATORY — cannot be empty
• Acceptance criteria must be pass/fail — no subjective criteria

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: mattjaikaran
• Source: mattjaikaran/meridian
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.