spec-decomposition
npx machina-cli add skill LiorCohen/sdd/spec-decomposition --openclawSpec Decomposition Skill
Purpose
Analyze a specification document to identify natural change boundaries and return a structured decomposition result. This is a pure analysis skill that takes input and returns output without user interaction.
Input
Schema: schemas/input.schema.json
Accepts decomposition mode, spec content, and mode-specific parameters for outline, section, or hierarchical decomposition.
Output
Schema: schemas/output.schema.json
Returns mode-specific results: outline sections, or hierarchical epic/feature groupings with dependency graph.
Resource Files
For detailed guidance, read these on-demand:
- outline-modes.md — Outline, section, hierarchical mode documentation with examples
- decomposition-algorithm.md — 5-phase algorithm, formulas, heuristics
- data-structures.md — DecomposedChange, DecompositionResult schemas, special cases
Quick Reference
Modes: outline (extract headers), section (analyze one section), hierarchical (epics + features), default (full analysis)
Algorithm phases: Structure Extraction -> Boundary Detection -> Dependency Detection -> Independence Scoring -> Refinement
Complexity levels: SMALL (<= 3 ACs), MEDIUM (4-8 ACs), LARGE (> 8 ACs), EPIC (> 10 ACs + 3+ components)
Independence score: 0.0-1.0 scale; >= 0.5 is standalone, < 0.3 should be merged
Source
git clone https://github.com/LiorCohen/sdd/blob/main/plugin/core/skills/spec-decomposition/SKILL.mdView on GitHub Overview
Spec decomposition analyzes a specification document to identify natural change boundaries and deliver a structured breakdown. It supports outline, section, and hierarchical modes, producing either header-based outlines or epic/feature groupings with dependencies. This pure analysis step emits repeatable decompositions with no direct user interaction.
How This Skill Works
Input uses a schema that accepts decomposition mode, spec content, and mode-specific parameters. The skill executes a 5-phase algorithm—Structure Extraction, Boundary Detection, Dependency Detection, Independence Scoring, and Refinement—to produce mode-specific results (outlines, sections, or a hierarchical epic/feature graph) along with an independence score per item.
When to Use It
- When you have a large spec and need to identify independent changes to minimize cross-cutting work.
- When planning releases by turning requirements into modular features and epics.
- When you want a dependency graph to visualize how changes relate across components.
- When extracting outlines or section-level decompositions for stakeholder reviews.
- When evaluating complexity with predefined levels (SMALL, MEDIUM, LARGE, EPIC) and applying the independence score.
Quick Start
- Step 1: Provide the spec content and select the decomposition mode (outline, section, or hierarchical).
- Step 2: Run the 5-phase decomposition algorithm and review the produced results.
- Step 3: Use the independence scores to finalize standalone changes or merge low-scoring items.
Best Practices
- Start with the full spec and choose the most suitable mode (outline, section, or hierarchical) before running decomposition.
- Use the independence score to decide if a chunk can be shipped standalone (>=0.5) or needs merging (<0.3).
- Validate boundary detections against domain knowledge to avoid artificial splits.
- Generate multiple decomposition candidates and compare them for robustness.
- Document assumptions, constraints, and edge cases surfaced during refinement.
Example Use Cases
- Decomposing a product requirements spec into independent UI, API, and data-layer changes.
- Breaking a payment integration spec into separate, testable features with a dependency graph.
- Creating an outline of a data migration spec with boundary-driven change sets.
- Transforming a cross-platform feature spec into platform-specific epic/feature groupings.
- Refining a refactor spec into isolated commits with clear independence scores.
