8.5 KiB
8.5 KiB
name, description
| name | description |
|---|---|
| work-decomposition | Procedure for decomposing multi-feature requests into independent workstreams — load when user requests 3+ features or features span independent domains |
When to Load
Load this skill when any of these conditions are true:
- User requests 3 or more distinct features in a single message or session.
- Requested features span independent domains (e.g., frontend-only + backend API + new service).
- Requested features have mixed risk profiles (e.g., UI tweak + encryption + new auth surface).
This skill supplements planning. Load it before the PLAN phase and follow the procedure below.
Decomposition Procedure
Step 1: Identify Features
List each distinct feature the user requested. A feature is a user-visible capability or behavior change.
Rules:
- If a request contains sub-features that can be independently shipped and tested, count them separately.
- "Add temperature display" and "add optimize button" are two features, even if both touch the same page.
- "Encrypted API key storage" and "wire recommendations to use stored keys" are two features — storage is infrastructure, wiring is application logic.
Step 2: Assess Independence
For each pair of features, evaluate:
- Do they share modified files?
- Does one depend on the other's output/data?
- Do they touch the same data models or APIs?
- Could one ship to production without the other?
Group features that share hard dependencies into the same workstream. Features with no shared dependencies are independent workstreams.
Step 3: Classify Risk Profile
For each workstream, classify its highest-risk feature:
| Risk | Triggers | Quality Pipeline |
|---|---|---|
| Low | Frontend-only, config changes, copy/UI tweaks | Tier 3 (fast) |
| Medium | New API endpoints, data model changes, third-party integrations | Tier 2 (standard) |
| High | Auth/security changes, encryption, new service surfaces (MCP, webhooks, SSO), data migration, secret handling | Tier 1 (full) + human checkpoint |
Step 4: Allocate Workstreams → Worktrees
Each independent workstream gets its own:
- Worktree:
.worktrees/<workstream-name> - Branch:
feat/<workstream-name> - PR: Separate pull request for independent review
- Quality pipeline: Independent coder → reviewer → tester cycle
Exception: Two low-risk features that touch the same area (e.g., two UI tweaks in the same component) may share a worktree if they can be implemented and committed sequentially.
Step 5: Order Workstreams
- If workstreams have dependencies, order them so dependent work starts after its prerequisite is merged or at least reviewed.
- If independent, dispatch in parallel (multiple coders simultaneously).
- Prefer shipping lower-risk workstreams first — they unblock value sooner and reduce in-flight complexity.
Step 6: Present Decomposition to User
Before proceeding to implementation, present the decomposition to the user:
Proposed workstreams:
1. [workstream-name] (risk: low/medium/high)
Features: [list]
Worktree: .worktrees/[name]
Branch: feat/[name]
Estimated pipeline: Tier [1/2/3]
2. [workstream-name] (risk: low/medium/high)
...
Execution order: [1] → [2] (or [1] and [2] in parallel)
Human checkpoints: [list any high-risk decisions needing approval]
Wait for user approval before proceeding. If the user adjusts grouping, update accordingly.
Human Checkpoint Triggers
The Lead MUST stop and ask the user for explicit approval before dispatching coder work when ANY of these conditions are met:
Mandatory Checkpoints
- Security-sensitive design: Encryption approach, auth model/flow, secret storage mechanism, token management, permission model changes.
- Architectural ambiguity: Multiple valid approaches with materially different tradeoffs that aren't resolvable from codebase context alone (e.g., MCP SDK vs REST endpoints, embedded vs external service, SQL vs NoSQL for new data).
- Vision-dependent features: Features where the user's intended UX, behavior model, or product direction isn't fully specified (e.g., "improve recommendations" — improve how? what inputs? what output format?).
- New external dependencies: Adding a new service, SDK, or infrastructure component not already in the project.
- Data model changes with migration impact: New models or schema changes that affect existing production data.
Checkpoint Format
When triggering a checkpoint, present:
- The specific design decision that needs input
- 2-3 concrete options with pros/cons/tradeoffs
- Your recommendation and rationale
- What you'll do if the user doesn't respond (safe default)
What Is NOT a Checkpoint
Do not interrupt the user for:
- Implementation details (naming, file organization, code patterns)
- Choices fully determined by existing codebase conventions
- Decisions already covered by prior user answers or megamemory guidance
Coder Dispatch Rules
One Feature Per Coder — No Exceptions
Each coder invocation must implement exactly one feature or a tightly-coupled subset of one feature. This is a hard rule, not a guideline.
Why This Matters
- Focused prompts produce higher-quality implementations
- Each feature goes through its own review/test cycle independently
- Failures in one feature don't block others
- Commits stay atomic and revertable
Parallel Dispatch
If features are independent (different files, no shared state), dispatch multiple coder invocations simultaneously in the same message. This is faster than sequential single-feature dispatches.
Coder Prompt Requirements
Each coder dispatch MUST include:
- Single feature description with acceptance criteria
- Specific file paths and edit points from discovery (not vague references)
- Discovered values verbatim: i18n keys, API signatures, component names, existing patterns
- Worktree path for all file operations
- Active megamemory concept ID for the task
- Quality tier so coder understands the expected rigor
Anti-patterns — Never Do These
- ❌ Sending 2+ unrelated features to one coder invocation
- ❌ Saying "implement the phased plan" without specifying which single feature
- ❌ Including features the critic said to defer or drop
- ❌ Embedding unresolved blockers as "constraints" for the coder to figure out
- ❌ Proceeding past a RESOLVE verdict without actually resolving the blockers
Commit Strategy
Within each workstream/worktree:
- One commit per feature after it passes review/test
- Conventional Commit format:
feat: <what and why> - If a workstream contains 2 closely-related features, commit them separately (not as one giant diff)
Decomposition Decision Examples
Example: 4 features requested (like session ses_3328)
User requests: optimize button, temperature display, AI recommendations with key storage, MCP server
Analysis:
- Optimize button: frontend-only, low risk, independent
- Temperature: backend+frontend, medium risk, independent
- AI recommendations + key storage: backend, HIGH risk (encryption, secrets), independent
- MCP server: new service surface, HIGH risk (auth, architecture), independent
Decomposition:
Workstream 1: optimize-and-temp (low/medium risk, Tier 2)
- .worktrees/optimize-and-temp, feat/optimize-and-temp
- Coder A: optimize button → review → test → commit
- Coder B: temperature display → review → test → commit
- PR #1
Workstream 2: ai-recommendations (HIGH risk, Tier 1)
- .worktrees/ai-recommendations, feat/ai-recommendations
- Human checkpoint: encryption approach + key storage design
- Coder C: encrypted key CRUD → security review → test → commit
- Coder D: wire recommendations → review → test → commit
- PR #2
Workstream 3: mcp-server (HIGH risk, Tier 1) — or DEFERRED per critic
- Human checkpoint: MCP SDK vs REST, auth model
- .worktrees/mcp-server, feat/mcp-server
- Coder E: MCP implementation → security review → adversarial test → commit
- PR #3
Example: 2 tightly-coupled features
User requests: add dark mode toggle + persist theme preference
Analysis:
- Toggle and persistence are tightly coupled (same state, same UX flow)
- Both touch settings page + theme context
Decomposition:
Single workstream: dark-mode (medium risk, Tier 2)
- One worktree, one branch, one PR
- Coder A: toggle + persistence together (they share state)
- Or split if toggle is pure UI and persistence is API: two coder calls