@hanzlaa/rcode 3.6.15 → 4.0.0

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

@@ -0,0 +1,220 @@
+# rcode 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/rcode/agents/rules/planner/task-templates.md

@@ -0,0 +1,296 @@
+# rcode Planner: Task Templates by Type
+
+## Standard Task Template
+
+```xml
+<task type="auto">
+  <name>Task: [Action-oriented name]</name>
+  <files>path/to/file.ext, path/to/another.ts</files>
+  <action>[Specific implementation with what to avoid and WHY]</action>
+  <verify>
+    <automated>npm test -- --filter=feature_name</automated>
+  </verify>
+  <done>[Measurable acceptance criteria]</done>
+</task>
+```
+
+---
+
+## TDD Task Template
+
+Use when you can write `expect(fn(input)).toBe(output)` before implementing.
+
+```xml
+<task type="auto" tdd="true">
+  <name>Task: [name]</name>
+  <files>src/feature.ts, src/feature.test.ts</files>
+  <behavior>
+    - Test 1: [expected behavior]
+    - Test 2: [edge case]
+    - Test 3: [error case]
+  </behavior>
+  <action>[Implementation after RED phase]</action>
+  <verify>
+    <automated>npm test -- --filter=feature</automated>
+  </verify>
+  <done>[All tests passing, implementation matches behavior spec]</done>
+</task>
+```
+
+---
+
+## Checkpoint: Human Verify Template
+
+Use for visual/functional verification (90% of checkpoints).
+
+```xml
+<task type="checkpoint:human-verify" gate="blocking">
+  <name>Verify: [Feature name works]</name>
+  <what-built>[What the agent automated]</what-built>
+  <how-to-verify>
+    1. Navigate to http://localhost:3000/login
+    2. Enter email "test@example.com" and password "Test123!"
+    3. Verify you see the dashboard with your name
+    4. Refresh the page
+    5. Verify you're still logged in (not redirected to login)
+  </how-to-verify>
+  <resume-signal>Type "approved" if all steps work, or describe issues</resume-signal>
+</task>
+```
+
+---
+
+## Checkpoint: Decision Template
+
+Use for implementation choices (9% of checkpoints).
+
+```xml
+<task type="checkpoint:decision" gate="blocking">
+  <name>Decide: Database schema for messages</name>
+  <what-youre-deciding>
+    Where to store user-to-message relationships:
+    
+    Option A: Single `messages` table with `userId` foreign key
+    - Pros: Simple, normalized
+    - Cons: Requires join for user info
+    
+    Option B: Embed user data in `messages` (denormalized)
+    - Pros: Faster queries, less joins
+    - Cons: Inconsistent if user updates name
+  </what-youre-deciding>
+  <what-matters>
+    - Message queries run frequently (critical performance)
+    - User names rarely change
+    - Query response time target: <100ms
+  </what-matters>
+  <resume-signal>Reply with "Option A" or "Option B", we'll implement that schema</resume-signal>
+</task>
+```
+
+---
+
+## Checkpoint: Human Action Template
+
+Use for unavoidable manual steps (1% of checkpoints).
+
+```xml
+<task type="checkpoint:human-action" gate="blocking">
+  <name>Set up Stripe API key</name>
+  <what-needed>
+    The next task implements Stripe payment processing, which requires your API key.
+  </what-needed>
+  <steps>
+    1. Visit https://dashboard.stripe.com
+    2. Go to Developers → API Keys
+    3. Copy the **Secret Key** (not the publishable key!)
+    4. Set in your environment: export STRIPE_SECRET_KEY=sk_live_...
+    5. Confirm below when ready
+  </steps>
+  <resume-signal>Reply "ready" when STRIPE_SECRET_KEY is set in your environment</resume-signal>
+</task>
+```
+
+---
+
+## Database Migration Task Template
+
+```xml
+<task type="auto">
+  <name>Task: Add role field to users table</name>
+  <files>prisma/schema.prisma, prisma/migrations/[timestamp]_add_role.sql</files>
+  <action>
+    1. Update User model in schema: add `role String @default("user")`
+    2. Run `prisma migrate dev --name add_role`
+    3. Verify migration file created in prisma/migrations/
+    4. Do NOT manually edit migration file
+  </action>
+  <verify>
+    <automated>prisma db push --skip-generate</automated>
+  </verify>
+  <done>Schema updated, migration created, database reflects new field</done>
+</task>
+```
+
+---
+
+## API Endpoint Task Template
+
+```xml
+<task type="auto">
+  <name>Task: Implement POST /api/users endpoint</name>
+  <files>src/app/api/users/route.ts, src/types/user.ts</files>
+  <action>
+    Create POST endpoint accepting { email, password, name }:
+    1. Validate email format with regex (RFC 5322 subset)
+    2. Validate password length >= 8 chars
+    3. Validate name length 2-50 chars
+    4. Hash password with bcryptjs (not plaintext!)
+    5. Create user in database
+    6. Return 201 with user object (exclude password)
+    7. Return 400 for validation errors
+    8. Return 409 if email already exists
+  </action>
+  <verify>
+    <automated>npm test -- --filter=users-api</automated>
+  </verify>
+  <done>
+    Valid data returns 201 + user object
+    Invalid data returns 400 with error message
+    Duplicate email returns 409
+    Password never returned in response
+  </done>
+</task>
+```
+
+---
+
+## UI Component Task Template
+
+```xml
+<task type="auto">
+  <name>Task: Create LoginForm component</name>
+  <files>src/components/LoginForm.tsx, src/components/LoginForm.test.tsx</files>
+  <action>
+    Create form component with:
+    1. Email input field (required, type="email")
+    2. Password input field (required, type="password")
+    3. Login button (disabled while submitting)
+    4. Error message display (if submission fails)
+    5. Success behavior: call onSubmit({ email, password })
+    6. Use Sonner toast on error (not alert())
+    7. Disabled state during submission (no double-click)
+  </action>
+  <verify>
+    <automated>npm test -- --filter=LoginForm</automated>
+  </verify>
+  <done>
+    Component renders, accepts input, calls onSubmit, disables during submission,
+    shows errors with toast notification
+  </done>
+</task>
+```
+
+---
+
+## Configuration Task Template
+
+```xml
+<task type="auto">
+  <name>Task: Configure environment variables</name>
+  <files>.env.example, .env.local (local only)</files>
+  <action>
+    1. Create .env.example with template (no real values):
+       DATABASE_URL=postgresql://user:pass@localhost:5432/mydb
+       JWT_SECRET=your-secret-key-here
+       STRIPE_SECRET_KEY=sk_test_...
+    2. Create .env.local in dev environment with real values
+    3. Add .env.local to .gitignore (never commit secrets)
+    4. Document each var: purpose, where to get it, format
+  </action>
+  <verify>
+    <automated>test -f .env.example && grep -q DATABASE_URL .env.example</automated>
+  </verify>
+  <done>.env.example exists with all required variables documented, .env.local ignored</done>
+</task>
+```
+
+---
+
+## Documentation Task Template
+
+```xml
+<task type="auto">
+  <name>Task: Document authentication flow</name>
+  <files>docs/AUTHENTICATION.md</files>
+  <action>
+    Document in docs/AUTHENTICATION.md:
+    1. Overview: How auth works (JWT with refresh tokens)
+    2. User flow: Registration → Login → Access token → Refresh → Logout
+    3. Developer reference: Endpoints, request/response shapes, errors
+    4. Diagrams: ASCII or Mermaid sequence diagram
+    5. Examples: cURL commands for each endpoint
+  </action>
+  <verify>
+    <automated>test -f docs/AUTHENTICATION.md && grep -q "POST /api/auth/login" docs/AUTHENTICATION.md</automated>
+  </verify>
+  <done>Documentation complete, all endpoints documented, examples provided</done>
+</task>
+```
+
+---
+
+## Refactoring Task Template
+
+```xml
+<task type="auto">
+  <name>Task: Extract auth validation to utility</name>
+  <files>src/lib/auth-validation.ts, src/api/auth/login/route.ts</files>
+  <action>
+    1. Create src/lib/auth-validation.ts with functions:
+       - validateEmail(email: string): boolean
+       - validatePassword(password: string): boolean
+       - validateUserInput(email, password): { valid: boolean, errors: string[] }
+    2. Update src/api/auth/login/route.ts to use validators
+    3. Keep behavior identical (no refactoring the logic itself)
+    4. All tests must still pass
+  </action>
+  <verify>
+    <automated>npm test && npm run type-check</automated>
+  </verify>
+  <done>Utilities created, API route refactored, all tests passing</done>
+</task>
+```
+
+---
+
+## Common Task Sizing Rules
+
+| Duration | Action | Example |
+|----------|--------|---------|
+| < 15 min | TOO SMALL — combine with related task | "Add email field to form" + "Update User model" |
+| 15-60 min | RIGHT SIZE | "Create User API endpoint with validation" |
+| > 60 min | TOO LARGE — split | "Build complete auth system" → split into 3 tasks |
+
+---
+
+## Task Specificity Checker
+
+**Test:** Could a different executor implement this without asking clarifying questions?
+
+**Bad (too vague):**
+```xml
+<action>Add authentication</action>
+```
+
+**Good (specific):**
+```xml
+<action>
+  Create POST /api/auth/login endpoint accepting { email, password }:
+  - Validate email format with standard regex
+  - Query User table by email
+  - Compare password with bcryptjs.compare()
+  - Return 200 + JWT token in httpOnly cookie (15-min expiry)
+  - Return 401 if email not found or password wrong
+  - Do NOT return password in response
+</action>
+```