@hanzlaa/rcode 2.1.0

package/rihal/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/rihal/references/thinking-models-debug.md

@@ -0,0 +1,126 @@
+# Thinking Models for Debugging
+
+Five systematic debugging models: 5 Whys, differential diagnosis, bisection, hypothesis-driven testing, and recent-changes priority.
+
+---
+
+## 1. Five Whys
+
+**When to apply:** Symptom unclear, need root cause, not just surface fix
+
+**Concrete steps:**
+1. State the symptom: *"Test fails with 'undefined is not a function'"*
+2. Ask why 1: *"Which function is undefined?"* → "fetchUser"
+3. Ask why 2: *"Why is fetchUser undefined?"* → "Import missing"
+4. Ask why 3: *"Why is import missing?"* → "File was deleted, import not updated"
+5. Ask why 4: *"Why wasn't import updated?"* → "Refactoring script incomplete"
+6. Ask why 5: *"Why was refactoring incomplete?"* → "Manual step skipped in checklist"
+
+**Output:** Root cause (process, not code). Fix: update refactoring checklist.
+
+---
+
+## 2. Differential Diagnosis
+
+**When to apply:** Multiple possible causes, uncertain which is real
+
+**Concrete steps:**
+1. List all plausible causes for the bug (e.g., API timeout)
+   - Network outage
+   - Rate limiting
+   - Invalid credentials
+   - Request malformed
+   - Downstream service down
+2. Design a test to eliminate each (in cheap-to-expensive order)
+   - Cheap: Check error message (rate limit? network?)
+   - Medium: Call API directly with curl/Postman
+   - Expensive: Spin up test environment, mock service
+3. Run tests in order, eliminate causes
+4. Surviving cause is likely culprit
+
+**Output:** Diagnosis with high confidence.
+
+---
+
+## 3. Bisection (Binary Search)
+
+**When to apply:** Bug appeared recently, need to find which change broke it
+
+**Concrete steps:**
+1. Identify the "last known good" commit (tests passing)
+2. Identify current commit (tests failing)
+3. Bisect: check the commit halfway between
+   - Does it fail? → Bug is in earlier half. Search lower half next.
+   - Does it pass? → Bug is in later half. Search upper half next.
+4. Repeat until you narrow to 1 commit
+5. Inspect that commit's changes
+
+**Output:** Exact commit that introduced bug. Then inspect diff.
+
+**Example:**
+```
+Last good: abc123 (commit 100)
+Current:   def456 (commit 200)
+Check:     mid789 (commit 150) → FAILS
+Check:     mid234 (commit 125) → PASSES
+Check:     mid567 (commit 137) → FAILS
+Check:     mid890 (commit 131) → PASSES
+Repeat until → found commit 133 introduced bug
+```
+
+---
+
+## 4. Hypothesis-Driven Testing
+
+**When to apply:** Behavior unexpected, need to validate assumptions
+
+**Concrete steps:**
+1. Formulate hypothesis: *"Login fails because JWT expiration is 0"*
+2. Design test that would **falsify** the hypothesis
+   - Test: Log in, inspect JWT, check exp field
+   - If exp field is nonzero → hypothesis false, look elsewhere
+   - If exp field is zero → hypothesis confirmed, fix JWT generation
+3. Run the test; interpret result
+4. Refine hypothesis based on result; loop
+
+**Output:** Validated or falsified hypothesis, narrowed search space.
+
+---
+
+## 5. Recent-Changes Priority
+
+**When to apply:** Bug present but source unknown, no bisect history
+
+**Concrete steps:**
+1. Bugs cluster in recently-changed code (Pareto principle)
+2. List commits from last N days (e.g., 7 days)
+3. For each recent commit, list files changed
+4. Prioritize: files most likely to impact bug symptom
+5. Inspect those files first
+
+**Example:**
+```
+Symptom: Cart disappears after login
+Recent changes (last 5 commits):
+- auth.js (login, JWT) ← likely culprit
+- cart.js (add/remove items) ← possible
+- api.js (endpoints) ← possible
+- style.css (layout) ← unlikely
+- config.yaml (unrelated) ← unlikely
+
+Priority order: auth.js > cart.js > api.js
+```
+
+---
+
+## Integration: Multi-Model Debugging
+
+**When stuck, apply in order:**
+
+1. **Recent-Changes Priority** → Identify suspect files
+2. **Hypothesis-Driven Testing** → Test assumptions about those files
+3. **Differential Diagnosis** → If test inconclusive, list causes and eliminate
+4. **Bisection** → If cause still unclear, find commit that broke it
+5. **Five Whys** → Once found, trace root cause to prevent recurrence
+
+**Outcome:** Fast root-cause diagnosis, preventative fix.

package/rihal/references/thinking-models-planning.md

@@ -0,0 +1,127 @@
+# Thinking Models for Planning
+
+Four mental models for rigorous planning: pre-mortem, MECE decomposition, constraint analysis, and reversibility testing.
+
+---
+
+## 1. Pre-Mortem Analysis
+
+**What it counters:** Optimism bias, overlooked failure modes
+
+**How it works:**
+Imagine the project has failed 6 months from now. Work backward: *What went wrong?*
+
+**Prompt template:**
+```
+Imagine we're in month 6 and {phase} failed catastrophically.
+What is ONE thing that went wrong to cause this failure?
+List 5 plausible failure modes (technical, social, scope).
+For each, describe the early warning sign we missed.
+```
+
+**Planning step:**
+- After drafting SPRINT.md, ask pre-mortem questions
+- Add risk mitigation to Phase {N}
+- Example: *"Failure mode: UI doesn't resize on mobile. Early signal: No responsive testing in Phase 2. Mitigation: Add device testing checkpoint."*
+
+---
+
+## 2. MECE Decomposition
+
+**What it counters:** Gaps, overlaps, incomplete task lists
+
+**How it works:**
+Break work into Mutually Exclusive, Collectively Exhaustive buckets—no overlap, no gaps.
+
+**Prompt template:**
+```
+Decompose {phase_goal} into MECE categories.
+Each task should:
+- Belong to exactly ONE category (no overlap)
+- Contribute to the phase goal (no stragglers)
+- Be independently verifiable
+
+List categories, tasks per category, dependencies.
+```
+
+**Planning step:**
+- Use MECE to structure Phase {N} tasks
+- Verify no task appears twice, no category is empty
+- Example: *"Phase: Build user auth. Categories: (1) Schema design, (2) JWT logic, (3) Route protection, (4) Testing. Zero overlap, complete coverage."*
+
+---
+
+## 3. Constraint Analysis
+
+**What it counters:** Wasted effort on non-binding constraints
+
+**How it works:**
+Identify the ONE binding constraint (the bottleneck limiting progress). Attack it first.
+
+**Prompt template:**
+```
+List all constraints on {phase}:
+- Technical (API limits, performance)
+- Social (team availability, approval)
+- Temporal (deadline, dependencies)
+- Resource (budget, tooling)
+
+Rank by impact: Which constraint, if removed, would accelerate most?
+This is the binding constraint.
+```
+
+**Planning step:**
+- Run constraint analysis before Phase {N}
+- Reorder tasks to address binding constraint first
+- Example: *"Binding: API review (1-week SLA). Move API design to start of Phase 3. Unblock subsequent tasks."*
+
+---
+
+## 4. Reversibility Test
+
+**What it counters:** Irreversible decisions made without sufficient deliberation
+
+**How it works:**
+Classify each decision as one-way door (hard to undo) or two-way door (reversible).
+
+**Prompt template:**
+```
+For each decision in {phase}:
+- Tech stack choice → one-way door (costly to change)
+- Testing strategy → two-way door (can pivot mid-phase)
+
+List one-way decisions. For each, answer:
+- What would I regret if this is wrong?
+- What information would reduce regret?
+- Is delaying decision worth the information gain?
+```
+
+**Planning step:**
+- Flag one-way decisions in SPRINT.md with `[ONE-WAY]` tag
+- For one-way decisions, add deliberation time before Phase {N}
+- Example: *"[ONE-WAY] Framework choice (Next.js vs Remix). Allocate 1 day for prototyping before commit."*
+
+---
+
+## Integration in SPRINT.md
+
+Add a **Planning Context** section:
+
+```markdown
+## Planning Context
+
+### Pre-Mortem
+- Failure mode 1: [mitigation in phase N]
+- Failure mode 2: [mitigation in phase N]
+
+### MECE Structure
+- Category A: [tasks 1–3]
+- Category B: [tasks 4–6]
+- Coverage: ✅ Complete, ✅ Non-overlapping
+
+### Binding Constraint
+- [Constraint name]: addressed in task {N}
+
+### One-Way Decisions
+- [Decision]: Deliberation time allocated in phase {N-1}
+```