Decompose

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

1. Lightweight: a brief interview, not a deep investigation — ask only what you cannot already infer
2. Boundary-focused: Only care about scope boundaries and dependencies
3. No demand validation: That is /idea's responsibility
4. No deep research: That is /prd's responsibility
5. 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:

@../shared/project-context.md

Execute PC.1 (Project Discovery) and PC.3 (Project Profile). Prefer the fast path — resolve <sf_scripts> (see @../shared/scripts.md) and run python3 "<sf_scripts>/sf-scan.py" --root "<project_root>", which returns the project structure, languages, frameworks, DB/auth signals, and the existing-doc inventory in one pass. Fall back to the manual PC.1/PC.3 scan only if python3 is unavailable or the script is not found — switch to the fallback silently.

1. Project structure, README, existing docs (PC.1) — read from the scan's document inventory and source-tree fields
2. Project profile — Web API, CLI, Frontend, etc. (PC.3) — the scan gives the raw signals; you label the profile
3. Check if ideas/{feature-name}/draft.md exists — if found, read it for context on scope

The project profile informs the decomposition: a monorepo with multiple apps has different split criteria than a single-purpose API. 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 only what you cannot already infer from the scan and the user's description, adapting based on answers — there is no fixed number of rounds.

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
Materially more scope than one Tech Design + Feature Specs can cohesively cover	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 (suggest running /spec-forge:prd first to clarify scope)

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, give a one-to-two-sentence justification that names the deciding factor (the coupling, scope, or boundary that settled it) — do not present the verdict without justification. Expand to the full ✓/✗ Split Rationale block (see Step 4a / 4b) only when the verdict is genuinely close, or when the user pushes back and wants to see the reasoning; for a clear-cut call the short justification is enough.

Step 4a: Single Feature Verdict

If the project is a single feature:

1. State the verdict with a one-to-two-sentence justification naming the deciding factor, e.g. "Single feature — the components are tightly coupled around one data model and the whole thing is specifiable in a few paragraphs, so splitting would be premature." Only if the verdict was close, or the user pushes back, expand to the full Split Rationale block:

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.]

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

Step 4b: Multi-Split — Generate Manifest

If the project should be split:

1. State the verdict with a one-to-two-sentence justification naming the deciding factor (what makes the project too broad to treat as one feature — e.g. "the auth subsystem and payment pipeline share no code paths and deploy independently"). Only if the verdict was close, or the user pushes back, expand to the full Split Rationale block:

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]

2. Present the proposed split structure together with the rationale to the user for confirmation
3. Use AskUserQuestion: "Here's my proposed breakdown and the reasoning behind it. Does this look right, or would you change anything?"
4. If the user wants changes, adjust rationale accordingly and re-confirm
5. 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:

• CRITICAL: Must be the VERY FIRST thing in the file — no YAML front-matter, no headings, no blank lines before the <!-- FEATURE_MANIFEST comment. The spec-forge chain parser reads from the top and will fail to recognize the manifest if anything precedes it.
• 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}