Scope

---
name: workflows:scope
description: Break ideas (big or small) into PR-sized features through collaborative dialogue
argument-hint: "[vision, idea, or problem to scope into features]"
---

# Scope Features

**Note: The current year is 2026.** Use this when dating scope documents.

Scoping converts a vision or idea into **PR-sized features** — each one a concrete, non-breaking capability. It precedes `/workflows:plan`, which answers **HOW** to build each feature.

**Process knowledge:** Load the `brainstorming` skill for detailed question techniques, approach exploration patterns, and YAGNI principles.

## Feature Description

<feature_description> #$ARGUMENTS </feature_description>

**If the feature description above is empty, ask the user:** "What would you like to scope? Please describe the vision, feature, or problem you want to break into buildable features."

Do not proceed until you have a feature description from the user.

## Execution Flow

### Phase 0: Archive Previous Round

Before starting new scoping work, archive any completed artifacts from the previous cycle.

```bash
# Move completed scope docs to archive
for f in factory/artifacts/scope/*.md; do
  [ -f "$f" ] && mv "$f" factory/artifacts/scope/archive/
done

# Move completed plan docs to archive
for f in factory/artifacts/plans/*.md; do
  [ -f "$f" ] && mv "$f" factory/artifacts/plans/archive/
done

# Move completed todos to archive
for f in factory/artifacts/todos/*.md; do
  [ -f "$f" ] && mv "$f" factory/artifacts/todos/archive/
done

# Move completed logs to archive
for f in factory/artifacts/logs/*.md; do
  [ -f "$f" ] && mv "$f" factory/artifacts/logs/archive/
done

If no artifacts exist to archive, skip silently and proceed.

Announce: "Archived previous round's artifacts. Starting fresh scope."

Phase 1: Assess Requirements Clarity

Evaluate whether full scoping is needed based on the feature description.

Clear requirements indicators:

• Specific acceptance criteria provided
• Referenced existing patterns to follow
• Described exact expected behavior
• Constrained, well-defined scope

If requirements are already clear: Use AskUserQuestion tool to suggest: "Your requirements seem detailed enough to proceed directly to planning. Should I run /workflows:plan instead, or would you like to explore the idea further?"

Phase 2: Understand the Idea

2.1 Repository Research (Lightweight)

Run a quick repo scan to understand existing patterns:

• Task repo-research-analyst("Understand existing patterns related to: ")

Focus on: similar features, established patterns, CLAUDE.md guidance.

2.2 Read Principles

Check factory/principles/ for axioms that should inform this scoping:

ls factory/principles/*.md 2>/dev/null

If principles exist, read them and factor into scoping decisions.

2.3 Collaborative Dialogue

Use the AskUserQuestion tool to ask questions one at a time.

Guidelines (see brainstorming skill for detailed techniques):

• Prefer multiple choice when natural options exist
• Start broad (purpose, users) then narrow (constraints, edge cases)
• Validate assumptions explicitly
• Ask about success criteria
• Ask product-oriented AND technical-capacity questions to determine how to break the vision into features

Exit condition: Continue until the idea is clear OR user says "proceed"

Phase 3: Break Into Features

Propose concrete PR-sized features based on research and conversation.

For each feature, provide:

• Title and brief description (2-3 sentences)
• Why it's a standalone PR (doesn't break existing functionality)
• Dependencies on other features (what must come first?)
• Estimated complexity (low / medium / high)

Lead with your recommended ordering and explain why. Apply YAGNI — prefer fewer, simpler features.

Use AskUserQuestion tool to ask the user to confirm, adjust, or reorder the features.

Phase 4: Capture the Scope

Write a scope document to factory/artifacts/scope/YYYY-MM-DD-<topic>-scope.md.

Document structure:

---
title: [Scope Title]
date: YYYY-MM-DD
input: [original vision/idea, one line]
---

## Vision
[What we're building and why]

## Features
### Feature 1: [Title]
- Description: [2-3 sentences]
- Dependencies: [none | Feature X]
- Complexity: [low | medium | high]
- Acceptance criteria:
  - [ ] Criterion 1
  - [ ] Criterion 2

### Feature 2: [Title]
...

## Key Decisions
- [Decision 1 — and why]
- [Decision 2 — and why]

## Open Questions
- [Anything unresolved]

Ensure factory/artifacts/scope/ directory exists before writing.

IMPORTANT: Before proceeding to Phase 5, check if there are any Open Questions listed in the scope document. If there are open questions, YOU MUST ask the user about each one using AskUserQuestion before offering to proceed to planning. Move resolved questions to a "Resolved Questions" section.

Phase 5: Handoff

Use AskUserQuestion tool to present next steps:

Question: "Scope captured with [N] features. What would you like to do next?"

Options:

1. Review and refine - Improve the document through structured self-review
2. Proceed to planning - Run /workflows:plan on the first feature
3. Ask more questions - I have more questions to clarify before moving on
4. Done for now - Return later

If user selects "Ask more questions": Return to Phase 2.3 (Collaborative Dialogue) and continue asking questions one at a time. Continue until the user is satisfied, then return to Phase 5.

If user selects "Review and refine":

Load the document-review skill and apply it to the scope document.

When document-review returns "Review complete", present next steps:

1. Move to planning - Continue to /workflows:plan with the first feature
2. Done for now - Scoping complete. To start planning later: /workflows:plan [document-path]

Output Summary

When complete, display:

S