# Spec Phase

> A Claude skill from mattjaikaran/meridian.

- **Type:** Skill
- **Install:** `agentstack add skill-mattjaikaran-meridian-spec-phase`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [mattjaikaran](https://agentstack.voostack.com/s/mattjaikaran)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [mattjaikaran](https://github.com/mattjaikaran)
- **Source:** https://github.com/mattjaikaran/meridian/tree/main/skills/spec-phase

## Install

```sh
agentstack add skill-mattjaikaran-meridian-spec-phase
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# /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

```bash
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

```bash
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)

2. 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`

3. Display updated scores:

```
After round :

```

4. **Gate check:**

```bash
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 '),
    phase_name='',
    phase_id=,
    goal='''''',
    requirements=,
    in_scope=,
    out_of_scope=,
    acceptance_criteria=,
    constraints=,
    final_scores=,
    unresolved_dimensions=,
)
mark_spec_complete(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](https://github.com/mattjaikaran)
- **Source:** [mattjaikaran/meridian](https://github.com/mattjaikaran/meridian)
- **License:** Apache-2.0

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** yes
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-mattjaikaran-meridian-spec-phase
- Seller: https://agentstack.voostack.com/s/mattjaikaran
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.