Scope

/scope — Scope Definition Engine v1.0

Unified brief + specify. Lock down "what you will do and what you will NOT do" before implementation. Quick (default) = IN/OUT lock + BRIEF.md. Full = L0→L4 layer chain + spec.md.

Dominant Variable

Is the Scope OUT section explicitly written? — IN alone causes scope creep during implementation. OUT must be explicit to lock it. In Full mode, additionally L2 decision clarity is the dominant variable.

Trigger

• /scope (Quick default)
• /scope full (Full mode)
• /brief (Quick backward compat)
• /specify (Full backward compat)
• "scope this", "스펙 잡아줘", "범위 잡아줘", "기획 정리해줘"
• "spec 만들어", "스펙 만들어", "plan this"

Discard If

• Bug fix, 1-file edit → implement directly
• BRIEF.md/spec.md already exists → use Edit
• Exploration only → delegate to brainstorming

Key Assumptions

1. Project CLAUDE.md exists (existing projects) — if broken: can't auto-scan constraints, write from user input only.
2. User provides idea/requirement in ≥1 sentence — if broken: ask "Tell me in one sentence what to build" once.

Mode Selection

Unsure? Start Quick → if user wants more detail: "Shall we switch to full mode?"

Quick Mode — IN/OUT Brief

Step 1: Detect project

• Existing project: CLAUDE.md, package.json etc. exist → 2-level Glob + keyword Grep (10-file cap)
• New project: skip

Step 2: Ambiguity score gating

Score clarity across 4 dimensions (0-10 each), by judgment.

Gating (deterministic): hand the 4 scores to the gate script and read its stdout — don't average them by eye. Resolve the script from the skill's own directory rather than a path relative to the invocation cwd — python scope/scripts/... only works when the shell happens to be sitting one level above scope/, and breaks in every other cwd:

GATE_SCRIPT=$(find ~/.claude -name "ambiguity_gate.py" -path "*/scope/scripts/*" -type f 2>/dev/null | head -1)
python "$GATE_SCRIPT" quick --scores '{"function":8,"boundary":7,"verification":6,"assumptions":9}'
# -> {"ok": true, "avg": 7.5, "weakest": "verification"}

ok: false → target the dimension the script names as weakest with clarifying questions (max 3). Exceeds question limit → conservative minimum scope + [assumed] tag.

Step 3: Generate Brief

## Brief: [feature name — verb phrase]

**Goal**: [1-2 sentences. Start with verb.]

**Scope IN**
- [concrete items]

**Scope OUT** ← Required, min 2 items
- [natural extension but excluded]

**Constraints**
- [file/action/integration constraints — min 1 if existing project]

**Exit Criteria**
- [ ] [who/what] [action] → [measurable result]

**Risk Flags**
- [min 1]

**Contraindication**
- [condition where this approach doesn't fit — min 1]
- Example: "If data > 100K rows, this design has performance issues", "If team > 2 people, API contract first"

Step 4: Min-item validation → Approval → Save BRIEF.md

The gate script takes --file, not stdin, so it needs something on disk to read — but Invariant 5 says the deliverable (BRIEF.md) isn't saved until after approval, and approval isn't requested until the script says ok: true. Break that cycle by writing the drafted brief to a scratch file (e.g. .scope-draft.md) first: the scratch write is not the Invariant-5-gated save, it exists purely so the deterministic script has a path to read. Draft freely, re-run the gate as many times as needed, all before any approval exists.

Validate the scratch draft against the minimum-item requirements — don't count bullets by eye. A bolded aside inside a section (e.g. **Note**: ...) can look like a new section header on a human skim and silently truncate a manual count; a regression test locks this exact failure mode closed in the script.

GATE_SCRIPT=$(find ~/.claude -name "ambiguity_gate.py" -path "*/scope/scripts/*" -type f 2>/dev/null | head -1)
python "$GATE_SCRIPT" min-items --file .scope-draft.md
# -> {"scope_out": 2, "risk_flags": 1, "contraindication": 1, "constraints": 1, "ok": true}

Pass --new-project for new projects (Invariant 6 waives the Constraints requirement). ok: false → the per-field counts in the JSON show which section is short; revise .scope-draft.md, add items there, and re-run before moving to approval.

Request approval only once the script reports ok: true. On approval: write the same content to BRIEF.md (Invariant 5 — this is the actual gated save) and delete the scratch file. On rejection: keep revising the scratch file and re-gating; it is never shown to the user as the deliverable, only BRIEF.md is.

Full Mode — L0→L4 Spec Chain

Layer Flow

Core Rules

1. Layer order is immutable — no skipping, no backward traversal
2. Append, don't overwrite — Read existing spec.md first
3. doubt-reviewer independent validation required (if skipped: mark Reviewer: SKIPPED)
4. Tasks must link to Requirements (Fulfills: R{n}.{m})

L2 Self-Validation

Each Decision gets clarity score (0-5):

• 5: Implementer can state in 1 sentence what to build
• 3: Needs 1-2 clarifying questions
• 1: Completely ambiguous

Gating (deterministic): hand the per-Decision scores to the gate script — don't average them by eye. Resolve the script from the skill's own directory, not a cwd-relative path (see Quick Mode Step 2 for why):

GATE_SCRIPT=$(find ~/.claude -name "ambiguity_gate.py" -path "*/scope/scripts/*" -type f 2>/dev/null | head -1)
python "$GATE_SCRIPT" full --scores "5,3,4,5"
# -> {"ok": true, "avg": 4.25}

ok: false → warn "Decisions are ambiguous" + suggest rewrite.

Deliverable

specs/{kebab-name}/spec.md — required sections: Meta / Goal / Non-goals / Confirmed Goal / Research / Decisions / Constraints / Known Gaps / Requirements / Tasks / Plan Summary

Mid-Task Scope Drift — 10x-Discovery Rule

Quick and Full modes both lock IN/OUT only at write time — neither covers what to do when scope explodes mid-execution.

Even for scope locked in BRIEF.md/spec.md, if evidence found during implementation (hidden coupling, a required migration, a stopgap carrying far more load than expected) shows the work is a multiple of what was originally understood, stop immediately and surface it:

• What was discovered
• The honest new scale
• 2-3 costed options (full fix / narrow workaround / defer)
• A recommendation

Two things are forbidden: (a) silently absorbing the explosion (the user ends up waiting 5x longer than promised) (b) quietly shrinking the deliverable to fit the original budget (the user only discovers later they got less than expected). Both are worse than a plain "here's what I found."

Scope Boundary

Safety Layers