Implementation Group Decomposition Skill

Break a large document — architecture proposal, feature spec, migration plan, or requirements set — into self-contained implementation groups ordered for sequential execution through the make-plan pipeline.

When to Use

• User says "make groups", "group requirements", "sequence groups", "decompose into groups"
• User has a large document with many requirements/features that must be implemented incrementally
• User wants to feed groups one at a time through /make-plan

Core Principles

• Groups are implementation units, not categories. Each group must be independently plannable and implementable. A group produces a working, testable increment.
• Requirements travel with their group. Every requirement from the source document must appear in exactly one group, referenced by its original ID. No requirement is dropped or split.
• Dependency order is the sequencing rule. Group A's output is available when Group B starts. Order by what produces foundations first, consumers last.
• Source material is unverified input. Verify claims about the codebase against subagent findings before incorporating them into grouping decisions.

Critical Constraints

NEVER:

• Modify any source code files
• Create files outside temp/make-groups/ directory
• Drop, split, or rewrite requirements — reference them by original ID
• Create groups that cannot be independently planned
• Include implementation steps or technical approach in the group descriptions

ALWAYS:

• Use subagents to verify codebase structure before finalizing groups
• Include every requirement from the source document in exactly one group
• Assign each group a sequential suffix: groupA, groupB, ... groupZ
• State dependencies between groups explicitly
• Write to temp/make-groups/ directory

Workflow

Step 1: Read the Source Document

Read the full document. Inventory every requirement (REQ-*), feature, and deliverable. Build a raw list with original IDs preserved.

Step 2: Verify Against Codebase

Launch parallel Explore subagents to understand:

• What exists today that the requirements relate to
• Module boundaries and dependency directions
• Which components are foundational vs. consumers

Step 3: Form Groups

Cluster requirements into groups. Each group must:

1. Be independently plannable — someone could take this group to /make-plan without needing other groups implemented first (except declared dependencies)
2. Produce a working increment — after implementation, the system is in a valid state
3. Contain all related requirements — no requirement is orphaned or deferred

Name each group with a short descriptive label and assign suffix groupA through groupZ in implementation order.

Step 4: Order by Dependency

Sort groups so that each group's dependencies are satisfied by earlier groups. Document the dependency chain explicitly.

Step 5: Write the Groups Documents

Produce three outputs in temp/make-groups/:

5a. Index file (consolidated): groups_{topic}_{YYYY-MM-DD_HHMMSS}.md

markdown
1# Implementation Groups: {Topic}
2
3**Date:** {YYYY-MM-DD}
4**Source:** {Document path or description}
5**Groups:** {count}
6
7## Per-Group Files
8
9- `groupA_{topic}_{ts}.md`
10- `groupB_{topic}_{ts}.md`
11- ...
12
13## Manifest
14
15`manifest_{topic}_{ts}.json`
16
17## Dependency Chain
18
19{group_id} → {group_id} → ... (linear or DAG as needed)
20
21---
22
23## {Group Label} (groupA)
24
25### Purpose
26{What this group delivers and why it comes at this position in the sequence}
27
28### Dependencies
29{None, or list of group IDs that must be complete first}
30
31### Requirements
32- **REQ-XXX-001:** {Original requirement text}
33- **REQ-XXX-002:** {Original requirement text}
34- ...
35
36### Planning Context
37{What make-plan needs to know: affected modules, key interfaces, constraints. Factual only — no prescribed approach.}
38
39---
40
41## {Group Label} (groupB)
42
43{Same structure}
44
45---
46
47{Repeat for each group}
48
49## Traceability
50
51| Requirement | Group |
52|-------------|-------|
53| REQ-XXX-001 | groupA |
54| REQ-XXX-002 | groupA |
55| REQ-YYY-001 | groupB |
56| ... | ... |

5b. Per-group files: groupA_{topic}_{ts}.md, groupB_{topic}_{ts}.md, etc.

Each per-group file contains the group's section extracted from the index — one self-contained file per group for pipeline consumption:

markdown
1# {Group Label} (groupA)
2
3## Purpose
4{What this group delivers}
5
6## Dependencies
7{None, or list of group IDs}
8
9## Requirements
10- **REQ-XXX-001:** {text}
11- **REQ-XXX-002:** {text}
12
13## Planning Context
14{What make-plan needs to know}

5c. Manifest file: manifest_{topic}_{ts}.json

Machine-readable manifest for pipeline orchestration:

json
1{
2    "topic": "{topic}",
3    "date": "{YYYY-MM-DD}",
4    "source": "{document path}",
5    "group_count": 7,
6    "dependency_chain": ["groupA", "groupB", "groupC"],
7    "groups": [
8        {
9            "id": "groupA",
10            "label": "{Group Label}",
11            "file": "groupA_{topic}_{ts}.md",
12            "dependencies": [],
13            "requirements": ["REQ-XXX-001", "REQ-XXX-002"]
14        }
15    ],
16    "index_file": "groups_{topic}_{ts}.md"
17}

Step 6: Verify Completeness

Before finalizing, check:

• Every requirement from the source document appears in the traceability table
• No requirement appears in more than one group
• No group depends on a group that comes after it in the sequence
• Each group is self-contained enough to be a /make-plan input
• Per-group file count matches group count in manifest
• All per-group files are written to disk

Report to terminal: index file path, manifest file path, per-group file count, and the dependency chain.

Output Location

temp/make-groups/
├── groups_{topic}_{ts}.md           # Consolidated index (all groups)
├── manifest_{topic}_{ts}.json       # Machine-readable manifest
├── groupA_{topic}_{ts}.md           # Individual per-group file
├── groupB_{topic}_{ts}.md
└── ...

Feature Branch Recommendation

When implementing multiple groups from this skill's output, always work on a feature branch, not directly on main. Group implementations take multiple plan-implement-merge cycles and should not land on the base branch until the full set is complete.

After make-groups completes, create a feature branch before starting the pipeline:

bash
1git checkout -b feature/{topic}

Then run each group through /make-plan → /dry-walkthrough → /implement-worktree using the feature branch as the base branch for all merge operations.

Related Skills

• /make-req — Produces requirements from raw input (this skill groups existing requirements)
• /make-plan — Consumes individual groups as planning input
• /audit-impl — Audits the full implementation against all group plans before final merge
• /elaborate-phase — Elaborates phases within a plan (this skill creates the groups that become plans)
• /dry-walkthrough — Validates plans produced from groups