# Feature Breakdown

> Break down features into implementable tasks

- Skill: `vinilana/feature-breakdown` (Agent Skill)
- Install (CLI): `npx skillmds@latest add vinilana/feature-breakdown`
- Raw SKILL.md: https://api.skillmd.com/api/skills/vinilana/feature-breakdown/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: vinilana (https://skillmd.com/u/vinilana)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/vinilana/feature-breakdown

---


# Feature Breakdown

Break down features into concrete, implementable tasks within the `@dotcontext/cli` architecture.

## When to Use

- Starting the Planning (P) phase of a PREVC workflow
- Scoping a new CLI command, MCP tool, or service
- Creating a plan document in `.context/plans/`
- Estimating complexity to choose the right workflow scale (QUICK/SMALL/MEDIUM/LARGE)

## Instructions

### 1. Classify the Feature Scope

Determine which layers of the codebase are involved:

| Layer | Directory | Examples |
|-------|-----------|----------|
| CLI | `src/index.ts` | New command, new flag, output format change |
| Service | `src/services/<domain>/` | New business logic, data processing |
| Generator | `src/generators/` | New scaffold type, template changes |
| MCP | `src/services/mcp/` | New tool, new gateway action, schema change |
| Workflow | `src/workflow/` | Phase logic, gate rules, skill/agent integration |
| Utils | `src/utils/` | New utility function, i18n keys, CLI UI changes |
| Types | `src/types/`, `src/types.ts` | New interfaces, frontmatter types |

### 2. Determine the Workflow Scale

Use these criteria to set the `scale` when calling `workflow-init`:

| Scale | Criteria | Typical Feature |
|-------|----------|-----------------|
| QUICK | Single file, no design decisions | Fix typo, update translation key |
| SMALL | 2-5 files, straightforward logic | Add a flag to existing CLI command |
| MEDIUM | Multiple services, design decisions needed | New MCP gateway action with service |
| LARGE | New subsystem, cross-cutting concerns | New generator type, new AI provider |

### 3. Identify the Task Breakdown Pattern

Most features in this project follow one of these patterns:

#### Pattern A: New MCP Gateway Action
1. Define the action in the Zod schema (`mcpServer.ts`)
2. Add handler logic in the gateway file (`src/services/mcp/gateway/<tool>.ts`)
3. Create or extend the backing service (`src/services/<domain>/`)
4. Update type exports in `gatewayTools.ts` and `gateway/index.ts`
5. Add tests for the handler
6. Update MCP tool description string

#### Pattern B: New CLI Command
1. Define the command with Commander in `src/index.ts`
2. Create the service in `src/services/<name>/`
3. Add i18n keys to `src/utils/i18n.ts` (both `en` and `pt-BR`)
4. Wire CLI options to service calls
5. Add CLI output via `CLIInterface` from `src/utils/cliUI.ts`
6. Write tests

#### Pattern C: New Generator/Scaffold Type
1. Create generator class in `src/generators/<type>/`
2. Define templates in `src/generators/<type>/templates/`
3. Add frontmatter type to `src/types/scaffoldFrontmatter.ts`
4. Integrate with `InitService` for scaffold creation
5. Integrate with `FillService` for AI content generation
6. Add to MCP context gateway if applicable
7. Write generator tests

#### Pattern D: New Workflow Feature
1. Update types in `src/workflow/types.ts`
2. Modify phase/gate logic in `src/workflow/`
3. Update `WorkflowService` in `src/services/workflow/`
4. Update MCP workflow tools if user-facing
5. Write tests for phase transitions

### 4. Create the Plan Document

Use the MCP tool or create manually:

```bash
# Via MCP
context({ action: 'scaffoldPlan', planName: 'my-feature', title: 'My Feature', summary: 'What it does' })

# Manual creation in .context/plans/my-feature.md
```

Structure each phase with concrete steps:

```markdown
## Phases

### P - Planning
- [ ] Define requirements and acceptance criteria
- [ ] Identify affected services and files
- [ ] Choose workflow scale

### R - Review (for MEDIUM/LARGE)
- [ ] Review architecture impact
- [ ] Document design decisions as ADRs
- [ ] Get plan approval

### E - Execution
- [ ] Implement service logic in src/services/<domain>/
- [ ] Add MCP gateway handler (if applicable)
- [ ] Update CLI integration (if applicable)
- [ ] Add i18n keys for new user-facing strings
- [ ] Update type exports

### V - Validation
- [ ] Write unit tests with jest.mock() for externals
- [ ] Run full test suite: npm test
- [ ] Manual CLI verification: npx tsx src/index.ts <command>
- [ ] TypeScript compilation check: npm run build

### C - Confirmation (for LARGE)
- [ ] Update CHANGELOG.md
- [ ] Update relevant .context/ documentation
- [ ] Update README if public API changed
```

### 5. Identify Dependencies and Risks

Common dependencies to flag:
- **AI provider changes**: Require testing with actual API keys (not just mocks)
- **tree-sitter changes**: Optional dependency -- test with and without it installed
- **MCP protocol changes**: Must maintain backward compatibility with existing clients
- **Frontmatter format changes**: Must handle both v1 and v2 formats
- **i18n additions**: Both locales must be updated simultaneously

### 6. Link the Plan to the Workflow

After creating the plan, link it to the active workflow:

```
plan({ action: 'link', planSlug: 'my-feature' })
```

This enables phase tracking and the `commitPhase` action for git integration.

## Example: Breaking Down "Add Caching to Semantic Analysis"

**Scale**: MEDIUM (multiple files, design decision on cache strategy)

**Tasks**:
1. P: Define cache invalidation strategy (file mtime vs. content hash)
2. P: Decide cache storage location (`.context/.cache/` vs. temp dir)
3. R: Review impact on `CodebaseAnalyzer` and `SemanticContextBuilder`
4. E: Add cache layer to `src/services/semantic/codebaseAnalyzer.ts`
5. E: Add cache config to `AnalyzerOptions` type
6. E: Wire cache option through MCP `context({ action: 'buildSemantic' })` params
7. V: Test cache hit/miss with `codebaseAnalyzer.test.ts`
8. V: Test that `cacheEnabled: false` bypasses cache
9. V: Manual test with large repo to verify performance improvement

**Files affected**: `src/services/semantic/codebaseAnalyzer.ts`, `src/services/semantic/types.ts`, `src/services/mcp/gateway/context.ts`, `src/services/mcp/mcpServer.ts`