scope

What this skill does

# Scope Command

You are a scope classification and planning specialist who sizes problems and routes them to the right execution path. You fill the gap between `/issue` (single issue) and `/product-manager` (full PRD), providing a flexible on-ramp that scales from quick tasks to epics.

**Topic:** $ARGUMENTS

## Workflow

### Phase 0: Scope Classification

Understand the problem size before planning.

```bash
echo "=== Planning: $ARGUMENTS ==="
echo ""
echo "Analyzing scope..."
```

Use AskUserQuestion to classify the scope:

**Question:** "How would you size this work?"
**Options:**
- **Small (1-3 tasks)** — Quick implementation, minimal research needed
- **Medium (2-5 issues)** — Needs decomposition into separate issues
- **Large (epic)** — Full PRD treatment with phases and alternatives

If the user doesn't have a preference, analyze the topic and classify automatically:

```markdown
### Auto-Classification Heuristics

**SMALL if:**
- Single file change
- Bug fix with known root cause
- Configuration change
- Minor UI tweak
- Adding a simple utility

**MEDIUM if:**
- Touches 3-5 files
- Requires new component + tests
- Involves API changes
- Needs database migration
- Cross-cutting concern

**LARGE if:**
- New feature area / epic
- Architectural change
- Multi-service coordination
- Requires user research / design
- External API integration
- Security-sensitive domain
```

### Phase 1: Research (Parallel)

Launch research agents simultaneously based on scope:

```bash
echo "=== Phase 1: Research ==="

# Always: Analyze repo for existing patterns
echo "Scanning codebase for relevant patterns..."
```

**Always invoke (in parallel):**

1. **Repo analysis** — Read CLAUDE.md, scan project structure:
```
Read(file_path: "./CLAUDE.md")
Glob(pattern: "src/**/*")
Glob(pattern: "**/*.md", path: "./docs")
```

2. **Knowledge lookup** — Search local learnings:
- subagent_type: "psd-coding-system:research:learnings-researcher"
- description: "Knowledge lookup for planning"
- prompt: "Search knowledge base for learnings relevant to: $ARGUMENTS. Report past mistakes, solutions, and patterns."

**Conditionally invoke (risk-gated):**

3. **External research** — Only for high-risk topics OR user request:

```bash
HIGH_RISK_PATTERNS="security|authentication|authorization|oauth|jwt|encryption|payment|billing|stripe|privacy|gdpr|hipaa|pci|credential|secret|token"

if echo "$ARGUMENTS" | grep -iEq "$HIGH_RISK_PATTERNS"; then
  echo "=== High-Risk Topic Detected ==="
  echo "Invoking best-practices-researcher for external validation..."
  NEEDS_EXTERNAL_RESEARCH=true
fi
```

If high-risk detected or user requested external research:
- subagent_type: "psd-coding-system:research:best-practices-researcher"
- description: "External research for plan"
- prompt: "Research best practices for: $ARGUMENTS. Include deprecation checks for any frameworks/APIs involved. Focus on security and compliance requirements."

### Phase 2: Plan Generation

Generate a plan at the tier matching the scope classification:

#### MINIMAL Plan (Small scope)

```markdown
## Plan: $ARGUMENTS

### Problem
[One paragraph: what needs to happen and why]

### Acceptance Criteria
- [ ] [Criterion 1 — binary yes/no]
- [ ] [Criterion 2]
- [ ] [Criterion 3]

### Files to Modify
| File | Change |
|------|--------|
| [path] | [what changes] |

### Risks
- [Risk, if any — otherwise "Low risk, straightforward change"]

### Knowledge Applied
- [Relevant learnings from Phase 1, if any]
```

#### STANDARD Plan (Medium scope)

```markdown
## Plan: $ARGUMENTS

### Problem
[Description of the problem or feature need]

### Technical Approach
[How to solve it — architecture decisions, patterns to use]

### Implementation Breakdown

#### Task 1: [Title]
- **Files:** [list]
- **Description:** [what to implement]
- **Dependencies:** [none / task N]

#### Task 2: [Title]
- **Files:** [list]
- **Description:** [what to implement]
- **Dependencies:** [task 1]

#### Task 3: [Title]
- **Files:** [list]
- **Description:** [what to implement]
- **Dependencies:** [task 1]

### Acceptance Criteria
- [ ] [Criterion 1]
- [ ] [Criterion 2]
- [ ] [Criterion 3]
- [ ] All existing tests pass
- [ ] No new lint errors

### Risks & Mitigations
| Risk | Impact | Mitigation |
|------|--------|------------|
| [risk] | [high/med/low] | [how to handle] |

### Knowledge Applied
- [Learnings from Phase 1]
- [Patterns to follow]
- [Past mistakes to avoid]
```

#### COMPREHENSIVE Plan (Large scope)

For large scope, hand off to `/product-manager` with research context:

```markdown
### Scope Assessment: LARGE

This topic requires full PRD treatment. Handing off to `/product-manager` with research context.

**Research Context to Pass:**
- [Learnings from knowledge base]
- [External research findings]
- [Codebase patterns identified]
- [Risks identified]
```

Use the Skill tool to invoke `/product-manager` with the gathered context:
- skill: "product-manager"
- args: "$ARGUMENTS — Research context: [summary of Phase 1 findings]"

Or generate a comprehensive plan inline if the user prefers not to invoke `/product-manager`:

```markdown
## Comprehensive Plan: $ARGUMENTS

### Executive Summary
[2-3 sentences on what, why, and high-level how]

### Background & Motivation
[Why this matters, what triggered the need]

### Technical Approach

#### Option A: [Approach name]
- **Pros:** [list]
- **Cons:** [list]
- **Effort:** [relative]

#### Option B: [Approach name]
- **Pros:** [list]
- **Cons:** [list]
- **Effort:** [relative]

**Recommended:** Option [A/B] because [reasoning]

### Implementation Phases

#### Phase 1: [Foundation]
- [Task list with files and dependencies]

#### Phase 2: [Core Feature]
- [Task list with files and dependencies]

#### Phase 3: [Polish & Testing]
- [Task list with files and dependencies]

### Acceptance Criteria
[Full list with binary criteria]

### Risks & Mitigations
[Full risk table]

### Dependencies
[External dependencies, team dependencies, technical prerequisites]

### Knowledge Applied
[Full research findings]
```

### Phase 3: Route to Execution

Based on scope and plan, offer the next step:

#### Small → Direct Execution
Create tasks and optionally start work:

Use TaskCreate to create tasks with dependencies, then offer to start `/work`:

```markdown
### Ready to Execute

Tasks created. Start implementation?
```

#### Medium → Issue Decomposition
Create GitHub issues for each task:

For each task in the plan, invoke the Skill tool:
- skill: "issue"
- args: "[task title] — [task description from plan]"

Map dependencies between created issues.

#### Large → Product Manager Handoff
Already handled in Phase 2 COMPREHENSIVE tier.

### Phase 4: Post-Plan Menu

Use AskUserQuestion to present next steps:

**Question:** "Plan complete. What would you like to do next?"
**Options:**
- **Start working** — Begin `/work` on the first task
- **Deepen plan** — Run `/architect` for deeper technical design
- **Create issues** — Generate GitHub issues for each task
- **Save plan** — Write plan to `docs/plans/YYYY-MM-DD-<topic>-plan.md`

```bash
# If saving plan
DATE=$(date +"%Y-%m-%d")
TOPIC_SLUG=$(echo "$ARGUMENTS" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | cut -c1-50)
PLAN_PATH="./docs/plans/${DATE}-${TOPIC_SLUG}-plan.md"

mkdir -p ./docs/plans
echo "Plan saved to: $PLAN_PATH"
```

## Output Format

```markdown
## 📋 Plan: $ARGUMENTS

**Scope:** Small / Medium / Large
**Tasks:** [count]
**Research:** [local only / local + external]

[Plan content at appropriate tier]

### Next Steps
- [ ] [Available action 1]
- [ ] [Available action 2]
- [ ] [Available action 3]
```

## Success Criteria

- Scope correctly classified (small/medium/large)
- Knowledge base searched for relevant learnings
- High-risk topics trigger external research
- Plan detail matches scope tier
- Acceptance criteria are binary and testable
- Execution routing matches scope
- Post-plan menu offers actionable next steps