--- 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 `` (see `@../shared/scripts.md`) and run `python3 "/sf-scan.py" --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: ``` # 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 `