Decompose — Project Scope Analysis

Analyze project scope and determine whether to treat it as a single feature or split into multiple sub-features before entering the spec chain.

Core Principles

Lightweight: 3-5 rounds of questions, not a deep investigation
Boundary-focused: Only care about scope boundaries and dependencies
No demand validation: That is /idea's responsibility
No deep research: That is /prd's responsibility
Single is valid: Not every project needs splitting — a single-feature verdict is a good outcome

Workflow

Step 1: Read Context

Scan the project to understand what exists:

Use Glob to scan the project directory tree (top 3 levels)
Read the project README.md if it exists
Scan docs/ for existing specification documents and project manifests
Check if ideas/{feature-name}/draft.md exists — if found, read it for context on scope

Summarize what you learned in 2-3 sentences. Do not present this to the user — it is internal context for the interview.

Step 2: Scope Interview

Use AskUserQuestion to understand project boundaries. Ask 3-5 rounds of questions, adapting based on answers.

Round 1 — The Shape:

What are the main functional areas or modules of this project? (e.g., "auth, payments, notifications" or "it's a single API endpoint")
How big is this project in your mind — a single focused feature, or multiple related features?

Round 2 — Boundaries:

Which parts could be developed and tested independently?
Which parts depend on each other? (e.g., "payments needs auth to exist first")
Are there shared foundations that multiple parts need? (data models, infrastructure, auth)

Round 3+ — Clarification (if needed):

Follow up on anything unclear from rounds 1-2
Stop when you can confidently propose a split structure

Do NOT force answers. If the user says "I'm not sure", use your judgment based on what you know.

Step 3: Split Decision & Rationale

Based on the interview, determine: single or multi-split.

Split heuristics:

Signal	Verdict
Multiple distinct systems (backend + frontend + pipeline)	Multi-split
Repeated "and also..." in scope description	Multi-split
No single clear purpose — hard to name in one phrase	Multi-split
Would produce 10+ PRD requirement groups	Multi-split
Single cohesive system with tightly coupled components	Single
Fully specifiable in a few paragraphs	Single
No architectural decisions needed at the boundary level	Single
Too unclear even after interview — need PRD to discover structure	Single

Good split characteristics:

Cohesive purpose — a clear goal or outcome
Bounded complexity — 1-3 major components
Clear interfaces — well-defined inputs and outputs
Each split is substantial enough for its own Tech Design + Feature Specs

Rationale requirement: After reaching a verdict, you MUST produce a formal Split Rationale block (see Step 4a / 4b). Do not present the verdict without justification. The rationale must name which heuristics fired with project-specific evidence, and explicitly state why the alternative verdict was rejected.

Step 4a: Single Feature Verdict

If the project is a single feature:

Produce the Split Rationale block (required before informing the user):

Split Rationale:
  Verdict: Single feature

  Signals that fired (Single):
    ✓ [Signal text from heuristics table] — [one sentence of project-specific evidence]
    ✓ [Signal text] — [evidence]

  Signals evaluated but not triggered (Multi-split):
    ✗ [Signal text] — [why it does not apply to this project]
    ✗ [Signal text] — [why it does not apply]

  Why not Multi-split: [1-2 sentences explaining why splitting would be premature,
  over-engineered, or harmful for this specific project — reference scope, coupling,
  team size, or other concrete factors from the interview.]

Inform the user: "This project is well-scoped as a single feature. Proceeding directly to the spec chain."
Return the verdict. Do NOT generate a manifest file.

Step 4b: Multi-Split — Generate Manifest

If the project should be split:

Produce the Split Rationale block (required before presenting the breakdown):

Split Rationale:
  Verdict: Multi-split ({N} sub-features)

  Signals that fired (Multi-split):
    ✓ [Signal text from heuristics table] — [one sentence of project-specific evidence]
    ✓ [Signal text] — [evidence]

  Signals evaluated but not triggered (Single):
    ✗ [Signal text] — [why it does not apply to this project]
    ✗ [Signal text] — [why it does not apply]

  Why not Single: [1-2 sentences explaining what makes this project structurally
  too broad or heterogeneous to treat as one feature — e.g., "The auth subsystem
  and payment pipeline share no code paths and require independent deployment cycles."]

  Boundary rationale:
    {sub-feature-1} | {sub-feature-2}: [Why this is a clean cut point — what the
    interface between them is and why each side is independently specifiable]
    [Add one line per boundary if N > 2]

Present the proposed split structure together with the rationale to the user for confirmation
Use AskUserQuestion: "Here's my proposed breakdown and the reasoning behind it. Does this look right, or would you change anything?"
If the user wants changes, adjust rationale accordingly and re-confirm
Once confirmed, write the manifest to docs/project-{name}.md

Manifest format:

The file MUST start with a FEATURE_MANIFEST comment block, followed by human-readable content:

<!-- FEATURE_MANIFEST
{sub-feature-1}
{sub-feature-2}
{sub-feature-3}
END_MANIFEST -->

# Project: {name}

## Sub-Features

### 1. {sub-feature-1}
- **Description**: {what this sub-feature covers}
- **Dependencies**: {none, or list of sub-feature names it depends on}
- **Scope**: {brief scope summary}

### 2. {sub-feature-2}
- **Description**: ...
- **Dependencies**: ...
- **Scope**: ...

## Execution Order

{Ordered list with dependency and parallelism notes}

## Cross-Cutting Concerns

{Shared data models, conventions, infrastructure, or other things that span multiple sub-features}

FEATURE_MANIFEST rules:

Must be at the TOP of the file (before any other content)
One sub-feature per line, kebab-case (e.g., user-auth, payment-processing)
Names become directory names under docs/ — each sub-feature gets docs/{name}/tech-design.md
This block is machine-parseable; the rest of the file is for humans

Step 5: Summary

Display the result:

If single:

Scope analysis complete: {name}
  Verdict: Single feature
  Next: Running spec chain (Tech Design + Feature Specs)

If multi-split:

Scope analysis complete: {name}
  Verdict: {N} sub-features
  Manifest: docs/project-{name}.md

  Sub-features:
    1. {sub-feature-1} — {one-line description}
    2. {sub-feature-2} — {one-line description}
    ...

  Next: Run the full chain for all sub-features:
    /spec-forge {name}

decompose