Task Plan Creator

You are creating a detailed implementation plan from an approved design document. The plan will be executed by Claude Code agents via ralphex, so it must be detailed, unambiguous, and self-contained.

Prerequisites

Before starting, verify that an approved design exists:

•Look for tasks/plans/YYYY-MM-DD-feature-name.md
•Check that frontmatter contains status: approved

If no approved design exists:

code

No approved design found for this feature.
Run /task-design first to create and approve a design, or specify the design file path.

If design exists but not approved:

code

Design exists but status is '[current-status]', not 'approved'.
Run /task-design to continue the design process.

Output Location

Write the plan inside the existing design document: tasks/plans/YYYY-MM-DD-feature-name.md

Add a new section # Implementation Plan at the end of the design document (after # Context).

Plan Structure

Add the following section to the design document:

markdown

# Implementation Plan

## Overview
[2-4 sentences describing what will be implemented and why - derived from Problem Statement]

## Development Approach
- Complete each task fully before moving to the next
- Make small, focused changes
- **CRITICAL: all tests must pass before starting next task**
- **CRITICAL: update this plan when scope changes**

## Validation Commands
- `[test command]` - Run tests
- `[typecheck command]` - Type checking
- `[lint command]` - Linting (if applicable)

---

## Task 1: [Task Name]
- [ ] [Specific action item]
- [ ] [Another action item]
- [ ] Write/update tests for this task
- [ ] Run `[validation command]` - must pass before next task

---

## Task 2: [Task Name]
...

---

## Task [N-1]: Update documentation
- [ ] Update CLAUDE.md with new patterns/conventions (if applicable)
- [ ] Add inline documentation for complex functions
- [ ] Update API documentation (if applicable)
- [ ] Run `bun test` and `bun run typecheck` - must pass before next task

---

## Task [Final]: Cleanup design artifacts
- [ ] Remove all `DESIGN PROTOTYPE: YYYY-MM-DD-feature-name.md` comments from codebase
- [ ] Delete any empty scaffold files that were replaced
- [ ] Update design document status to `implemented`
- [ ] Verify no prototype markers remain: `grep -r "DESIGN PROTOTYPE: YYYY-MM-DD-feature-name" src/`
- [ ] Run `bun test:all` and `bun run typecheck` - final verification

---

## Post-Completion Verification
1. **Functional test**: [Describe how to manually test the feature]
2. **Edge case test**: [Test a specific edge case manually]
3. **Integration check**: [Verify integration with existing features]
4. **No regressions**: All existing tests pass
5. **Cleanup verified**: No DESIGN PROTOTYPE comments remain

Your Process

Phase 1: Load Design Context

•Read the approved design document completely
•Read all prototype placeholder files listed in prototype-files frontmatter
•
Understand:
- •The problem being solved (from Problem Statement)
- •The chosen approach and rationale (from Proposed Approach, Key Decisions)
- •All affected files (from Affected Components)
- •Technical details (from Technical Details)
- •Edge cases identified (from Edge Cases and Error Handling)
- •Test cases planned (from Test Cases)
- •Review notes (from AI Review Notes)

Phase 2: Analyze Prototype Placeholders

For each file with DESIGN PROTOTYPE: <design-file> markers:

•Identify what changes are outlined
•Determine dependencies between changes
•Group related changes into logical tasks
•Order tasks so dependencies are satisfied

Phase 3: Create Task Breakdown

Convert the design into discrete, ordered tasks:

•Group by component: Changes to related files go in same task
•Order by dependency: Foundation tasks before tasks that depend on them
•Include tests: Every task must have test checkboxes
•Add validation gates: Every task ends with passing validation commands
•Keep tasks focused: 2-8 checkboxes per task is ideal

Task ordering principles:

•Types/interfaces before implementations
•Core logic before integrations
•Unit tests alongside implementation
•Integration tests after components exist
•Documentation second-to-last
•Cleanup last

Phase 4: Write the Implementation Plan

Add # Implementation Plan section to tasks/plans/YYYY-MM-DD-feature-name.md with:

•Overview derived from design's Problem Statement
•Development approach guidelines
•Validation commands appropriate for this project
•Detailed tasks with specific checkboxes
•Documentation task (second-to-last)
•Cleanup task to remove prototype placeholders (last)
•Post-completion verification steps

Phase 5: Verify Plan Quality

Critically and thoroughly review the plan before presenting to user:

•Plan is written inside the design document under # Implementation Plan
•Every affected file from design's Affected Components is covered in tasks
•Every prototype placeholder location has a corresponding task
•Tasks are ordered so dependencies are satisfied
•Each task has 2-8 specific checkboxes
•Every task ends with validation gate
•Tasks reference design's Technical Details for implementation specifics
•Tasks reference design's Edge Cases for error handling
•Tasks cover ALL test cases mentioned in the design document
•There's a task focused on documentation updates (CLAUDE.md, docs, user guides, inline comments)
•There's a task focused on cleaning up all DESIGN PROTOTYPE markers
•Post-completion verification steps are defined

Phase 6: Update the document status

Change the design document status to planned.

Task Writing Guidelines

Good Task Structure

markdown

### Task 3: Implement user validation middleware

- [ ] Create `src/middleware/validate-user.ts` with `validateUser()` function
- [ ] Validate JWT token from Authorization header
- [ ] Return 401 for missing/invalid tokens, 403 for expired tokens
- [ ] Add middleware to protected routes in `src/routes/index.ts`
- [ ] Write unit tests in `src/middleware/validate-user.test.ts`
- [ ] Write integration test for protected endpoint
- [ ] Run `bun test` and `bun run typecheck` - must pass before next task

Bad Task Structure (avoid)

markdown

### Task 3: Add auth
- [ ] Implement authentication
- [ ] Add tests

Checkbox Guidelines

Each checkbox should be:

•Specific: Name exact files, functions, endpoints
•Verifiable: Clear success criteria
•Atomic: One logical action per checkbox
•Ordered: Later checkboxes may depend on earlier ones

Include checkboxes for:

•Implementation steps (reference prototype placeholder locations)
•Test creation/updates
•Error handling (reference design's Edge Cases section)
•Edge case coverage
•Documentation updates (inline comments for complex logic)

Testing Requirements

Every task MUST include testing checkboxes:

markdown

- [ ] Write unit tests for [specific function/module]
- [ ] Write integration tests for [specific flow]
- [ ] Add test cases for edge cases: [list them]
- [ ] Run `[test command]` - must pass before next task

Test coverage should include:

•Happy path scenarios
•Error conditions
•Edge cases (empty inputs, boundary values, concurrent access)
•Integration with adjacent components

Converting Prototype Placeholders to Tasks

From new file scaffold:

Prototype:

typescript

// ═══════════════════════════════════════════════════════════════════════════
// DESIGN PROTOTYPE: 2026-01-28-feature.md
// ═══════════════════════════════════════════════════════════════════════════
//
// export interface UserSession { ... }
// export function createSession(userId: string): UserSession
// export function validateSession(token: string): boolean

Task:

markdown

### Task 2: Implement session management module

- [ ] Replace prototype scaffold in `src/session/manager.ts` with actual implementation
- [ ] Implement `UserSession` interface as specified in design's Technical Details
- [ ] Implement `createSession()` function with JWT generation
- [ ] Implement `validateSession()` function with expiry checking
- [ ] Export all public types and functions
- [ ] Write unit tests in `src/session/manager.test.ts`
- [ ] Run `bun test` and `bun run typecheck` - must pass before next task

From inline markers:

Prototype:

typescript

// DESIGN PROTOTYPE: 2026-01-28-feature.md
// Add parameter → mappingType: MappingTypeName = "loinc"
export function generateConceptMapId(sender: SenderContext): string {

Task:

markdown

### Task 4: Update generateConceptMapId for multiple mapping types

- [ ] Add `mappingType: MappingTypeName = "loinc"` parameter to `generateConceptMapId()`
- [ ] Import `MappingTypeName` from `src/code-mapping/mapping-types.ts`
- [ ] Use `MAPPING_TYPES[mappingType].conceptMapSuffix` instead of hardcoded `-to-loinc`
- [ ] Update all existing call sites (should work with default parameter)
- [ ] Add unit tests for new parameter with different mapping types
- [ ] Run `bun test` and `bun run typecheck` - must pass before next task

Validation Commands

Always include commands that verify correctness. Get these from the project's CLAUDE.md or package.json:

markdown

## Validation Commands
- `bun test` - Run all tests
- `bun run typecheck` - Type checking
- `bun run lint` - Linting (if applicable)
- `bun run build` - Verify build succeeds (if applicable)