201 lines
8.6 KiB
Markdown
201 lines
8.6 KiB
Markdown
---
|
|
name: work-decomposition
|
|
description: Procedure for decomposing multi-feature requests into independent workstreams
|
|
— load when user requests 3+ features or features span independent domains
|
|
permalink: opencode-config/skills/work-decomposition/skill
|
|
---
|
|
|
|
## 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
|
|
|
|
1. **Security-sensitive design**: Encryption approach, auth model/flow, secret storage mechanism, token management, permission model changes.
|
|
2. **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).
|
|
3. **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?).
|
|
4. **New external dependencies**: Adding a new service, SDK, or infrastructure component not already in the project.
|
|
5. **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 cached guidance in basic-memory project `decisions/` notes
|
|
|
|
## 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:
|
|
1. **Single feature** description with acceptance criteria
|
|
2. **Specific file paths and edit points** from discovery (not vague references)
|
|
3. **Discovered values verbatim**: i18n keys, API signatures, component names, existing patterns
|
|
4. **Worktree path** for all file operations
|
|
5. **Active plan note** for the task (for example: a basic-memory project `plans/<feature>` note)
|
|
6. **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
|
|
``` |