decompose git:20260719.c80ca98A

Immutable. This exact content is served forever at /api/v1/blob/3a775aa14283a0bf.

---
name: decompose
description: >
  Lightweight project decomposition skill. Analyzes project scope through a brief interview
  and determines whether the project should be treated as a single feature or split into
  multiple sub-features. For multi-split projects, generates a project manifest listing
  sub-features, dependencies, and execution order.
instructions: >
  Follow the workflow below exactly. This skill is typically invoked inside a sub-agent
  by the spec-forge chain orchestrator (Step D.1) or via /spec-forge:decompose.
  Keep the interview lightweight — ask only what you cannot already infer from the scan and
  the user's description, not a fixed number of rounds. Do NOT perform demand validation (that is
  /idea's job) or deep research (that is /prd's job). Focus only on scope boundaries and
  dependencies.
---

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