@sienklogic/plan-build-run 2.21.1 → 2.21.2

package/plugins/pbr/references/tdd.md

@@ -0,0 +1,263 @@
+<overview>
+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.
+</overview>
+
+<when_to_use_tdd>
+## When TDD Improves Quality
+
+**TDD candidates (create a TDD plan):**
+- Business logic with defined inputs/outputs
+- API endpoints with request/response contracts
+- Data transformations, parsing, formatting
+- Validation rules and constraints
+- Algorithms with testable behavior
+- State machines and workflows
+- Utility functions with clear specifications
+
+**Skip TDD (use standard plan with `type="auto"` tasks):**
+- UI layout, styling, visual components
+- Configuration changes
+- Glue code connecting existing components
+- One-off scripts and migrations
+- Simple CRUD with no business logic
+- Exploratory prototyping
+
+**Heuristic:** Can you write `expect(fn(input)).toBe(output)` before writing `fn`?
+→ Yes: Create a TDD plan
+→ No: Use standard plan, add tests after if needed
+</when_to_use_tdd>
+
+<tdd_plan_structure>
+## TDD Plan Structure
+
+Each TDD plan implements **one feature** through the full RED-GREEN-REFACTOR cycle.
+
+```markdown
+---
+phase: XX-name
+plan: NN
+type: tdd
+---
+
+<objective>
+[What feature and why]
+Purpose: [Design benefit of TDD for this feature]
+Output: [Working, tested feature]
+</objective>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@relevant/source/files.ts
+</context>
+
+<feature>
+  <name>[Feature name]</name>
+  <files>[source file, test file]</files>
+  <behavior>
+    [Expected behavior in testable terms]
+    Cases: input → expected output
+  </behavior>
+  <implementation>[How to implement once tests pass]</implementation>
+</feature>
+
+<verification>
+[Test command that proves feature works]
+</verification>
+
+<success_criteria>
+- Failing test written and committed
+- Implementation passes test
+- Refactor complete (if needed)
+- All 2-3 commits present
+</success_criteria>
+
+<output>
+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
+</output>
+```
+
+**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.
+</tdd_plan_structure>
+
+<execution_flow>
+## Red-Green-Refactor Cycle
+
+**RED - Write failing test:**
+1. Create test file following project conventions
+2. Write test describing expected behavior (from `<behavior>` element)
+3. Run test - it MUST fail
+4. If test passes: feature exists or test is wrong. Investigate.
+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({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({phase}-{plan}): clean up [feature]`
+
+**Result:** Each TDD plan produces 2-3 atomic commits.
+</execution_flow>
+
+<test_quality>
+## Good Tests vs Bad Tests
+
+**Test behavior, not implementation:**
+- Good: "returns formatted date string"
+- Bad: "calls formatDate helper with correct params"
+- Tests should survive refactors
+
+**One concept per test:**
+- Good: Separate tests for valid input, empty input, malformed input
+- Bad: Single test checking all edge cases with multiple assertions
+
+**Descriptive names:**
+- Good: "should reject empty email", "returns null for invalid ID"
+- Bad: "test1", "handles error", "works correctly"
+
+**No implementation details:**
+- Good: Test public API, observable behavior
+- Bad: Mock internals, test private methods, assert on internal state
+</test_quality>
+
+<framework_setup>
+## Test Framework Setup (If None Exists)
+
+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
+# JavaScript/TypeScript
+if [ -f package.json ]; then echo "node"; fi
+
+# Python
+if [ -f requirements.txt ] || [ -f pyproject.toml ]; then echo "python"; fi
+
+# Go
+if [ -f go.mod ]; then echo "go"; fi
+
+# Rust
+if [ -f Cargo.toml ]; then echo "rust"; fi
+```
+
+**2. Install minimal framework:**
+| Project | Framework | Install |
+|---------|-----------|---------|
+| Node.js | Jest | `npm install -D jest @types/jest ts-jest` |
+| Node.js (Vite) | Vitest | `npm install -D vitest` |
+| Python | pytest | `pip install pytest` |
+| Go | testing | Built-in |
+| Rust | cargo test | Built-in |
+
+**3. Create config if needed:**
+- Jest: `jest.config.js` with ts-jest preset
+- Vitest: `vitest.config.ts` with test globals
+- pytest: `pytest.ini` or `pyproject.toml` section
+
+**4. Verify setup:**
+```bash
+# Run empty test suite - should pass with 0 tests
+npm test  # Node
+pytest    # Python
+go test ./...  # Go
+cargo test    # Rust
+```
+
+**5. Create first test file:**
+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.
+</framework_setup>
+
+<error_handling>
+## Error Handling
+
+**Test doesn't fail in RED phase:**
+- Feature may already exist - investigate
+- Test may be wrong (not testing what you think)
+- Fix before proceeding
+
+**Test doesn't pass in GREEN phase:**
+- Debug implementation
+- Don't skip to refactor
+- Keep iterating until green
+
+**Tests fail in REFACTOR phase:**
+- Undo refactor
+- Commit was premature
+- Refactor in smaller steps
+
+**Unrelated tests break:**
+- Stop and investigate
+- May indicate coupling issue
+- Fix before proceeding
+</error_handling>
+
+<commit_pattern>
+## Commit Pattern for TDD Plans
+
+TDD plans produce 2-3 atomic commits (one per phase):
+
+```
+test(08-02): add failing test for email validation
+
+- Tests valid email formats accepted
+- Tests invalid formats rejected
+- Tests empty input handling
+
+feat(08-02): implement email validation
+
+- Regex pattern matches RFC 5322
+- Returns boolean for validity
+- Handles edge cases (empty, null)
+
+refactor(08-02): extract regex to constant (optional)
+
+- Moved pattern to EMAIL_REGEX constant
+- No behavior changes
+- Tests still pass
+```
+
+**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
+- Clear history showing TDD discipline
+- Consistent with overall commit strategy
+</commit_pattern>
+
+<context_budget>
+## 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.
+</context_budget>

package/plugins/pbr/references/thinking-models-planning.md

@@ -0,0 +1,47 @@
+# Thinking Models: Planning Cluster
+
+Structured reasoning models for the **planner** and **roadmapper** agents. Apply these at decision points during plan creation, not continuously. Each model counters a specific documented failure mode.
+
+Source: Curated from [thinking-partner](https://github.com/mattnowdev/thinking-partner) model catalog (150+ models). Selected for direct applicability to PBR planning workflow.
+
+## 1. Pre-Mortem Analysis
+
+**Counters:** Optimistic plan decomposition that ignores failure modes.
+
+Before finalizing this plan, assume it has already failed. List the 3 most likely reasons for failure -- missing dependency, wrong decomposition, underestimated complexity -- and add mitigation steps or acceptance criteria that would catch each failure early.
+
+## 2. MECE Decomposition
+
+**Counters:** Overlapping tasks (merge conflicts) or gapped tasks (missing requirements).
+
+Verify this task breakdown is MECE at the REQUIREMENT level: (1) list every requirement from the phase goal, (2) confirm each maps to exactly one task's `<done>`, (3) if two tasks modify the same file, confirm they modify DIFFERENT sections or serve DIFFERENT requirements, (4) flag any requirement not covered by any task.
+
+## 3. Constraint Analysis
+
+**Counters:** Deferring the hardest constraint to the last task, causing late-stage failures.
+
+Identify the single hardest constraint in this phase -- the one thing that, if it doesn't work, makes everything else irrelevant. Schedule that constraint as Task 1 or 2, not last. If the constraint involves an external API or unfamiliar library, add a spike/proof-of-concept task before the main implementation.
+
+## 4. Reversibility Test
+
+**Counters:** Over-analyzing cheap decisions, under-analyzing costly ones.
+
+For each significant decision in this plan, classify as REVERSIBLE (can change later with low cost) or IRREVERSIBLE (changing later requires migration, breaking changes, or significant rework). Spend analysis time proportional to irreversibility. For irreversible decisions, document the rationale in the plan.
+
+## 5. Curse of Knowledge Counter
+
+**Counters:** Plan-to-executor ambiguity from compressed instructions.
+
+For each `<action>` step, re-read it as if you have NEVER seen this codebase. Is every noun unambiguous (which file? which function? which endpoint?)? Is every verb specific (add WHERE? modify HOW?)? If a step could be interpreted two ways, rewrite it. Include file paths, function names, and expected behavior in every action step.
+
+## 6. Base Rate Neglect Counter
+
+**Counters:** Planners ignoring low-confidence research caveats.
+
+Before finalizing the plan, read ALL `[NEEDS DECISION]` items and LOW-confidence recommendations from SUMMARY.md. For each: either (a) create a `checkpoint:decision` task to resolve it, or (b) document why the risk is acceptable in the plan's deviation notes. LOW-confidence items that are silently accepted become undocumented technical debt.
+
+## Gap Closure Mode: Root-Cause Check
+
+**Applies only when:** Planner enters gap closure mode (triggered by `gaps_found` in VERIFICATION.md).
+
+Before writing the fix plan, apply a single "why" round: Why did this gap occur? Was it a plan deficiency (wrong task), an execution miss (correct task, wrong implementation), or a changed assumption (environment/dependency shift)? The fix plan must target the root cause category, not just the symptom.

package/plugins/pbr/references/thinking-models-verification.md

@@ -0,0 +1,44 @@
+# Thinking Models: Verification Cluster
+
+Structured reasoning models for the **verifier** and **plan-checker** agents. Apply these during verification passes, not continuously. Each model counters a specific documented failure mode.
+
+Source: Curated from [thinking-partner](https://github.com/mattnowdev/thinking-partner) model catalog (150+ models). Selected for direct applicability to PBR verification workflow.
+
+## Sequencing Rule
+
+**Inversion** and **Confirmation Bias Counter** both look for failures but serve different purposes. Run them in sequence:
+
+1. **Inversion FIRST** (brainstorm): generate 3 ways this could be wrong
+2. **Confirmation Bias Counter SECOND** (structured check): find one partial requirement, one misleading test, one uncovered error path
+
+Inversion generates the list; Confirmation Bias Counter is the discipline to verify items on it.
+
+## 1. Inversion
+
+**Counters:** Verifiers confirming success rather than finding failures.
+
+Instead of checking what IS correct, list 3 specific ways this implementation could be WRONG despite passing tests: missing edge cases, silent data loss, race conditions, unhandled error paths. For each, write a concrete check (grep for pattern, test with specific input, verify error handling exists). Additionally, check whether any documented DEVIATION in SUMMARY.md changes the meaning or applicability of a must-have. If a must-have was written assuming approach A but the executor used approach B, the must-have may need reinterpretation, not literal checking.
+
+## 2. Chesterton's Fence
+
+**Counters:** Flagging purposeful code as dead or unnecessary.
+
+Before flagging any existing code as dead, redundant, or overcomplicated, determine WHY it was written that way. Check git blame, comments, test cases, and the PLAN.md that created it. If the reason is unclear, flag as "purpose unknown -- recommend keeping with WARNING, not removing" and include the git blame hash for the commit that introduced it.
+
+## 3. Confirmation Bias Counter
+
+**Counters:** Verifiers primed by SUMMARY.md claims to see success.
+
+After your initial verification pass, do a DISCONFIRMATION pass: (1) find one requirement that is only partially met, (2) find one test that passes but does not actually test the stated behavior, (3) find one error path that has no test coverage. Report these even if overall verification passes.
+
+## 4. Planning Fallacy Calibration
+
+**Counters:** Accepting over-scoped plans as reasonable (plan-checker).
+
+For each task estimated as "simple" or "small", check: does it touch more than 2 files? Does it require understanding an unfamiliar API? Does it modify shared infrastructure? If yes to any, flag as likely underestimated. Plans with >5 tasks or tasks touching >4 files per task are over-scoped.
+
+## 5. Counterfactual Thinking
+
+**Counters:** Plans that assume success at every step with no error recovery (plan-checker).
+
+For each plan, ask: "What would happen if the executor followed this plan EXACTLY as written but encountered a common failure: dependency version mismatch, API returning unexpected format, file already modified by prior plan?" If the plan has no contingency path and the `<action>` steps assume success at every point, flag as WARNING: "No error recovery path for task T{n}."