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.

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:

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

echo "=== Phase 1: Research ==="

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

Always invoke (in parallel):

Repo analysis — Read CLAUDE.md, scan project structure:

Read(file_path: "./CLAUDE.md")
Glob(pattern: "src/**/*")
Glob(pattern: "**/*.md", path: "./docs")

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):

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

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)

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

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

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

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

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

# 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

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

scope