diff --git a/get-shit-done/references/plan-format.md b/get-shit-done/references/plan-format.md index fd4127987..f7ea067ee 100644 --- a/get-shit-done/references/plan-format.md +++ b/get-shit-done/references/plan-format.md @@ -243,42 +243,30 @@ Use for: Technology selection, architecture decisions, design choices, feature p See `./checkpoints.md` for comprehensive checkpoint guidance. - -Tasks can include `tdd="true"` attribute when TDD improves quality: + +**TDD work uses dedicated plans.** -**Structure:** -```xml - - Task N: [Name] - [paths] - [What test to write first - the failing assertion] - [Implementation to make test pass] - [Tests pass, behavior works] - [Criteria] - -``` +TDD features require 2-3 execution cycles (RED → GREEN → REFACTOR), each with file reads, test runs, and potential debugging. This is fundamentally heavier than standard tasks and would consume 50-60% of context if embedded in a multi-task plan. -**When to add tdd="true":** +**When to create a TDD plan:** - Business logic with defined inputs/outputs - API endpoints with request/response contracts - Data transformations and parsing - Validation rules - Algorithms with testable behavior -**When NOT to add tdd="true":** +**When to use standard plans (skip TDD):** - UI layout and styling - Configuration changes - Glue code connecting existing components - One-off scripts -**Execution flow (when tdd="true"):** -1. Claude writes failing test from `` -2. Claude implements from `` until test passes -3. Claude refactors if needed (tests still pass) -4. Claude commits atomic change +**Heuristic:** Can you write `expect(fn(input)).toBe(output)` before writing `fn`? +→ Yes: Create a TDD plan (one feature per plan) +→ No: Use standard plan, add tests after if needed -See `./tdd.md` for comprehensive TDD guidance. - +See `./tdd.md` for TDD plan structure and execution guidance. + Use @file references to load context for the prompt: @@ -384,25 +372,11 @@ Claude: "How? What type? What library? Where?" Claude can implement this immediately. - -TDD task example: + +**TDD candidates get dedicated plans.** -```xml - - Task 2: Create email validation utility - src/lib/validation.ts, src/lib/validation.test.ts - - Test: isValidEmail returns true for valid emails, false for invalid - Cases: "user@example.com" → true, "invalid" → false, "" → false, "user@" → false - - Implement isValidEmail using regex pattern. Handle edge cases: empty string, missing @, missing domain. - npm test -- validation.test.ts passes all cases - Email validation works for all edge cases, tests document behavior - -``` - -Claude executes this with RED → GREEN → REFACTOR cycle, producing atomic commits. - +If email validation warrants TDD, create a TDD plan for it. See `./tdd.md` for TDD plan structure. + Writing the actual code in the plan. Trust Claude to implement from clear instructions. diff --git a/get-shit-done/references/principles.md b/get-shit-done/references/principles.md index 8c4b5f827..abc048a9a 100644 --- a/get-shit-done/references/principles.md +++ b/get-shit-done/references/principles.md @@ -77,7 +77,7 @@ Plans are guides, not straitjackets. During execution: Use TDD when the work WOULD benefit from it. Not dogma—pragmatism. -**TDD candidates (write test first):** +**TDD candidates (create dedicated TDD plan):** - Business logic with defined inputs/outputs - API endpoints and handlers - Data transformations and parsing @@ -85,7 +85,7 @@ Use TDD when the work WOULD benefit from it. Not dogma—pragmatism. - State machines and workflows - Anything where you can describe expected behavior before implementing -**Skip TDD for:** +**Skip TDD (use standard plan):** - UI layout and styling - Exploratory prototyping - One-off scripts and migrations @@ -94,16 +94,20 @@ Use TDD when the work WOULD benefit from it. Not dogma—pragmatism. **Decision heuristic:** Can you write `expect(fn(input)).toBe(output)` before writing `fn`? -→ Yes: TDD will help -→ No: Write implementation first, add tests after if needed +→ Yes: Create a TDD plan (one feature per plan) +→ No: Standard plan, add tests after if needed -**TDD task structure:** -When TDD applies, structure tasks as test-first: -1. Write failing test (red) -2. Implement to pass (green) -3. Refactor if needed +**Why TDD gets its own plan:** +TDD requires 2-3 execution cycles (RED → GREEN → REFACTOR), each with file reads, test runs, and potential debugging. This consumes 40-50% of context for a single feature. Dedicated TDD plans ensure full quality throughout the cycle. + +**TDD plan structure:** +1. Write failing test (RED) → commit +2. Implement to pass (GREEN) → commit +3. Refactor if needed → commit This is about design quality, not test coverage metrics. + +See `~/.claude/get-shit-done/references/tdd.md` for TDD plan structure. diff --git a/get-shit-done/references/scope-estimation.md b/get-shit-done/references/scope-estimation.md index 11feb4cac..de223ab03 100644 --- a/get-shit-done/references/scope-estimation.md +++ b/get-shit-done/references/scope-estimation.md @@ -38,6 +38,27 @@ Why 50% not 80%? **When in doubt: Default to 2 tasks.** Better to have an extra plan than degraded quality. + +**TDD features get their own plans. Target ~40% context.** + +TDD requires 2-3 execution cycles (RED → GREEN → REFACTOR), each with file reads, test runs, and potential debugging. This is fundamentally heavier than linear task execution. + +| TDD Feature Complexity | Context Usage | +|------------------------|---------------| +| Simple utility function | ~25-30% | +| Business logic with edge cases | ~35-40% | +| Complex algorithm | ~40-50% | + +**One feature per TDD plan.** If features are trivial enough to batch, they're trivial enough to skip TDD. + +**Why TDD plans are separate:** +- TDD consumes 40-50% context for a single feature +- Dedicated plans ensure full quality throughout RED-GREEN-REFACTOR +- Each TDD feature gets fresh context, peak quality + +See `~/.claude/get-shit-done/references/tdd.md` for TDD plan structure. + + diff --git a/get-shit-done/references/tdd.md b/get-shit-done/references/tdd.md index 223bf2675..e9bb44ea2 100644 --- a/get-shit-done/references/tdd.md +++ b/get-shit-done/references/tdd.md @@ -2,12 +2,14 @@ TDD is about design quality, not coverage metrics. The red-green-refactor cycle forces you to think about behavior before implementation, producing cleaner interfaces and more testable code. **Principle:** If you can describe the behavior as `expect(fn(input)).toBe(output)` before writing `fn`, TDD improves the result. + +**Key insight:** TDD work is fundamentally heavier than standard tasks—it requires 2-3 execution cycles (RED → GREEN → REFACTOR), each with file reads, test runs, and potential debugging. TDD features get dedicated plans to ensure full context is available throughout the cycle. - + ## When TDD Improves Quality -**TDD candidates (add `tdd="true"`, include ``):** +**TDD candidates (create a TDD plan):** - Business logic with defined inputs/outputs - API endpoints with request/response contracts - Data transformations, parsing, formatting @@ -16,7 +18,7 @@ TDD is about design quality, not coverage metrics. The red-green-refactor cycle - State machines and workflows - Utility functions with clear specifications -**Skip TDD (standard `type="auto"`):** +**Skip TDD (use standard plan with `type="auto"` tasks):** - UI layout, styling, visual components - Configuration changes - Glue code connecting existing components @@ -25,32 +27,89 @@ TDD is about design quality, not coverage metrics. The red-green-refactor cycle - Exploratory prototyping **Heuristic:** Can you write `expect(fn(input)).toBe(output)` before writing `fn`? -→ Yes: TDD will help -→ No: Implement first, add tests after if needed - +→ Yes: Create a TDD plan +→ No: Use standard plan, add tests after if needed + + + +## TDD Plan Structure + +Each TDD plan implements **one feature** through the full RED-GREEN-REFACTOR cycle. + +```markdown +--- +phase: XX-name +plan: NN +type: tdd +--- + + +[What feature and why] +Purpose: [Design benefit of TDD for this feature] +Output: [Working, tested feature] + + + +@.planning/PROJECT.md +@.planning/ROADMAP.md +@relevant/source/files.ts + + + + [Feature name] + [source file, test file] + + [Expected behavior in testable terms] + Cases: input → expected output + + [How to implement once tests pass] + + + +[Test command that proves feature works] + + + +- Failing test written and committed +- Implementation passes test +- Refactor complete (if needed) +- All 2-3 commits present + + + +After completion, create SUMMARY.md with: +- RED: What test was written, why it failed +- GREEN: What implementation made it pass +- REFACTOR: What cleanup was done (if any) +- Commits: List of commits produced + +``` + +**One feature per TDD plan.** If features are trivial enough to batch, they're trivial enough to skip TDD—use a standard plan and add tests after. + ## Red-Green-Refactor Cycle **RED - Write failing test:** 1. Create test file following project conventions -2. Write test describing expected behavior (from `` element) +2. Write test describing expected behavior (from `` element) 3. Run test - it MUST fail 4. If test passes: feature exists or test is wrong. Investigate. -5. Commit: `test: add failing test for [feature]` +5. Commit: `test({phase}-{plan}): add failing test for [feature]` **GREEN - Implement to pass:** 1. Write minimal code to make test pass 2. No cleverness, no optimization - just make it work 3. Run test - it MUST pass -4. Commit: `feat: implement [feature]` +4. Commit: `feat({phase}-{plan}): implement [feature]` **REFACTOR (if needed):** 1. Clean up implementation if obvious improvements exist 2. Run tests - MUST still pass -3. Only commit if changes made: `refactor: clean up [feature]` +3. Only commit if changes made: `refactor({phase}-{plan}): clean up [feature]` -**Atomic commits:** Each TDD task produces 2-3 commits following this pattern. +**Result:** Each TDD plan produces 2-3 atomic commits. @@ -77,7 +136,7 @@ TDD is about design quality, not coverage metrics. The red-green-refactor cycle ## Test Framework Setup (If None Exists) -When a TDD task exists but no test framework is configured: +When executing a TDD plan but no test framework is configured, set it up as part of the RED phase: **1. Detect project type:** ```bash @@ -122,6 +181,8 @@ Follow project conventions for test location: - `*.test.ts` / `*.spec.ts` next to source - `__tests__/` directory - `tests/` directory at root + +Framework setup is a one-time cost included in the first TDD plan's RED phase. @@ -134,7 +195,7 @@ Follow project conventions for test location: **Test doesn't pass in GREEN phase:** - Debug implementation -- Don't skip to next task +- Don't skip to refactor - Keep iterating until green **Tests fail in REFACTOR phase:** @@ -149,39 +210,54 @@ Follow project conventions for test location: -## Commit Pattern for TDD Tasks +## Commit Pattern for TDD Plans -TDD tasks produce 2-3 atomic commits (one per TDD phase): +TDD plans produce 2-3 atomic commits (one per phase): ``` -test({phase}-{plan}): add failing test for email validation +test(08-02): add failing test for email validation - Tests valid email formats accepted - Tests invalid formats rejected - Tests empty input handling -feat({phase}-{plan}): implement email validation +feat(08-02): implement email validation - Regex pattern matches RFC 5322 - Returns boolean for validity - Handles edge cases (empty, null) -refactor({phase}-{plan}): extract regex to constant (optional) +refactor(08-02): extract regex to constant (optional) - Moved pattern to EMAIL_REGEX constant - No behavior changes - Tests still pass ``` -**This aligns with the standard task commit pattern:** -- Non-TDD tasks: 1 commit per task (feat/fix) -- TDD tasks: 2-3 commits per task (test/feat/refactor) +**Comparison with standard plans:** +- Standard plans: 1 commit per task, 2-4 commits per plan +- TDD plans: 2-3 commits for single feature Both follow same format: `{type}({phase}-{plan}): {description}` **Benefits:** - Each commit independently revertable -- Git bisect works at commit level (not just task level) +- Git bisect works at commit level - Clear history showing TDD discipline - Consistent with overall commit strategy + + +## Context Budget + +TDD plans target **~40% context usage** (lower than standard plans' ~50%). + +Why lower: +- RED phase: write test, run test, potentially debug why it didn't fail +- GREEN phase: implement, run test, potentially iterate on failures +- REFACTOR phase: modify code, run tests, verify no regressions + +Each phase involves reading files, running commands, analyzing output. The back-and-forth is inherently heavier than linear task execution. + +Single feature focus ensures full quality throughout the cycle. + diff --git a/get-shit-done/templates/phase-prompt.md b/get-shit-done/templates/phase-prompt.md index 63086d453..4f5917e35 100644 --- a/get-shit-done/templates/phase-prompt.md +++ b/get-shit-done/templates/phase-prompt.md @@ -169,7 +169,20 @@ From create-meta-prompts patterns: - Different subsystems (auth vs API vs UI) - Clear dependency boundaries (setup → implement → test) - Risk of context overflow (>50% estimated usage) - +- **TDD candidates** - Features that warrant TDD become their own TDD plans + + + +**TDD features get dedicated plans.** + +TDD requires 2-3 execution cycles (RED → GREEN → REFACTOR) that consume 40-50% context for a single feature. Features warranting TDD (business logic, validation, algorithms, API contracts) each get their own TDD plan. + +**Heuristic:** Can you write `expect(fn(input)).toBe(output)` before writing `fn`? +→ Yes: Create a TDD plan (one feature per plan) +→ No: Standard task in standard plan + +See `~/.claude/get-shit-done/references/tdd.md` for TDD plan structure. + diff --git a/get-shit-done/workflows/execute-phase.md b/get-shit-done/workflows/execute-phase.md index 39eb1e56c..b95f02061 100644 --- a/get-shit-done/workflows/execute-phase.md +++ b/get-shit-done/workflows/execute-phase.md @@ -815,55 +815,62 @@ Logged to .planning/ISSUES.md for future consideration: - -## TDD Task Execution + +## TDD Plan Execution -When executing a task with `tdd="true"` attribute: +When executing a plan with `type: tdd` in frontmatter, follow the RED-GREEN-REFACTOR cycle for the single feature defined in the plan. -**1. Check test infrastructure:** +**1. Check test infrastructure (if first TDD plan):** If no test framework configured: - Detect project type from package.json/requirements.txt/etc. - Install minimal test framework (Jest, pytest, Go testing, etc.) - Create test config file - Verify: run empty test suite +- This is part of the RED phase, not a separate task **2. RED - Write failing test:** -- Read `` element for test specification +- Read `` element for test specification - Create test file if doesn't exist (follow project conventions) - Write test(s) that describe expected behavior - Run tests - MUST fail (if passes, test is wrong or feature exists) -- Commit: "test: add failing test for [feature]" +- Commit: `test({phase}-{plan}): add failing test for [feature]` **3. GREEN - Implement to pass:** -- Read `` element for implementation guidance +- Read `` element for guidance - Write minimal code to make test pass - Run tests - MUST pass -- Commit: "feat: implement [feature]" +- Commit: `feat({phase}-{plan}): implement [feature]` **4. REFACTOR (if needed):** - Clean up code if obvious improvements - Run tests - MUST still pass -- Commit only if changes made: "refactor: clean up [feature]" +- Commit only if changes made: `refactor({phase}-{plan}): clean up [feature]` -**Commit pattern for TDD tasks:** -Each TDD task produces 2-3 atomic commits: -1. `test: add failing test for X` -2. `feat: implement X` -3. `refactor: clean up X` (optional) +**Commit pattern for TDD plans:** +Each TDD plan produces 2-3 atomic commits: +1. `test({phase}-{plan}): add failing test for X` +2. `feat({phase}-{plan}): implement X` +3. `refactor({phase}-{plan}): clean up X` (optional) **Error handling:** - If test doesn't fail in RED phase: Test is wrong or feature already exists. Investigate before proceeding. -- If test doesn't pass in GREEN phase: Debug implementation, don't skip to next task. +- If test doesn't pass in GREEN phase: Debug implementation, keep iterating until green. - If tests fail in REFACTOR phase: Undo refactor, commit was premature. **Verification:** -After TDD task completion, ensure: +After TDD plan completion, ensure: - All tests pass - Test coverage for the new behavior exists - No unrelated tests broken -**Note:** TDD tasks produce 2-3 commits (test/feat/refactor). Non-TDD tasks produce 1 commit after task completion. - +**Why TDD uses dedicated plans:** TDD requires 2-3 execution cycles (RED → GREEN → REFACTOR), each with file reads, test runs, and potential debugging. This consumes 40-50% of context for a single feature. Dedicated plans ensure full quality throughout the cycle. + +**Comparison:** +- Standard plans: Multiple tasks, 1 commit per task, 2-4 commits total +- TDD plans: Single feature, 2-3 commits for RED/GREEN/REFACTOR cycle + +See `~/.claude/get-shit-done/references/tdd.md` for TDD plan structure. + ## Task Commit Protocol @@ -917,7 +924,7 @@ git commit -m "{type}({phase}-{plan}): {concise task description} **Examples:** ```bash -# Non-TDD task +# Standard plan task git commit -m "feat(08-02): create user registration endpoint - POST /auth/register validates email and password @@ -925,31 +932,16 @@ git commit -m "feat(08-02): create user registration endpoint - Returns JWT token on success " -# TDD task - RED phase -git commit -m "test(07-02): add failing test for JWT generation +# Another standard task +git commit -m "fix(08-02): correct email validation regex -- Tests token contains user ID claim -- Tests token expires in 1 hour -- Tests signature verification -" - -# TDD task - GREEN phase -git commit -m "feat(07-02): implement JWT generation - -- Uses jose library for signing -- Includes user ID and expiry claims -- Signs with HS256 algorithm -" - -# TDD task - REFACTOR phase -git commit -m "refactor(07-02): extract JWT config to constants - -- Moved expiry time to constant -- Centralized algorithm selection -- No behavior changes +- Fixed regex to accept plus-addressing +- Added tests for edge cases " ``` +**Note:** TDD plans have their own commit pattern (test/feat/refactor for RED/GREEN/REFACTOR phases). See `` section above. + **5. Record commit hash:** After committing, capture hash for SUMMARY.md: diff --git a/get-shit-done/workflows/plan-phase.md b/get-shit-done/workflows/plan-phase.md index 049be9407..a19d799c4 100644 --- a/get-shit-done/workflows/plan-phase.md +++ b/get-shit-done/workflows/plan-phase.md @@ -225,7 +225,9 @@ cat .planning/phases/XX-name/${PHASE}-CONTEXT.md 2>/dev/null -Decompose phase into tasks. Each task needs: +Decompose phase into tasks and identify TDD candidates. + +**Standard tasks need:** - **Type**: auto, checkpoint:human-verify, checkpoint:decision (human-action rarely needed) - **Task name**: Clear, action-oriented - **Files**: Which files created/modified (for auto tasks) @@ -233,9 +235,9 @@ Decompose phase into tasks. Each task needs: - **Verify**: How to prove it worked - **Done**: Acceptance criteria -**TDD detection:** For each task, evaluate TDD fit: +**TDD detection:** For each potential task, evaluate TDD fit: -TDD candidates (add `tdd="true"` to task, include `` element): +TDD candidates (create dedicated TDD plans): - Business logic with defined inputs/outputs - API endpoints with request/response contracts - Data transformations, parsing, formatting @@ -243,7 +245,7 @@ TDD candidates (add `tdd="true"` to task, include `` element): - Algorithms with testable behavior - State machines and workflows -Skip TDD (standard `type="auto"` task): +Standard tasks (remain in standard plans): - UI layout, styling, visual components - Configuration changes - Glue code connecting existing components @@ -251,15 +253,14 @@ Skip TDD (standard `type="auto"` task): - Simple CRUD with no business logic **Heuristic:** Can you write `expect(fn(input)).toBe(output)` before writing `fn`? -→ Yes: Add `tdd="true"`, include `` describing the failing test -→ No: Standard task, no TDD annotation +→ Yes: Create a dedicated TDD plan for this feature (one feature per TDD plan) +→ No: Standard task in standard plan -**Test framework:** If project has no test setup and TDD tasks exist, add a setup task first: -- Detect project type (package.json → Jest, requirements.txt → pytest, etc.) -- Add minimal test configuration -- Create example test file to verify setup +**Why TDD gets its own plan:** TDD requires 2-3 execution cycles (RED → GREEN → REFACTOR), each with file reads, test runs, and potential debugging. Embedded in a multi-task plan, TDD work consumes 50-60% of context alone, degrading quality for remaining tasks. -See `~/.claude/get-shit-done/references/tdd.md` for complete TDD guidance. +**Test framework:** If project has no test setup and TDD plans are needed, the first TDD plan's RED phase handles framework setup as part of writing the first test. + +See `~/.claude/get-shit-done/references/tdd.md` for TDD plan structure. **Checkpoints:** Visual/functional verification → checkpoint:human-verify. Implementation choices → checkpoint:decision. Manual action (email, 2FA) → checkpoint:human-action (rare). @@ -427,20 +428,7 @@ Phase plan created: .planning/phases/XX-name/{phase}-01-PLAN.md If you can't specify Files + Action + Verify + Done, the task is too vague. -**Good TDD task:** -```xml - - Create price calculator with discount rules - src/lib/pricing.ts, src/lib/pricing.test.ts - - Test: calculatePrice applies discounts correctly - Cases: base 100 + 10% off → 90, base 100 + 20% off + $5 coupon → 75 - - Implement calculatePrice(base, discountPercent, couponAmount). Apply percentage first, then flat amount. - npm test -- pricing.test.ts passes - Price calculation handles all discount combinations correctly - -``` +**TDD candidates get dedicated plans.** If "Create price calculator with discount rules" warrants TDD, create a TDD plan for it. See `~/.claude/get-shit-done/references/tdd.md` for TDD plan structure.