Implementation Plan for LLMS

gistfile1.txt

# PRD Implementation Framework with TDD

## Structure
- Root: Implementation Plan (`implementation_plan.md`)
- Level 1: Phases (folders: `phase_1`, `phase_2`, etc.)
- Level 2: Tasks (folders within phases: `task_1.1`, `task_1.2`, etc.)
- Level 3: Subtasks (files within task folders: `subtask_1.1.1.md`, etc.)
- Level 4: Implementation Units (files within subtask folders: `unit_1.1.1.1.md`, etc.)

## Implementation Process

### 1. Planning Stage
- Create an implementation plan in `implementation_plan.md` with:
  - A high-level checklist of phases
  - Global technological constraints:
    - Approved package list with specific versions
    - Banned packages or approaches
    - Architectural patterns to follow
- Break the implementation into logical phases (e.g., setup, core features, testing, deployment)
- For each phase, create a folder and a `phase_overview.md` with a checklist of tasks

### 2. Task Breakdown
- For each task in a phase:
  - Create a subfolder with an identifying name (`task_name`)
  - Create `task_details.md` with a description and checklist of subtasks
  - Ensure each task represents a cohesive piece of functionality

### 3. Subtask Definition
- For each subtask:
  - Create a file `subtask_name.md` within the task folder
  - Include a description, acceptance criteria, and checklist of implementation units
  - A subtask should be completable in a single coding session

### 4. Implementation Units with TDD
- For each implementation unit:
  - Create a file `unit_name.md` with:
    - Goal: Clear description of what this unit should accomplish
    - Function/Class Specification: Name, inputs, outputs, behavior
    - Test Cases: Multiple specific test cases with expected outputs
    - Edge Cases: Test cases for boundary conditions and error handling
    - Dependencies: Other units this depends on
    - **Allowed Packages**: Specific list of packages that may be used
      - Include version requirements if necessary
      - Note any package-specific constraints or usage patterns
    - **Implementation Constraints**: Any limitations on how to implement
  - Implementation phases for each unit (each with its own checklist item):
    1. **Red phase**: Write failing tests first
       - Create `unit_name.test.js` with comprehensive test cases
       - Verify tests fail for the right reasons
    2. **Green phase**: Implement minimal code to pass tests
       - Create `unit_name.js` with implementation
       - Run tests and iterate until all tests pass
    3. **Refactor phase**: Clean up implementation
       - Refactor code while maintaining passing tests
       - Document any decisions or trade-offs

### 5. Progress Tracking and Updates
- After completing an implementation unit:
  - Update the subtask document with completion status
  - Add a summary of the implemented functionality
  - List any exported functions/classes now available for use
  - Document any deviations from the original plan

- After completing a subtask:
  - Update the parent task document with:
    - Completion status of the subtask
    - Summary of all implementation units completed
    - List of all available functions/classes/modules
    - Any issues or learnings that affect subsequent subtasks

- After completing a task:
  - Update the parent phase document with:
    - Completion status of the task
    - Summary of functionality now available
    - Any changes to assumptions or requirements discovered
    - Dependencies available for subsequent tasks

### 6. Git Workflow
- Branch Strategy:
  - Create a branch for each phase: `phase/phase-name`
  - For each task, branch from the phase branch: `task/task-name`
  - Directly implement subtasks and units on the task branch
- Commit Structure:
  - Red commit: After writing failing tests
    - Message format: `[RED] unit-name: Add test cases for X functionality`
  - Green commit: After making tests pass
    - Message format: `[GREEN] unit-name: Implement X functionality`
  - Refactor commit: After cleaning up code
    - Message format: `[REFACTOR] unit-name: Improve X aspect`
  - Update commit: After updating parent documents
    - Message format: `[UPDATE] Update task/phase documentation for completed work`
- Merge Process:
  - After completing all units in a subtask, mark the subtask complete
  - After completing all subtasks in a task, merge the task branch to its phase branch
  - After completing all tasks in a phase, merge the phase branch to main

### 7. Implementation Guidelines
- Never write implementation code until tests are written and verified to fail
- Tests must be specific enough to drive the implementation
- Each test should verify one specific behavior or edge case
- **No mocks or test doubles**: Build real dependencies first and use them in tests
- Maintain a test coverage goal (e.g., 90%+)
- Order implementation units so dependencies are built before dependent code
- Include automated test verification in the workflow
- Document any discovered edge cases during implementation
- Only use explicitly allowed packages for each implementation unit
- Follow specified architectural patterns and coding standards

## Templates

### Phase Overview Template
```markdown
# Phase: [Phase Name]

## Description
[Brief description of this phase and its objectives]

## Technological Constraints
- **Approved Packages**: [List of allowed packages with versions]
- **Architectural Patterns**: [Patterns to follow]
- **Coding Standards**: [Link or reference to standards]

## Tasks Checklist
- [ ] Task 1: [Brief description]
- [ ] Task 2: [Brief description]
- [ ] Task 3: [Brief description]

## Completion Status
- Start Date: [Date]
- Current Status: [Not Started/In Progress/Completed]
- Completion Date: [Date when completed]

## Available Components After Phase Completion
[To be filled after phase is complete - list of all available components]
```

### Task Details Template
```markdown
# Task: [Task Name]

## Description
[Detailed description of the task and its objectives]

## Dependencies
- [List any dependencies on other tasks/components]

## Subtasks Checklist
- [ ] Subtask 1: [Brief description]
- [ ] Subtask 2: [Brief description]
- [ ] Subtask 3: [Brief description]

## Completion Status
- Start Date: [Date]
- Current Status: [Not Started/In Progress/Completed]
- Completion Date: [Date when completed]

## Available Components After Task Completion
[To be filled after task is complete - list of all available components]
```

### Subtask Template
```markdown
# Subtask: [Subtask Name]

## Description
[Detailed description of the subtask]

## Acceptance Criteria
- [Criterion 1]
- [Criterion 2]
- [Criterion 3]

## Implementation Units Checklist
- [ ] Unit 1: [Brief description]
- [ ] Unit 2: [Brief description]
- [ ] Unit 3: [Brief description]

## Completion Status
- Start Date: [Date]
- Current Status: [Not Started/In Progress/Completed]
- Completion Date: [Date when completed]

## Available Components After Subtask Completion
[To be filled after subtask is complete - list of all available components]
```

### Implementation Unit Template
```markdown
# Implementation Unit: [Unit Name]

## Goal
[Clear description of what this unit should accomplish]

## Function/Class Specification
- **Name**: [Name of function/class]
- **Inputs**: [Description of inputs with types]
- **Outputs**: [Description of outputs with types]
- **Behavior**: [Detailed description of expected behavior]

## Dependencies
- [List any dependencies on other implementation units]

## Allowed Packages
- [Package 1] v[X.Y.Z]
- [Package 2] v[X.Y.Z]
- [Internal dependency 1]

## Implementation Constraints
- [Any specific constraints on implementation approach]
- [Performance requirements]
- [Memory limitations]

## Test Cases
1. **Test Case 1**: [Description]
   - Input: [Input values]
   - Expected Output: [Expected output]
   
2. **Test Case 2**: [Description]
   - Input: [Input values]
   - Expected Output: [Expected output]

## Edge Cases
1. **Edge Case 1**: [Description]
   - Input: [Input values]
   - Expected Output: [Expected output]
   
2. **Edge Case 2**: [Description]
   - Input: [Input values]
   - Expected Output: [Expected output]

## TDD Checklist
### Dependencies Check
- [ ] Verify all dependency units are completed and working
- [ ] Review the APIs of dependencies to understand integration points
- [ ] Confirm you're only using the allowed packages

### Red Phase
- [ ] Identify specific behaviors to test
- [ ] Write test for "happy path" (normal operation)
- [ ] Write tests for edge cases
- [ ] Write tests for error conditions
- [ ] Verify all tests fail for expected reasons

### Green Phase
- [ ] Implement minimal code to pass happy path test
- [ ] Verify happy path test passes
- [ ] Implement code for edge cases
- [ ] Implement error handling
- [ ] Verify all tests pass

### Refactor Phase
- [ ] Remove duplication
- [ ] Improve naming
- [ ] Optimize for readability
- [ ] Ensure code follows project style guidelines
- [ ] Verify all tests still pass after refactoring

### Documentation Update
- [ ] Update the implementation unit document marking it complete
- [ ] Update the parent subtask document with:
  - [ ] Completion status
  - [ ] Summary of implemented functionality
  - [ ] List of exported functions/classes now available
  - [ ] Any deviations from original plan

## Implementation Notes
[To be filled during implementation - any decisions, trade-offs, or challenges]

## Completion Status
- Start Date: [Date]
- Current Status: [Not Started/In Progress/Completed]
- Completion Date: [Date when completed]
```

This framework provides a structured approach to implementing PRDs using TDD principles, with clear tracking of progress, careful management of dependencies, and controlled use of external packages. The hierarchy from phases down to implementation units ensures that work is broken down into manageable pieces while maintaining a clear connection to the overall project goals.