@hanzlaa/rcode 2.1.0

package/rihal/agents/rules/planner/goal-backward-thinking.md

@@ -0,0 +1,220 @@
+# Rihal Planner: Goal-Backward Thinking Methodology
+
+## The Process: Goal-Backward Derivation
+
+Goal-backward planning starts from "what must be TRUE" and derives tasks backward to make it true.
+
+---
+
+## Step 1: State the Goal
+
+Take the phase goal from ROADMAP.md. Must be outcome-shaped, not task-shaped.
+
+**Good goals (outcomes):**
+- "Working chat interface"
+- "Users can authenticate with email or OAuth"
+- "Payment system accepts and processes Stripe charges"
+
+**Bad goals (tasks):**
+- "Build chat components"
+- "Implement authentication"
+- "Integrate Stripe"
+
+---
+
+## Step 2: Derive Observable Truths
+
+"What must be TRUE for this goal to be achieved?" List 3-7 truths from USER's perspective (not developer perspective).
+
+**Example: Chat Interface Goal**
+
+Must be TRUE:
+- User can see existing messages
+- User can type a new message
+- User can send the message
+- Sent message appears in the list immediately
+- Messages persist across page refresh
+- User cannot see messages from other users
+
+**Test:** Each truth verifiable by a human using the application without reading code.
+
+---
+
+## Step 3: Derive Required Artifacts
+
+For each truth: "What must EXIST for this to be true?"
+
+**Example: "User can see existing messages"**
+
+Requires:
+- Message list component (renders Message[])
+- Messages state (loaded from somewhere)
+- API route or data source (provides messages)
+- Message type definition (shapes the data)
+- Database table (Message model)
+
+**Test:** Each artifact = a specific file or database object, not abstract.
+
+---
+
+## Step 4: Derive Required Wiring
+
+For each artifact: "What must be CONNECTED for this to function?"
+
+**Example: Message list component wiring**
+
+- Imports Message type (not using `any`)
+- Receives messages prop or fetches from API
+- Maps over messages to render (not hardcoded)
+- Handles empty state (doesn't crash)
+- Passes correct data shape to component
+
+---
+
+## Step 5: Identify Key Links (Breakage Points)
+
+"Where is this most likely to break?" Key links = critical connections where breakage causes cascading failures.
+
+**Example: Chat Interface**
+
+- Input onSubmit → API call → if broken: typing works but sending doesn't
+- API save → database → if broken: appears to send but doesn't persist
+- Component → real data source → if broken: shows placeholder, not messages
+
+---
+
+## Must-Haves Output Format
+
+```yaml
+must_haves:
+  truths:
+    - "User can see existing messages"
+    - "User can send a message"
+    - "Messages persist across refresh"
+  artifacts:
+    - path: "src/components/Chat.tsx"
+      provides: "Message list rendering"
+      min_lines: 30
+    - path: "src/app/api/chat/route.ts"
+      provides: "Message CRUD operations"
+      exports: ["GET", "POST"]
+    - path: "prisma/schema.prisma"
+      provides: "Message model"
+      contains: "model Message"
+  key_links:
+    - from: "src/components/Chat.tsx"
+      to: "/api/chat"
+      via: "fetch in useEffect"
+      pattern: "fetch.*api/chat"
+    - from: "src/app/api/chat/route.ts"
+      to: "prisma.message"
+      via: "database query"
+      pattern: "prisma\\.message\\.(find|create)"
+```
+
+---
+
+## Common Failures in Goal-Backward Thinking
+
+### Truths Too Vague
+**Bad:** "User can use chat"
+**Good:** "User can see messages", "User can send message", "Messages persist"
+
+### Artifacts Too Abstract
+**Bad:** "Chat system", "Auth module"
+**Good:** "src/components/Chat.tsx", "src/app/api/auth/login/route.ts", "prisma/schema.prisma"
+
+### Missing Wiring
+**Bad:** Listing components without how they connect
+**Good:** "Chat.tsx fetches from /api/chat via useEffect on mount"
+
+### Truths Not Verifiable by User
+**Bad:** "System is fault-tolerant"
+**Good:** "User can send message even if network hiccups once"
+
+---
+
+## Why Goal-Backward Works
+
+**Forward planning:** "What should we build?" → produces biased, incomplete task lists
+- Risk: Include nice-to-have features that don't matter
+- Risk: Forget critical pieces
+- Result: Tasks that don't achieve goal
+
+**Goal-backward planning:** "What must be TRUE?" → produces complete task lists
+- Starts from user experience, not developer wishlist
+- Ensures nothing critical is forgotten
+- Tasks directly map to user-observable outcomes
+
+---
+
+## Example: Authentication Feature
+
+### Goal
+"Users can securely sign up, log in, and stay logged in"
+
+### Truths (User perspective)
+1. User can enter email and password on login page
+2. Invalid credentials show error message
+3. Valid credentials log user in
+4. User sees personalized dashboard after login
+5. User stays logged in after page refresh
+6. User can log out
+7. User can't access protected pages without logging in
+
+### Artifacts Needed
+- Login form component
+- Registration form component
+- Auth API routes (login, register, logout, refresh)
+- User database model
+- Session/JWT infrastructure
+- Protected route wrapper
+
+### Wiring
+- Form → API endpoint
+- API endpoint → database validation
+- Database → JWT token generation
+- Token → session management
+- Protected routes → auth check
+
+### Key Links (Where It Breaks)
+- Form submission to API: if broken, nothing gets sent
+- API to database: if broken, can't validate credentials
+- Token generation: if broken, can't stay logged in
+- Protected route check: if broken, unauthorized users access pages
+
+---
+
+## Using Must-Haves in Plans
+
+When creating tasks in SPRINT.md, reference must-haves:
+
+```xml
+<task type="auto">
+  <name>Task: Create Message model</name>
+  <files>prisma/schema.prisma</files>
+  <action>Add Message model per must_haves.artifacts (provides Message model). Fields: id, content, authorId, createdAt.</action>
+  <done>Message model created in schema, matches must_haves spec</done>
+</task>
+
+<task type="auto">
+  <name>Task: Create Chat API route</name>
+  <files>src/app/api/chat/route.ts</files>
+  <action>Create GET and POST per must_haves.artifacts (exports ["GET", "POST"]). GET returns all messages. POST creates new message.</action>
+  <done>Both methods implemented, types exported correctly</done>
+</task>
+```
+
+Each task directly satisfies an artifact requirement from must-haves.
+
+---
+
+## Validation Checklist
+
+Before finalizing plan:
+- [ ] Every truth has an artifact that makes it true
+- [ ] Every artifact has a file assigned
+- [ ] Every artifact maps to at least one task
+- [ ] Key links identify where breakage matters most
+- [ ] Tasks reference must-haves artifacts
+- [ ] No task is missing from must-haves coverage

package/rihal/agents/rules/planner/sprint-verification.md

@@ -0,0 +1,202 @@
+# Plan Verification Checklist
+
+Before outputting a SPRINT.md file, run this self-check to catch common planning errors. This is the planner's **"did I build this right?"** validation.
+
+---
+
+## Pre-Output Verification
+
+### Frontmatter Completeness
+
+- [ ] `phase:` — Filled with actual phase name (not "XX-name")
+- [ ] `plan:` — Filled with plan number (NN)
+- [ ] `type:` — Is either "execute" or "tdd" (not both, not neither)
+- [ ] `wave:` — Set correctly (calculated from max depends_on + 1)
+- [ ] `depends_on:` — Lists only directly-dependent plan IDs, or empty if none
+- [ ] `files_modified:` — Lists all files any task will touch
+- [ ] `autonomous:` — Is `true` if no checkpoints, `false` if has checkpoints
+- [ ] `requirements:` — NOT EMPTY (must list REQ-IDs from ROADMAP)
+- [ ] `must_haves:` — Has 2+ truths, 2+ artifacts, 2+ key_links
+
+### Task Structure
+
+- [ ] Each task has `<action>` section (not just description)
+- [ ] Each `<action>` includes "what to avoid & WHY"
+- [ ] Each task has `<verify>` with automated command (< 60 sec)
+- [ ] Each task has `<done>` with measurable acceptance criteria
+- [ ] No task is < 15 min or > 60 min (combine or split if needed)
+- [ ] Task IDs follow hierarchical format: `### Task {plan-id}.{NN}`
+
+### Dependency Validation
+
+- [ ] Wave calculation is correct (`max(dep_waves) + 1`)
+- [ ] No file ownership overlap between parallel tasks
+- [ ] Every checkpoint task has explicit `depends_on` from followers
+- [ ] No circular dependencies (Task A depends on B, B depends on A)
+
+### Content Quality
+
+- [ ] Locked decisions (D-01, D-02, etc.) appear in at least one task
+- [ ] No vague task descriptions ("Add authentication" → specific endpoint name + method)
+- [ ] No references to files that don't exist
+- [ ] Every task references concrete, existing file paths
+- [ ] Context bloat < 50% (if context section > 300 lines, trim it)
+
+### Objective & Output
+
+- [ ] `<objective>` clearly states what the plan accomplishes
+- [ ] `<objective>` includes "Purpose:" explaining why
+- [ ] `<objective>` includes "Output:" listing artifacts created
+- [ ] `<output>` section specifies exact SUMMARY.md filename and location
+
+---
+
+## Common Errors to Catch
+
+### Error 1: Empty Requirements
+
+**Symptom:**
+```yaml
+requirements: []
+```
+
+**Why It's Wrong:** Every plan must address ≥1 requirement from ROADMAP. Empty requirements = you didn't tie work to actual goals.
+
+**Fix:** Read ROADMAP, identify which REQ-IDs this plan fulfills, list them.
+
+### Error 2: Vague Task Descriptions
+
+**Symptom:**
+```
+### Task 01.1 — Add authentication
+
+Implement user authentication.
+```
+
+**Why It's Wrong:** "Add authentication" could mean OAuth, JWT, session-based, etc. Executor doesn't know what to build.
+
+**Fix:**
+```
+### Task 01.1 — Implement JWT-based login endpoint
+
+Create POST /api/auth/login that accepts email+password, validates against db,
+returns 15-min access token + 7-day refresh token (stored as HttpOnly cookie).
+```
+
+### Error 3: Missing Verify Command
+
+**Symptom:**
+```
+<verify>
+Run manual tests to check if login works
+</verify>
+```
+
+**Why It's Wrong:** "Manual tests" is not automatable and exceeds Nyquist Rule (60 sec max).
+
+**Fix:**
+```
+<verify>
+npm run test -- --testPathPattern="auth.test.js"
+# Must pass all login endpoint tests in < 30 sec
+</verify>
+```
+
+### Error 4: Parallel Tasks with Overlapping Files
+
+**Symptom:**
+```yaml
+plan: 01
+
+task-1:
+  files_modified: [src/index.ts, src/config.ts]
+
+task-2:
+  files_modified: [src/index.ts, src/api.ts]
+
+wave: 1
+```
+
+**Why It's Wrong:** Both tasks modify `src/index.ts`. If they run in parallel, one will overwrite the other's changes.
+
+**Fix:** Add `depends_on: [01.1]` to Task 1.2, increasing its wave to 2.
+
+### Error 5: Circular Dependencies
+
+**Symptom:**
+```
+Task 1.1 depends_on: [1.3]
+Task 1.3 depends_on: [1.1]
+```
+
+**Why It's Wrong:** Neither can start if both are waiting on the other.
+
+**Fix:** Identify the true dependency direction. Usually one is misidentified.
+
+### Error 6: Context Bloat
+
+**Symptom:**
+```
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/STATE.md
+@.planning/phases/01-research/SUMMARY.md
+@.planning/phases/01-research/01-research-01-SUMMARY.md
+@.planning/phases/02-design/SUMMARY.md
+@.planning/phases/02-design/02-design-01-SUMMARY.md
+... (20 more lines)
+</context>
+```
+
+**Why It's Wrong:** Context > 50% = cognitive overload. Executor spends time reading, not planning.
+
+**Fix:** Include only **genuinely needed** references. Trim to 2-3 SUMMARY files from prior phases.
+
+---
+
+## Self-Check Questions
+
+Before finalizing, ask yourself:
+
+1. **Could a different agent execute this?** If you replaced yourself with another LLM, would they understand exactly what to build?
+2. **Are all decisions locked?** Or are there ambiguities the executor must resolve?
+3. **Is the scope right for a single plan?** Or does this feel like 2-3 plans forced into one?
+4. **Did I reference decisions from CONTEXT.md?** Or am I ignoring user constraints?
+5. **Can I explain this plan to a junior dev in 2 minutes?** If not, it's too complex.
+
+---
+
+## Fast Verification Script
+
+Use this to spot-check SPRINT.md files locally:
+
+```bash
+# Check for empty fields
+grep -E "^(requirements|files_modified):\s*\[\s*\]" SPRINT.md && echo "ERROR: Empty array found"
+
+# Check for vague action descriptions
+grep -E "^\s+<action>\s*$" SPRINT.md | head -1 && echo "WARNING: Action section may be empty"
+
+# Count verify commands
+grep -c "<verify>" SPRINT.md  # Should equal task count
+
+# Check wave calculation
+grep "wave:" SPRINT.md
+```
+
+---
+
+## When to Reject & Replan
+
+If you catch **any** of these, reject the SPRINT.md and replan:
+
+- [ ] Empty `requirements` field
+- [ ] Circular dependencies
+- [ ] Task with no `<verify>` command
+- [ ] Task < 15 min or > 60 min
+- [ ] File ownership overlap in same wave
+- [ ] Context > 1000 lines
+- [ ] Wave count > 5 (likely over-split)
+
+Otherwise, output the SPRINT.md with confidence.