@hanzlaa/rcode 2.1.0

package/rihal/agents/rules/planner/common-patterns.md

@@ -0,0 +1,373 @@
+# Common Planning Patterns
+
+Recurring patterns emerge in well-written plans. Use these as templates to speed up your planning and ensure consistency.
+
+---
+
+## Pattern 1: Vertical Slice (Feature Implementation)
+
+**When to use:** Implementing a user-facing feature that touches model, API, and UI.
+
+**Structure:**
+```
+Plan X.1 (Wave 1): Model + Schema
+  - Create database schema
+  - Add validation logic
+  - Write unit tests
+
+Plan X.2 (Wave 1): API Endpoint
+  - Create REST endpoint (POST/GET/PUT/DELETE)
+  - Add error handling
+  - Verify with curl/Postman
+
+Plan X.3 (Wave 2): UI Form/Component
+  - Build React component
+  - Wire to API endpoint
+  - Integration test: form → API → database
+
+Plan X.4 (Wave 3): End-to-End Verification
+  - Test full user flow (UI → API → DB → UI)
+  - Checkpoint: Visual/functional review
+```
+
+**Dependencies:** 1.3 → {1.1, 1.2}, 1.4 → 1.3
+
+**Wave:** 1.1=1, 1.2=1, 1.3=2, 1.4=3
+
+**Key:** Parallelize independent work (model and API can happen together), serialize when one blocks another (UI needs working API).
+
+---
+
+## Pattern 2: Research + Implementation
+
+**When to use:** Work requiring learning before building (new library, unfamiliar pattern, architecture choice).
+
+**Structure:**
+```
+Plan Y.1 (Wave 1): Research/Spike
+  - Evaluate 2-3 options
+  - Build proof-of-concept
+  - Document findings + recommendation
+  - Checkpoint: Approval on chosen approach
+
+Plan Y.2 (Wave 2): Implementation
+  - Build full feature using chosen approach
+  - Integrate with codebase
+  - Tests + documentation
+
+Plan Y.3 (Wave 3): Optimization + Hardening
+  - Performance tuning based on findings
+  - Edge case handling
+  - Final verification
+```
+
+**Dependencies:** 2 → 1, 3 → 2
+
+**Wave:** 1=1, 2=2, 3=3
+
+**Key:** Always wait for research approval before building. Don't implement multiple approaches in parallel.
+
+---
+
+## Pattern 3: Refactoring + Testing
+
+**When to use:** Large refactors where you need to maintain test coverage throughout.
+
+**Structure:**
+```
+Plan Z.1 (Wave 1): Extract Abstractions
+  - Create new abstraction layer
+  - Write unit tests for new layer
+  - Don't change existing code yet
+
+Plan Z.2 (Wave 1): Parallel Migration Tasks
+  - Migrate Component A to use new abstraction
+  - Migrate Component B to use new abstraction
+  - (A and B can run parallel if they don't share files)
+
+Plan Z.3 (Wave 2): Cleanup
+  - Remove old abstraction/code
+  - Update integration tests
+  - Verify no regressions
+```
+
+**Dependencies:** 2 → 1, 3 → 2
+
+**Wave:** 1=1, 2a=1, 2b=1, 3=2
+
+**Key:** Test at every step. Parallelize migrations when they don't overlap. Clean up old code last.
+
+---
+
+## Pattern 4: Bug Fix + Root Cause Prevention
+
+**When to use:** Fixing bugs that expose systemic issues.
+
+**Structure:**
+```
+Plan A.1 (Wave 1): Root Cause Investigation
+  - Debug the symptom
+  - Identify root cause
+  - Checkpoint: Confirm understanding
+
+Plan A.2 (Wave 2): Fix + Add Safeguards
+  - Apply minimal fix to symptom
+  - Add tests to prevent regression
+  - Add validation/guard code to prevent root cause
+
+Plan A.3 (Wave 3): Broader Audit
+  - Search codebase for similar patterns
+  - Apply same fix in 1-2 other places
+  - Verify with tests
+```
+
+**Dependencies:** 2 → 1, 3 → 2
+
+**Wave:** 1=1, 2=2, 3=3
+
+**Key:** Start with minimal fix. Then prevent recurrence. Then look for similar bugs elsewhere.
+
+---
+
+## Pattern 5: Performance Optimization
+
+**When to use:** Addressing bottlenecks (slow queries, rendering, builds, etc.).
+
+**Structure:**
+```
+Plan B.1 (Wave 1): Measure Baseline
+  - Set up profiling/monitoring
+  - Establish baseline metrics
+  - Document bottleneck details
+
+Plan B.2 (Wave 2): Implement Optimization
+  - Try optimization approach A
+  - Measure improvement
+  - Decide: keep, iterate, or discard
+
+Plan B.3 (Wave 3): Validate + Deploy
+  - Performance testing in staging
+  - Compare before/after metrics
+  - Checkpoint: Performance improvement approved
+```
+
+**Dependencies:** 2 → 1, 3 → 2
+
+**Wave:** 1=1, 2=2, 3=3
+
+**Key:** Never optimize without baselines. Measure before/after. Some "optimizations" slow things down.
+
+---
+
+## Pattern 6: Configuration + Rollout
+
+**When to use:** Changes that need careful rollout (feature flags, env configs, rollback plans).
+
+**Structure:**
+```
+Plan C.1 (Wave 1): Feature Flag Infrastructure
+  - Create feature flag or environment variable
+  - Add conditional logic to feature
+  - Set default to OFF (safe default)
+
+Plan C.2 (Wave 2): Testing with Flag OFF
+  - Unit tests with flag disabled
+  - Integration tests with flag disabled
+  - Verify old behavior unchanged
+
+Plan C.3 (Wave 2): Testing with Flag ON
+  - Unit tests with flag enabled
+  - Integration tests with flag enabled
+  - Verify new behavior works
+
+Plan C.4 (Wave 3): Gradual Rollout
+  - Enable for 10% of users
+  - Monitor metrics
+  - Checkpoint: Should we increase rollout?
+  - If yes, increase to 50% → 100%
+  - If no, disable and investigate
+```
+
+**Dependencies:** 2 → 1, 3 → 1, 4 → {2, 3}
+
+**Wave:** 1=1, 2=2, 3=2, 4=3
+
+**Key:** Test both states (on/off). Roll out gradually. Have a disable strategy.
+
+---
+
+## Pattern 7: API Versioning
+
+**When to use:** Making breaking changes to APIs (endpoints, schemas, etc.).
+
+**Structure:**
+```
+Plan D.1 (Wave 1): Design New Version
+  - Document new API spec
+  - Design migration path from v1 to v2
+  - Plan deprecation timeline
+
+Plan D.2 (Wave 2): Implement v2 Endpoint (Parallel with D.3)
+  - Build new v2 endpoint (e.g., /api/v2/users)
+  - Tests for v2
+  - Keep v1 endpoint working
+
+Plan D.3 (Wave 2): Implement Adapter (Parallel with D.2)
+  - Build adapter that translates v2 requests → internal v2 model
+  - Unit tests for adapter
+
+Plan D.4 (Wave 3): Migrate Clients
+  - Update internal clients to use v2
+  - Checkpoint: All internal clients migrated?
+  - Start deprecating v1
+
+Plan D.5 (Wave 4): Cleanup
+  - Remove v1 endpoint
+  - Remove adapter
+  - Final tests
+```
+
+**Dependencies:** 2 → 1, 3 → 1, 4 → {2, 3}, 5 → 4
+
+**Wave:** 1=1, 2=2, 3=2, 4=3, 5=4
+
+**Key:** Build new version alongside old. Migrate clients gradually. Remove old version last.
+
+---
+
+## Pattern 8: Database Schema Migration
+
+**When to use:** Changing database structure with live data.
+
+**Structure:**
+```
+Plan E.1 (Wave 1): Add New Column/Table (Backward Compatible)
+  - Create new column (nullable) or table
+  - Deploy to production (zero downtime)
+  - Application ignores new field initially
+
+Plan E.2 (Wave 2): Backfill Data
+  - Write migration script to populate new column/table
+  - Run on production database
+  - Verify data integrity
+
+Plan E.3 (Wave 3): Update Application Code
+  - Update code to read/write new column/table
+  - Keep reading old column for safety (dual write)
+  - Deploy and monitor
+
+Plan E.4 (Wave 4): Remove Old Column (Cleanup)
+  - Once new column is working, remove old column
+  - Run cleanup migration
+  - Deploy final version
+```
+
+**Dependencies:** 2 → 1, 3 → 2, 4 → 3
+
+**Wave:** 1=1, 2=2, 3=3, 4=4
+
+**Key:** Never lock the database. Deploy schema changes first (backward compatible), then application changes, then cleanup.
+
+---
+
+## Pattern 9: Documentation + Code
+
+**When to use:** Feature where users need docs to understand/use it.
+
+**Structure:**
+```
+Plan F.1 (Wave 1): Implement Feature
+  - Build the feature
+  - Write unit tests
+  - Code review + merge
+
+Plan F.2 (Wave 2): Write Documentation
+  - API documentation (if applicable)
+  - User guide
+  - Examples
+  - Checkpoint: Docs reviewed by user/PO
+
+Plan F.3 (Wave 3): User Testing
+  - Give docs + feature to actual user
+  - Observe if they can use it without help
+  - Update docs based on feedback
+```
+
+**Dependencies:** 2 → 1, 3 → 2
+
+**Wave:** 1=1, 2=2, 3=3
+
+**Key:** Write docs AFTER implementation (you know what you built). Get real user feedback.
+
+---
+
+## Quick Pattern Selector
+
+| Situation | Pattern | Waves |
+|---|---|---|
+| New user-facing feature | Vertical Slice | 3-4 |
+| Need to learn before building | Research + Implementation | 3 |
+| Large refactor | Refactoring + Testing | 2-3 |
+| Fixing bugs | Bug Fix + Prevention | 3 |
+| Slow system | Optimization | 3 |
+| Safe rollout needed | Configuration + Rollout | 3-4 |
+| Breaking API change | API Versioning | 4 |
+| Database change | Schema Migration | 4 |
+| Feature + docs | Documentation + Code | 3 |
+
+---
+
+## Antipattern: Everything in One Task
+
+**Problem:**
+```
+Plan X.1: Implement user authentication
+  - Create schema
+  - Build API endpoint
+  - Build UI form
+  - Test everything
+  - Write docs
+  - Deploy to production
+```
+
+**Why it's wrong:**
+- Task is 3+ days (should be < 60 min)
+- Can't parallelize any work
+- One mistake blocks everything
+- Hard to verify/test incrementally
+
+**Fix:** Split into Vertical Slice pattern (4-5 tasks, waves 1-3, parallelizable).
+
+---
+
+## Antipattern: Excessive Parallelization
+
+**Problem:**
+```
+Plan X.1: Create schema
+Plan X.2: Build endpoint (depends on 1.1)
+Plan X.3: Build form (depends on 1.2)
+Plan X.4: Write tests (depends on 1.3)
+... (10 more sequential tasks)
+wave: 1
+```
+
+**Why it's wrong:**
+- Wave = 1 but tasks are sequential → misleading
+- Waves should increase as dependencies deepen
+- If everything depends on the previous task, only 1 task can run at a time
+
+**Fix:** Calculate waves correctly. If wave=1, tasks should truly be independent.
+
+---
+
+## When Pattern Doesn't Fit
+
+If your work doesn't match any pattern:
+
+1. Break it down into steps
+2. Identify which steps can run in parallel
+3. Create tasks accordingly
+4. Document the rationale in the plan
+
+Novel patterns are fine — just ensure they're still decomposed correctly.

package/rihal/agents/rules/planner/dependency-analysis.md

@@ -0,0 +1,195 @@
+# Dependency Analysis for Task Planning
+
+When building SPRINT.md frontmatter, you must determine dependencies between tasks. This determines **wave assignment** — which tasks can run in parallel and which must run sequentially.
+
+---
+
+## Core Rule: Detect `depends_on` Signals
+
+A task **depends_on** another if:
+
+1. **It reads files the other task creates** — "Task 2 needs the component Task 1 builds"
+2. **It requires a prior checkpoint result** — "This task waits for human approval from the previous step"
+3. **It refines/iterates on the other task's output** — "Task 2 improves the implementation from Task 1"
+4. **It requires setup/initialization from another task** — "Must create database schema before inserting seed data"
+5. **Its verification depends on the other task** — "Can't test integration until both sides are built"
+
+---
+
+## Wave Assignment Algorithm
+
+Use this deterministic rule to calculate waves:
+
+```
+if task.depends_on is empty:
+  task.wave = 1
+else:
+  task.wave = max(wave of all dependencies) + 1
+```
+
+**Example:**
+
+```
+Task 1.1 (no dependencies) → wave 1
+Task 1.2 (no dependencies) → wave 1
+Task 1.3 (depends on 1.1) → wave 2
+Task 1.4 (depends on 1.1 and 1.3) → wave 3 (max of waves 1 and 2 = 2, plus 1 = 3)
+```
+
+---
+
+## File Ownership Rule
+
+Tasks can run in parallel **if and only if** their `files_modified` lists don't overlap.
+
+**Parallel-Safe:**
+```yaml
+task-1:
+  files_modified: [src/api/routes.ts, src/api/middleware.ts]
+task-2:
+  files_modified: [src/ui/Button.tsx, src/ui/Input.tsx]
+→ No overlap, can be parallel
+```
+
+**Not Parallel-Safe:**
+```yaml
+task-1:
+  files_modified: [src/index.ts, src/config.ts]
+task-2:
+  files_modified: [src/index.ts, src/logger.ts]
+→ Both modify src/index.ts, so task-2 must depend_on task-1
+```
+
+---
+
+## Common Dependency Patterns
+
+### Pattern 1: Vertical Slices (PREFER)
+One feature = one task, cutting through model/API/UI.
+
+**Example:** "Add user authentication"
+- Task 1.1: Implement Auth schema + login endpoint
+- Task 1.2: Add login UI form
+- Task 1.3: Wire UI to endpoint + test flow
+
+**Dependency:** 1.2 → 1.1, 1.3 → 1.1+1.2 (API must exist before UI, form must exist before wiring)
+
+**Wave:** 1.1 (wave 1), 1.2 (wave 1), 1.3 (wave 2)
+
+### Pattern 2: Architectural Prerequisites
+Some tasks must complete before others can start.
+
+**Example:** "Add caching layer"
+- Task 2.1: Design cache schema, pick library (Redis vs in-memory)
+- Task 2.2: Implement cache abstraction
+- Task 2.3: Wire cache into data layer
+
+**Dependency:** 2.2 → 2.1, 2.3 → 2.2
+
+**Wave:** 2.1 (wave 1), 2.2 (wave 2), 2.3 (wave 3)
+
+### Pattern 3: Testing Verification
+Tests can run in parallel with implementation, but NOT before it.
+
+**Example:** "Build search feature"
+- Task 3.1: Implement search algorithm
+- Task 3.2: Write integration tests
+- Task 3.3: Benchmark + optimize
+
+**Dependency:** 3.2 → 3.1 (need implementation to test), 3.3 → 3.1+3.2
+
+**Wave:** 3.1 (wave 1), 3.2 (wave 2), 3.3 (wave 3)
+
+---
+
+## Red Flags (Over-Splitting)
+
+If you're creating too many tasks in sequence, you may be over-splitting. Check:
+
+| Red Flag | Why It's Wrong | Fix |
+|---|---|---|
+| **All tasks are wave N+1** | Everything is sequential; no parallelism | Identify truly independent work (UI, API, tests) |
+| **Tasks > 8 with no parallelism** | Likely over-scoped; should merge tasks | Combine tasks that can't run parallel anyway |
+| **Vague `depends_on`** | "Depends on team context" is not a dependency | Name the **specific prior task** |
+
+---
+
+## Documenting Dependencies
+
+In SPRINT.md frontmatter, list ONLY the tasks this plan **directly** depends on:
+
+```yaml
+depends_on: [01, 03]
+```
+
+NOT the transitive dependencies. Wave calculation handles the rest.
+
+Example (WRONG):
+```yaml
+depends_on: [01, 02, 03]  # If 03 depends on 02, don't repeat
+```
+
+Example (RIGHT):
+```yaml
+depends_on: [03]  # Only direct dependencies
+```
+
+---
+
+## Checkpoint Dependencies
+
+A task that requires **human approval** creates a dependency for subsequent tasks.
+
+**Pattern:**
+```
+Task 1.1: Implement feature (auto, no checkpoint)
+Task 1.2: Verify on staging (checkpoint: human-verify)
+Task 1.3: Deploy to production (depends_on: [1.2])
+```
+
+Task 1.3 must wait for 1.2's checkpoint because 1.2's verification result determines whether to proceed.
+
+---
+
+## Gotchas
+
+### Gotcha 1: Implied Dependencies
+**Problem:** You assume a dependency but don't state it.
+
+**Example:** "Task 2 extends Task 1's component"
+- If not in the task description, it's implied
+- Put it in `depends_on` or it may run before 1 completes
+
+**Fix:** Always be explicit. If Task 2 modifies a file Task 1 creates, add `depends_on: [1]`.
+
+### Gotcha 2: Parallel Tasks with Shared Resources
+**Problem:** Two tasks can't modify the same file simultaneously.
+
+**Example:**
+```yaml
+task-1:
+  files_modified: [src/index.ts]
+task-2:
+  files_modified: [src/index.ts]
+```
+
+**Fix:** Make task-2 depend_on task-1, or split the shared file logic.
+
+### Gotcha 3: Build Dependencies vs. Runtime Dependencies
+**Problem:** Confusing "needs at build time" with "needs at runtime".
+
+**Example:** Component A uses library X at runtime. Task 1 creates A, Task 2 installs X. Does Task 1 depend_on Task 2?
+
+**Answer:** Only if you need to test/verify A immediately. If Task 2 installs X later, no dependency needed.
+
+---
+
+## Verification Checklist
+
+Before submitting SPRINT.md, verify:
+
+- [ ] Each `depends_on` list is explicit and specific (not transitive)
+- [ ] Wave assignment follows the algorithm (wave = max(dependencies) + 1)
+- [ ] No `files_modified` overlap between parallel tasks
+- [ ] Every checkpoint task has explicit `depends_on` from following tasks
+- [ ] Total wave count is reasonable (< 5 waves for most plans)