Use this format for implementation-plan.md:
# Feature Name Implementation Plan
## Status: 🚧 IN PROGRESS
**Task List:** [task-list.md](./task-list.md)
---
## Overview
[Brief description of the feature]
## Current State
[Analysis of existing code]
## Load-bearing invariants (single source of truth)
[OPTIONAL but strongly recommended when the plan has cross-cutting rules that would otherwise be
restated across many tasks — an API contract or return-type shape, a visibility/boundary rule, a
"never do X" safety rule, a shared test convention. State each such rule ONCE here, canonically,
with exact symbol names and signatures, and declare this section authoritative: "task files apply
these in context but must not restate them differently; if a task snippet disagrees, this section
wins and the snippet is stale." A single referent stops the same rule drifting between a task's
Green snippet, its Context, and its acceptance criteria — the most common source of
contradict-and-patch churn.]
## Implementation Approach
[Detailed plan with phases]
## Files to Modify/Create
[List of files with descriptions]
## Task Details
| Task | Description | Details |
| ---- | ---------------- | -------------------------------------------------- |
| 1.1 | Task description | [tasks/1.1-task-name.md](./tasks/1.1-task-name.md) |
| 1.2 | Task description | [tasks/1.2-task-name.md](./tasks/1.2-task-name.md) |
## Research References
[If prior research exists in the project's .gumbo/research/ directory, link to relevant documents here]
- [research-doc-name.md](../../.gumbo/research/topic/research-doc-name.md)
## Testing Strategy
[How to test the changes — all tasks follow TDD Red/Green/Refactor]
Create a tasks/ subdirectory with a file for each substantive task. Use the naming convention {task-number}-{kebab-case-name}.md. Each task file follows strict Test-Driven Development (TDD) and must include explicit Red/Green/Refactor phases:
# Task 1.1: Short Task Title
## Objective
[What this task accomplishes]
## Location
[File(s) to create or modify, e.g. "New file: `src/module/foo.rs`" or "Modify: `src/module/bar.rs`"]
## TDD Phases
### 🔴 Red: Write Failing Tests
Write these test(s) first, before any implementation code:
```rust
#[test]
fn test_expected_behavior() {
// Arrange
let input = ...;
// Act
let result = function_under_test(input);
// Assert - this defines the expected behavior
assert_eq!(result, expected_value);
}
What the failing test asserts: [Describe what behavior the test defines]
Expected failure reason: [e.g., "function_under_test does not exist yet" or "returns wrong value because logic is missing"]
Run the test to confirm it fails for the expected reason. Do not write any implementation code during this phase.
🟢 Green: Minimal Implementation
Write the minimum code necessary to make the test(s) pass:
pub fn function_under_test(input: Type) -> OutputType {
}
Run the test to confirm it passes. No more code than necessary.
🔵 Refactor: Clean Up
[Describe refactoring opportunities, e.g.:]
- Extract helper function for [repeated logic]
- Rename [variable] for clarity
- Consolidate [duplicated code] with existing [function]
Run tests after refactoring to confirm they still pass. Commit after this phase.
Context
[Any additional notes: imports needed, related functions, edge cases to handle.
Link to research docs if relevant: see research-doc.md]
Acceptance Criteria
**Guidelines for task files:**
- Every task with implementation code must have explicit Red/Green/Refactor phases
- The Red phase must specify what tests to write, what they assert, and why they should fail
- The Green phase must describe only the minimal code to pass — no extras
- The Refactor phase should identify concrete cleanup opportunities
- Include enough code detail that implementation can proceed without re-reading the full codebase
- Show specific file paths, function signatures, struct definitions, and key logic
- Reference related research documents from `.gumbo/research/` when applicable
- Not every task-list item needs a task file — small or self-explanatory tasks (e.g., "run tests") can be described inline in the task list with `*(Covered in X.Y)*` or a brief note
- **Single-source each shared rule and symbol.** When a rule or a symbol (a function name, signature, type, or visibility) is introduced in one task and consumed by others, fix exactly one spelling for it — in the plan's invariants section or its owning task — and have other tasks *reference* it rather than restate it. Restated copies drift: a later edit fixes one and leaves the others contradicting, which an implementer then copies verbatim.
- **Verify cross-boundary visibility.** When a plan spans a package/crate or binary↔library boundary, state explicitly which symbols are public vs internal, and confirm every symbol a task consumes is visible from the consumer's location (e.g. a binary/CLI crate cannot see a library's `pub(crate)`/private items; a sibling module can). Getting this wrong produces won't-compile plans that look fine on the page.
- **Every consumed symbol must be defined by some task.** If task B uses `foo()`/`Bar`, some task must actually create it (don't write "owned by an earlier phase" against a symbol no task defines). Reconcile the producer and the consumer on one name, signature, and visibility.
