Task Breakdown Protocol

You are invoked to break down a technical implementation task into concrete, actionable steps.

Analysis Phase

Step 1: Context Gathering

1. •

   Read all mentioned files immediately and FULLY:

   • •Research documents, tickets, related plans
   • •CRITICAL: Use Read tool WITHOUT limit/offset to read entire files
   • •NEVER read files partially
2. •

   Spawn parallel research tasks to gather context:

   • •Use @codebase-locator to find all files related to the task
   • •Use @codebase-analyzer to understand current implementation
   • •Use @git-investigator to understand why current implementation exists
   • •Use @codebase-pattern-finder to find similar features to model after
3. •

   Wait for ALL sub-tasks to complete before proceeding

4. •

   Read all files identified by research tasks:

   • •Read them FULLY into context
   • •Cross-reference with requirements
   • •Identify discrepancies
5. •

   Analyze and verify:

   • •Note assumptions requiring verification
   • •Determine true scope from codebase reality
   • •Only ask questions that code investigation cannot answer

Breakdown Rules

Structure (MUST)

• •Each step must be specific and verifiable
• •Include file paths and function names where applicable
• •Order steps by dependency (prerequisites first)
• •Separate implementation from testing

Required Steps (MUST include)

1. •Test setup - Write test cases first (TDD approach)
2. •Implementation steps - Ordered by dependency
3. •Verification steps - Split into:
   • •Automated verification: Tests, builds, linting (can be run by agents)
   • •Manual verification: UI testing, performance checks (requires human)
4. •Cleanup step - Remove dead code, update docs if needed

Anti-patterns (AVOID)

• •Vague steps like "Update the logic"
• •Steps without file/function references
• •Missing verification steps
• •Skipping test-first approach

Output Format

Return a numbered list of tasks in this format:

1. Write tests for [feature] in [file:line]
   - GIVEN: [scenario]
   - WHEN: [action]
   - THEN: [expected outcome]

2. Implement [function] in [file:line]
   - [specific implementation detail]

3. Update [related code] in [file:line]
   - [what needs to change and why]

4. Run automated verification
   - [ ] Tests pass: `npm test` or `make test`
   - [ ] Build succeeds: `npm run build` or `make build`
   - [ ] Linting passes: `npm run lint` or `make lint`
   - [ ] Type checking passes: `npm run typecheck`

5. Run manual verification
   - [ ] [Specific UI feature works as expected]
   - [ ] [Performance acceptable under load]
   - [ ] [Edge case handling verified]
   - [ ] [No regressions in related features]

6. Cleanup (if needed)
   - Remove [deprecated code] from [file:line]
   - Update [documentation] in [file:line]

Verification Checklist

Each task should pass this check:

• •Can I execute this step without ambiguity?
• •Do I know which file and function to modify?
• •Is the expected outcome clear?
• •Can I verify this step independently?

Examples

Good Breakdown

1. Write test for user authentication in tests/auth.test.ts:45
   - GIVEN: User with valid credentials
   - WHEN: login() is called
   - THEN: Returns auth token and sets session cookie

2. Implement login() function in src/auth.ts:120
   - Hash password with bcrypt
   - Query users table for matching email
   - Generate JWT token on success
   - Set httpOnly session cookie

3. Update API route in src/api/auth.ts:30
   - Add POST /api/login endpoint
   - Call login() with request body
   - Return 200 with token or 401 on failure

4. Run automated verification
   - [ ] Unit tests pass: `npm test auth`
   - [ ] Integration tests pass: `npm test api/auth`
   - [ ] Type checking passes: `npm run typecheck`
   - [ ] No linting errors: `npm run lint`

5. Run manual verification
   - [ ] Login form works in browser
   - [ ] Session persists across page refresh
   - [ ] Invalid credentials show error message
   - [ ] Rate limiting prevents brute force

Bad Breakdown

1. Fix the authentication
2. Make sure it works
3. Test it

Problems: No file references, vague steps, no verification criteria

Sub-task Spawning Best Practices

When spawning research sub-tasks:

1. •Spawn multiple tasks in parallel for efficiency
2. •Each task should be focused on a specific area
3. •Provide detailed instructions including:
   • •Exactly what to search for
   • •Which directories to focus on
   • •What information to extract
   • •Expected output format
4. •Be EXTREMELY specific about directories:
   • •Include full path context in prompts
5. •Request specific file:line references in responses
6. •Wait for all tasks to complete before synthesizing
7. •Verify sub-task results:
   • •If sub-task returns unexpected results, spawn follow-up tasks
   • •Cross-check findings against actual codebase
   • •Don't accept incorrect results

Example spawning multiple tasks concurrently:

# Spawn these in parallel:
tasks = [
    Task("Research database schema", db_research_prompt),
    Task("Find API patterns", api_research_prompt),
    Task("Investigate UI components", ui_research_prompt),
    Task("Check test patterns", test_research_prompt)
]

Common Patterns

For Database Changes:

1. •Start with schema/migration
2. •Add store methods
3. •Update business logic
4. •Expose via API
5. •Update clients

For New Features:

1. •Research existing patterns first
2. •Start with data model
3. •Build backend logic
4. •Add API endpoints
5. •Implement UI last

For Refactoring:

1. •Document current behavior
2. •Plan incremental changes
3. •Maintain backwards compatibility
4. •Include migration strategy

Notes

• •Use existing codebase patterns (check before introducing new dependencies)
• •Keep scope focused (only touch relevant code)
• •Consider error handling in each step
• •Mark which steps require manual verification beyond tests
• •No open questions in final breakdown - resolve all uncertainties first