scope

What this skill does

## Pre-loaded Context

Active scopes:
!`find scopes -maxdepth 3 -name scope.md 2>/dev/null`

Current branch:
!`git branch --show-current 2>/dev/null`

# Scope Dispatcher

Routes to the appropriate operation based on argument or context.

> **Protocol:** [dispatch/protocol.md](../dispatch/protocol.md)
> **Reference:** See [reference/review.md](reference/review.md) for review workflow, [reference/update.md](reference/update.md) for update workflow, [reference/operations.md](reference/operations.md) for done/list.

---

## Auto-Detect Rules

Parse `$ARGUMENTS` in order:

| Pattern | Route | Action |
|---|---|---|
| `review [name]` | Review | Multi-agent review, produce review.yaml |
| `update [name]` | Update | Sync tasks.yaml status from git history |
| `done [name]` | Complete | Set status to `done` |
| `list` | List | Show all scopes with status |
| `<name>` matching existing scope (search `scopes/{draft,active,done}/<name>`) | Resume | Show scope, offer operations; promote `draft`→`active` if work has started |
| `<name>` not matching existing | Create | Create new scope under `scopes/draft/<name>/` |
| No argument, branch-associated scope exists | Resume | Show it; promote `draft`→`active` if work has started |
| No argument, no scope | Create | Ask what to scope |

---

## Menu Fallback

When no argument or unrecognized keyword, use **AskUserQuestion**:

```
Header: Scope
Question: What would you like to do?
multiSelect: false
Options:
- Create: Define a new scope with requirements and tasks
- Review: Multi-agent scope review with parallel reviewers
- Update: Sync task status from git history
- List: Show all scopes with status
```

| Selection | Action |
|---|---|
| Create | Run creation workflow below |
| Review | See [reference/review.md](reference/review.md) |
| Update | See [reference/update.md](reference/update.md) |
| List | See [reference/operations.md](reference/operations.md) |

---

# Resume Workflow

When resuming a scope:

1. **Locate scope:** Search across lifecycle dirs — `scopes/{draft,active,done}/<name>/`. A scope name is unique across states.
2. Read `scope.md` frontmatter and `tasks.yaml`
3. **Promote `draft` → `active`** if any of the following are true:
   - Any task has `status: in_progress` or `status: done`
   - Git log shows commits referencing this scope since creation
   - User selects "implement" or "continue" from the operations menu

   Promotion has two steps — both must run together:
   - Update `status: active` in `scope.md` frontmatter
   - `git mv scopes/draft/<name> scopes/active/<name>` (or `mv` if the scope is untracked)
4. Show scope summary and offer operations

---

# Creation Workflow

Creates structured tracking documents for complex development tasks.

**DO use for:** Complex multi-step tasks (3+ phases), non-trivial features, after ExitPlanMode.
**DON'T use for:** Single-file changes, trivial refactorings, tasks completable in < 30 minutes.

> **Reference:**
> - [reference/issue-types.md](reference/issue-types.md) — Initiative/Feature/Task/Exploratory definitions, taxonomy allocation, SDD integration
> - [reference/question-taxonomy.md](reference/question-taxonomy.md) — Question templates per taxonomy area with options
> - [reference/sdd-gates.md](reference/sdd-gates.md) — Pre-implementation gates for Initiatives (Simplicity, Anti-Abstraction, Integration-First)

---

## Steps

### Step 0: Native Plan Context

Before research, check for existing context from Claude's native `/plan`:

1. **Check for context:** If `/plan` was used earlier in the session, or the user references a plan, pull those findings in.
2. **If present:** Extract and seed taxonomy areas:
   - Goal/objective → **Scope**
   - Approach/strategy → **Integration** / **Architecture**
   - Open questions → priority clarification targets in Step 3
3. **If absent:** Proceed to Step 1.

This step bridges native planning with structured validation so the user isn't asked to re-state what `/plan` already established.

### Step 1: Research

Run `gestalt map`, read key files, understand current state. Research comes FIRST — before asking questions.

### Step 2: Issue Type Selection

**FIRST QUESTION (Always)** — Use AskUserQuestion:

```
Header: Work type
Question: What type of work is this?
multiSelect: false
Options:
- Initiative: Strategic coordination (months) - Multiple features toward business goal
- Feature: User-facing capability (weeks) - Deliverable value, multiple tasks
- Task: Implementation item (days) - Single concrete deliverable
- Exploratory: Not sure yet - Gather context first, then classify
```

This determines:
- **Question limit:** Tasks get 3, Features/Initiatives get 5
- **Taxonomy areas:** Tasks get minimal (3), Features/Initiatives get full (7)

**If Exploratory:** Gather context, ask 3 questions, present classification recommendation, restart with correct type.

### Step 3: Validation (Human-in-the-Loop)

Present findings and ask focused questions. Every question must:

- **Provide context:** What was found, what is thought, what is uncertain
- **Make tradeoffs explicit:** "We could do A (faster) or B (cleaner). A fits because X, but B if Y."
- **Never ask without context:** Always "Based on [findings], I recommend [X] over [Y] because [Z]. Does this match your intent?"

**Ambiguity scan:** For each taxonomy area (based on issue type), evaluate status and record in `validation.yaml` under `ambiguity_scan`:

- **clear** — Fully specified, no questions needed
- **partial** — Some information present, gaps remain
- **missing** — Not addressed at all

Per-area evaluation criteria:

| Area | Clear | Partial | Missing |
|------|-------|---------|---------|
| Scope | Goals, boundaries, success criteria defined | Some elements unclear | No scope information |
| Behavior | User flows, system responses specified | Some paths undefined | No behavior described |
| Data Model | Entities, relationships, formats clear | Schema gaps exist | No data model |
| Constraints | Performance, security, compatibility stated | Some constraints unclear | No constraints |
| Edge Cases | Error handling, limits documented | Some cases unaddressed | No edge cases |
| Integration | Dependencies, APIs, interfaces identified | Some touchpoints unclear | No integration info |
| Terminology | Domain terms defined consistently | Some ambiguous terms | No definitions |

Routing:
- **All clear:** Skip the validation loop, proceed silently to Step 3.5.
- **Gaps found:** Areas with `partial` or `missing` status become priority candidates, ordered by (Impact × Uncertainty).

**Constitution check (Initiatives only):** Read `.claude/constitution.md`; flag conflicts and ask user to resolve or document exception. Skip for Features/Tasks.

**Validation loop:** Ask clarifying questions in taxonomy-based batches (see [reference/question-taxonomy.md](reference/question-taxonomy.md) for templates per area):
1. Identify uncovered areas
2. Prioritize by (Impact x Uncertainty)
3. Group questions by taxonomy area
4. Use AskUserQuestion with options
5. Re-evaluate remaining questions for relevance
6. Repeat until limit reached or primary areas covered

**Batch format:**
```
Header: [Area, max 12 chars]
Question: [Clear question ending with ?]
multiSelect: false
Options:
- Option A: [choice] - [implication]
- Option B: [choice] - [implication]
- None: [default/skip]
```

**Taxonomy areas:**

| Type | Areas to Cover |
|------|----------------|
| Initiative | Scope, Behavior, Data Model, Constraints, Edge Cases, Integration, Terminology |
| Feature | Scope, Behavior, Data Model, Constraints, Edge Cases, Integration, Terminology |
| Task | Scope, Behavior, Integration |

### Step 3.5: SDD Section Opt-ins (Features/Initiatives)

```
Header: Sections
Question: Which detailed sections do you want?
multiSelect: true
Options:
- Tech Decisions: Document technology choices and rationale
- API Contract: Define API endpoints and schemas
- Data Model: Document entities and relationships