@hanzlaa/rcode 3.6.16 → 4.0.0

package/rcode/agents/rules/sprint-checker/process.md

@@ -0,0 +1,377 @@
+
+## Step 1: Load Context
+
+Load phase operation context:
+```bash
+INIT=$(node ".rcode/bin/rcode-tools.cjs" init phase-op "${PHASE_ARG}")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+```
+
+Extract from init JSON: `phase_dir`, `phase_number`, `has_plans`, `plan_count`.
+
+Orchestrator provides CONTEXT.md content in the verification prompt. If provided, parse for locked decisions, discretion areas, deferred ideas.
+
+```bash
+ls "$phase_dir"/*-SPRINT.md 2>/dev/null
+# Read research for Nyquist validation data
+cat "$phase_dir"/*-RESEARCH.md 2>/dev/null
+node ".rcode/bin/rcode-tools.cjs" roadmap get-phase "$phase_number"
+ls "$phase_dir"/*-BRIEF.md 2>/dev/null
+```
+
+**Extract:** Phase goal, requirements (decompose goal), locked decisions, deferred ideas.
+
+## Step 2: Load All Plans
+
+Use rcode-tools to validate plan structure:
+
+```bash
+for plan in "$PHASE_DIR"/*-SPRINT.md; do
+  echo "=== $plan ==="
+  PLAN_STRUCTURE=$(node ".rcode/bin/rcode-tools.cjs" verify plan-structure "$plan")
+  echo "$PLAN_STRUCTURE"
+done
+```
+
+Parse JSON result: `{ valid, errors, warnings, task_count, tasks: [{name, hasFiles, hasAction, hasVerify, hasDone}], frontmatter_fields }`
+
+Map errors/warnings to verification dimensions:
+- Missing frontmatter field → `task_completeness` or `must_haves_derivation`
+- Task missing elements → `task_completeness`
+- Wave/depends_on inconsistency → `dependency_correctness`
+- Checkpoint/autonomous mismatch → `task_completeness`
+
+## Step 3: Parse must_haves
+
+Extract must_haves from each plan using rcode-tools:
+
+```bash
+MUST_HAVES=$(node ".rcode/bin/rcode-tools.cjs" frontmatter get "$PLAN_PATH" --field must_haves)
+```
+
+Returns JSON: `{ truths: [...], artifacts: [...], key_links: [...] }`
+
+**Expected structure:**
+
+```yaml
+must_haves:
+  truths:
+    - "User can log in with email/password"
+    - "Invalid credentials return 401"
+  artifacts:
+    - path: "src/app/api/auth/login/route.ts"
+      provides: "Login endpoint"
+      min_lines: 30
+  key_links:
+    - from: "src/components/LoginForm.tsx"
+      to: "/api/auth/login"
+      via: "fetch in onSubmit"
+```
+
+Aggregate across plans for full picture of what phase delivers.
+
+## Step 4: Check Requirement Coverage
+
+Map requirements to tasks:
+
+```
+Requirement          | Plans | Tasks | Status
+---------------------|-------|-------|--------
+User can log in      | 01    | 1,2   | COVERED
+User can log out     | -     | -     | MISSING
+Session persists     | 01    | 3     | COVERED
+```
+
+For each requirement: find covering task(s), verify action is specific, flag gaps.
+
+**Exhaustive cross-check:** Also read PROJECT.md requirements (not just phase goal). Verify no PROJECT.md requirement relevant to this phase is silently dropped. A requirement is "relevant" if the ROADMAP.md explicitly maps it to this phase or if the phase goal directly implies it — do NOT flag requirements that belong to other phases or future work. Any unmapped relevant requirement is an automatic blocker — list it explicitly in issues.
+
+## Step 5: Validate Task Structure
+
+Use rcode-tools plan-structure verification (already run in Step 2):
+
+```bash
+PLAN_STRUCTURE=$(node ".rcode/bin/rcode-tools.cjs" verify plan-structure "$PLAN_PATH")
+```
+
+The `tasks` array in the result shows each task's completeness:
+- `hasFiles` — files element present
+- `hasAction` — action element present
+- `hasVerify` — verify element present
+- `hasDone` — done element present
+
+**Check:** valid task type (auto, checkpoint:*, tdd), auto tasks have files/action/verify/done, action is specific, verify is runnable, done is measurable.
+
+**For manual validation of specificity** (rcode-tools checks structure, not content quality):
+```bash
+grep -B5 "</task>" "$PHASE_DIR"/*-SPRINT.md | grep -v "<verify>"
+```
+
+## Step 6: Verify Dependency Graph
+
+```bash
+for plan in "$PHASE_DIR"/*-SPRINT.md; do
+  grep "depends_on:" "$plan"
+done
+```
+
+Validate: all referenced plans exist, no cycles, wave numbers consistent, no forward references. If A -> B -> C -> A, report cycle.
+
+## Step 7: Check Key Links
+
+For each key_link in must_haves: find source artifact task, check if action mentions the connection, flag missing wiring.
+
+```
+key_link: Chat.tsx -> /api/chat via fetch
+Task 2 action: "Create Chat component with message list..."
+Missing: No mention of fetch/API call → Issue: Key link not planned
+```
+
+## Step 8: Assess Scope
+
+```bash
+grep -c "<task" "$PHASE_DIR"/$PHASE-01-SPRINT.md
+grep "files_modified:" "$PHASE_DIR"/$PHASE-01-SPRINT.md
+```
+
+Thresholds: 2-3 tasks/plan good, 4 warning, 5+ blocker (split required).
+
+## Step 9: Verify must_haves Derivation
+
+**Truths:** user-observable (not "bcrypt installed" but "passwords are secure"), testable, specific.
+
+**Artifacts:** map to truths, reasonable min_lines, list expected exports/content.
+
+**Key_links:** connect dependent artifacts, specify method (fetch, Prisma, import), cover critical wiring.
+
+## Step 9.5: Verify File References (NEW)
+
+Before step 10, add pre-flight reference verification:
+
+```bash
+PLAN_TEXT=$(cat "$PLAN_PATH")
+VERIFY_RESULT=$(node -e "
+const cr = require('.rcode/bin/lib/code-references.cjs');
+const fs = require('fs');
+const text = fs.readFileSync(process.argv[1], 'utf8');
+const refs = cr.extractReferences(text);
+const result = cr.verifyReferences(refs, process.cwd());
+console.log(JSON.stringify(result, null, 2));
+" "$PLAN_PATH")
+```
+
+Check result:
+- If `summary.ratio < 0.5`: **BLOCKER** — "Plan references files/symbols that don't exist. Plan was built on hallucinated findings."
+- If `summary.ratio >= 0.5 AND < 0.8`: **WARNING** — List missing files/symbols, suggest re-planning with /rcode-debug
+- If `summary.ratio >= 0.8`: **INFO** — Most references verified, proceed
+
+Append to verification output:
+
+```markdown
+## File References Verification
+
+**Verified:** {summary.verified} / {summary.total} ({summary.ratio}%)
+**Status:** ✅ PASS / ⚠️  WARNING / ❌ FAIL
+
+{if missing refs:}
+Missing files: {list}
+Missing symbols: {list}
+{hint}
+```
+
+## Step 10: Determine Overall Status
+
+**passed:** All requirements covered, all tasks complete, dependency graph valid, key links planned, scope within budget, must_haves properly derived.
+
+**issues_found:** One or more blockers or warnings. Plans need revision.
+
+Severities: `blocker` (must fix), `warning` (should fix), `info` (suggestions).
+
+</verification_process>
+
+<examples>
+
+## Scope Exceeded (most common miss)
+
+**Plan 01 analysis:**
+```
+Tasks: 5
+Files modified: 12
+  - prisma/schema.prisma
+  - src/app/api/auth/login/route.ts
+  - src/app/api/auth/logout/route.ts
+  - src/app/api/auth/refresh/route.ts
+  - src/middleware.ts
+  - src/lib/auth.ts
+  - src/lib/jwt.ts
+  - src/components/LoginForm.tsx
+  - src/components/LogoutButton.tsx
+  - src/app/login/page.tsx
+  - src/app/dashboard/page.tsx
+  - src/types/auth.ts
+```
+
+5 tasks exceeds 2-3 target, 12 files is high, auth is complex domain → quality degradation risk.
+
+```yaml
+issue:
+  dimension: scope_sanity
+  severity: blocker
+  description: "Plan 01 has 5 tasks with 12 files - exceeds context budget"
+  plan: "01"
+  metrics:
+    tasks: 5
+    files: 12
+    estimated_context: "~80%"
+  fix_hint: "Split into: 01 (schema + API), 02 (middleware + lib), 03 (UI components)"
+```
+
+</examples>
+
+<issue_structure>
+
+## Issue Format
+
+```yaml
+issue:
+  plan: "16-01"              # Which plan (null if phase-level)
+  dimension: "task_completeness"  # Which dimension failed
+  severity: "blocker"        # blocker | warning | info
+  description: "..."
+  task: 2                    # Task number if applicable
+  fix_hint: "..."
+```
+
+## Severity Levels
+
+**blocker** - Must fix before execution
+- Missing requirement coverage
+- Missing required task fields
+- Circular dependencies
+- Scope > 5 tasks per plan
+
+**warning** - Should fix, execution may work
+- Scope 4 tasks (borderline)
+- Implementation-focused truths
+- Minor wiring missing
+
+**info** - Suggestions for improvement
+- Could split for better parallelization
+- Could improve verification specificity
+
+Return all issues as a structured `issues:` YAML list (see dimension examples for format).
+
+</issue_structure>
+
+<structured_returns>
+
+## VERIFICATION PASSED
+
+```markdown
+## VERIFICATION PASSED
+
+**Phase:** {phase-name}
+**Plans verified:** {N}
+**Status:** All checks passed
+
+### Coverage Summary
+
+| Requirement | Plans | Status |
+|-------------|-------|--------|
+| {req-1}     | 01    | Covered |
+| {req-2}     | 01,02 | Covered |
+
+### Plan Summary
+
+| Plan | Tasks | Files | Wave | Status |
+|------|-------|-------|------|--------|
+| 01   | 3     | 5     | 1    | Valid  |
+| 02   | 2     | 4     | 2    | Valid  |
+
+Plans verified. Run `/rcode-execute {phase}` to proceed.
+```
+
+## ISSUES FOUND
+
+```markdown
+## ISSUES FOUND
+
+**Phase:** {phase-name}
+**Plans checked:** {N}
+**Issues:** {X} blocker(s), {Y} warning(s), {Z} info
+
+### Blockers (must fix)
+
+**1. [{dimension}] {description}**
+- Plan: {plan}
+- Task: {task if applicable}
+- Fix: {fix_hint}
+
+### Warnings (should fix)
+
+**1. [{dimension}] {description}**
+- Plan: {plan}
+- Fix: {fix_hint}
+
+### Structured Issues
+
+(YAML issues list using format from Issue Format above)
+
+### Recommendation
+
+{N} blocker(s) require revision. Returning to planner with feedback.
+```
+
+</structured_returns>
+
+<anti_patterns>
+
+**DO NOT** check code existence — that's rcode-verifier's job. You verify plans, not codebase.
+
+**DO NOT** run the application. Static plan analysis only.
+
+**DO NOT** accept vague tasks. "Implement auth" is not specific. Tasks need concrete files, actions, verification.
+
+**DO NOT** skip dependency analysis. Circular/broken dependencies cause execution failures.
+
+**DO NOT** ignore scope. 5+ tasks/plan degrades quality. Report and split.
+
+**DO NOT** verify implementation details. Check that plans describe what to build.
+
+**DO NOT** trust task names alone. Read action, verify, done fields. A well-named task can be empty.
+
+</anti_patterns>
+
+<success_criteria>
+
+Plan verification complete when:
+
+- [ ] Phase goal extracted from ROADMAP.md
+- [ ] All SPRINT.md files in phase directory loaded
+- [ ] must_haves parsed from each plan frontmatter
+- [ ] Requirement coverage checked (all requirements have tasks)
+- [ ] Task completeness validated (all required fields present)
+- [ ] Dependency graph verified (no cycles, valid references)
+- [ ] Key links checked (wiring planned, not just artifacts)
+- [ ] Scope assessed (within context budget)
+- [ ] must_haves derivation verified (user-observable truths)
+- [ ] Context compliance checked (if CONTEXT.md provided):
+  - [ ] Locked decisions have implementing tasks
+  - [ ] No tasks contradict locked decisions
+  - [ ] Deferred ideas not included in plans
+- [ ] Overall status determined (passed | issues_found)
+- [ ] Cross-plan data contracts checked (no conflicting transforms on shared data)
+- [ ] CLAUDE.md compliance checked (plans respect project conventions)
+- [ ] Structured issues returned (if any found)
+- [ ] Result returned to orchestrator
+
+</success_criteria>
+
+## Constraints
+
+- Apply Karpathy guidelines (see @-included reference) as hard rules. Reference the principle number when refusing a change.
+- validate YAML frontmatter exactly as specified
+- check task structure against execution-protocol.md
+- verify all dependencies and checkpoint placement
+- return PASS/FAIL with specific issues listed
+- never modify the plan — only report findings

package/rcode/agents/rules/verifier/anti-patterns.md

@@ -0,0 +1,94 @@
+# Verifier — Anti-Pattern Scanning (Step 7) + Stub Detection Patterns
+
+## Step 7: Scan for Anti-Patterns
+
+Identify files modified in this phase from SUMMARY.md key-files section, or extract commits and verify:
+
+```bash
+# Option 1: Extract from SUMMARY frontmatter
+SUMMARY_FILES=$(node ".rcode/bin/rcode-tools.cjs" summary-extract "$PHASE_DIR"/*-SUMMARY.md --fields key-files)
+
+# Option 2: Verify commits exist (if commit hashes documented)
+COMMIT_HASHES=$(grep -oE "[a-f0-9]{7,40}" "$PHASE_DIR"/*-SUMMARY.md | head -10)
+if [ -n "$COMMIT_HASHES" ]; then
+  COMMITS_VALID=$(node ".rcode/bin/rcode-tools.cjs" verify commits $COMMIT_HASHES)
+fi
+
+# Fallback: grep for files
+grep -E "^\- \`" "$PHASE_DIR"/*-SUMMARY.md | sed 's/.*`\([^`]*\)`.*/\1/' | sort -u
+```
+
+## Anti-pattern detection on each file
+
+```bash
+# TODO/FIXME/placeholder comments
+grep -n -E "TODO|FIXME|XXX|HACK|PLACEHOLDER" "$file" 2>/dev/null
+grep -n -E "placeholder|coming soon|will be here|not yet implemented|not available" "$file" -i 2>/dev/null
+
+# Empty implementations
+grep -n -E "return null|return \{\}|return \[\]|=> \{\}" "$file" 2>/dev/null
+
+# Hardcoded empty data (common stub patterns)
+grep -n -E "=\s*\[\]|=\s*\{\}|=\s*null|=\s*undefined" "$file" 2>/dev/null | grep -v -E "(test|spec|mock|fixture|\.test\.|\.spec\.)" 2>/dev/null
+
+# Props with hardcoded empty values (React/Vue/Svelte stub indicators)
+grep -n -E "=\{(\[\]|\{\}|null|undefined|''|\"\")\}" "$file" 2>/dev/null
+
+# Console.log only implementations
+grep -n -B 2 -A 2 "console\.log" "$file" 2>/dev/null | grep -E "^\s*(const|function|=>)"
+```
+
+**Stub classification:** A grep match is a STUB only when the value flows to rendering or user-visible output AND no other code path populates it with real data. A test helper, type default, or initial state that gets overwritten by a fetch/store is NOT a stub. Check for data-fetching (useEffect, fetch, query, useSWR, useQuery, subscribe) that writes to the same variable before flagging.
+
+Categorize: 🛑 Blocker (prevents goal) | ⚠️ Warning (incomplete) | ℹ️ Info (notable)
+
+---
+
+## Stub Detection Reference Patterns
+
+### React Component Stubs
+
+```javascript
+// RED FLAGS:
+return <div>Component</div>
+return <div>Placeholder</div>
+return <div>{/* TODO */}</div>
+return null
+return <></>
+
+// Empty handlers:
+onClick={() => {}}
+onChange={() => console.log('clicked')}
+onSubmit={(e) => e.preventDefault()}  // Only prevents default
+```
+
+### API Route Stubs
+
+```typescript
+// RED FLAGS:
+export async function POST() {
+  return Response.json({ message: "Not implemented" });
+}
+
+export async function GET() {
+  return Response.json([]); // Empty array with no DB query
+}
+```
+
+### Wiring Red Flags
+
+```typescript
+// Fetch exists but response ignored:
+fetch('/api/messages')  // No await, no .then, no assignment
+
+// Query exists but result not returned:
+await prisma.message.findMany()
+return Response.json({ ok: true })  // Returns static, not query result
+
+// Handler only prevents default:
+onSubmit={(e) => e.preventDefault()}
+
+// State exists but not rendered:
+const [messages, setMessages] = useState([])
+return <div>No messages</div>  // Always shows "no messages"
+```

package/rcode/agents/rules/verifier/artifact-verification.md

@@ -0,0 +1,69 @@
+# Verifier — Observable Truths + 3-Level Artifact Verification (Steps 3–4)
+
+## Step 3: Verify Observable Truths
+
+For each truth, determine if codebase enables it.
+
+**Verification status:**
+
+- ✓ VERIFIED: All supporting artifacts pass all checks
+- ✗ FAILED: One or more artifacts missing, stub, or unwired
+- ? UNCERTAIN: Can't verify programmatically (needs human)
+
+For each truth:
+
+1. Identify supporting artifacts
+2. Check artifact status (Step 4)
+3. Check wiring status (Step 5)
+4. Determine truth status
+
+## Step 4: Verify Artifacts (Three Levels)
+
+Use rcode-tools for artifact verification against must_haves in PLAN frontmatter:
+
+```bash
+ARTIFACT_RESULT=$(node ".rcode/bin/rcode-tools.cjs" verify artifacts "$PLAN_PATH")
+```
+
+Parse JSON result: `{ all_passed, passed, total, artifacts: [{path, exists, issues, passed}] }`
+
+For each artifact in result:
+- `exists=false` → MISSING
+- `issues` contains "Only N lines" or "Missing pattern" → STUB
+- `passed=true` → VERIFIED
+
+### Artifact status mapping
+
+| exists | issues empty | Status      |
+| ------ | ------------ | ----------- |
+| true   | true         | ✓ VERIFIED  |
+| true   | false        | ✗ STUB      |
+| false  | -            | ✗ MISSING   |
+
+### Wiring verification (Level 3)
+
+For artifacts that pass Levels 1-2, check imports/usage manually:
+
+```bash
+# Import check
+grep -r "import.*$artifact_name" "${search_path:-src/}" --include="*.ts" --include="*.tsx" 2>/dev/null | wc -l
+
+# Usage check (beyond imports)
+grep -r "$artifact_name" "${search_path:-src/}" --include="*.ts" --include="*.tsx" 2>/dev/null | grep -v "import" | wc -l
+```
+
+**Wiring status:**
+- WIRED: Imported AND used
+- ORPHANED: Exists but not imported/used
+- PARTIAL: Imported but not used (or vice versa)
+
+### Final Artifact Status (Levels 1-3)
+
+| Exists | Substantive | Wired | Status      |
+| ------ | ----------- | ----- | ----------- |
+| ✓      | ✓           | ✓     | ✓ VERIFIED  |
+| ✓      | ✓           | ✗     | ⚠️ ORPHANED |
+| ✓      | ✗           | -     | ✗ STUB      |
+| ✗      | -           | -     | ✗ MISSING   |
+
+For Level 4 (data flow), see `data-flow-trace.md`.

package/rcode/agents/rules/verifier/context-loading.md

@@ -0,0 +1,84 @@
+# Verifier — Context Loading (Steps 0–2)
+
+## Step 0: Check for Previous Verification
+
+```bash
+cat "$PHASE_DIR"/*-VERIFICATION.md 2>/dev/null
+```
+
+**If previous verification exists with `gaps:` section → RE-VERIFICATION MODE:**
+
+1. Parse previous VERIFICATION.md frontmatter
+2. Extract `must_haves` (truths, artifacts, key_links)
+3. Extract `gaps` (items that failed)
+4. Set `is_re_verification = true`
+5. **Skip to Step 3** with optimization:
+   - **Failed items:** Full 3-level verification (exists, substantive, wired)
+   - **Passed items:** Quick regression check (existence + basic sanity only)
+
+**If no previous verification OR no `gaps:` section → INITIAL MODE:**
+
+Set `is_re_verification = false`, proceed with Step 1.
+
+## Step 1: Load Context (Initial Mode Only)
+
+```bash
+ls "$PHASE_DIR"/*-SPRINT.md 2>/dev/null
+ls "$PHASE_DIR"/*-SUMMARY.md 2>/dev/null
+node ".rcode/bin/rcode-tools.cjs" roadmap get-phase "$PHASE_NUMBER"
+grep -E "^| $PHASE_NUMBER" .rcode/REQUIREMENTS.md 2>/dev/null
+```
+
+Extract phase goal from ROADMAP.md — this is the outcome to verify, not the tasks.
+
+## Step 2: Establish Must-Haves (Initial Mode Only)
+
+In re-verification mode, must-haves come from Step 0.
+
+### Option A: Must-haves in PLAN frontmatter
+
+```bash
+grep -l "must_haves:" "$PHASE_DIR"/*-SPRINT.md 2>/dev/null
+```
+
+If found, extract and use:
+
+```yaml
+must_haves:
+  truths:
+    - "User can see existing messages"
+    - "User can send a message"
+  artifacts:
+    - path: "src/components/Chat.tsx"
+      provides: "Message list rendering"
+  key_links:
+    - from: "Chat.tsx"
+      to: "api/chat"
+      via: "fetch in useEffect"
+```
+
+### Option B: Use Success Criteria from ROADMAP.md
+
+If no must_haves in frontmatter, check for Success Criteria:
+
+```bash
+PHASE_DATA=$(node ".rcode/bin/rcode-tools.cjs" roadmap get-phase "$PHASE_NUMBER" --raw)
+```
+
+Parse the `success_criteria` array from the JSON output. If non-empty:
+1. **Use each Success Criterion directly as a truth** (they are already observable, testable behaviors)
+2. **Derive artifacts:** For each truth, "What must EXIST?" — map to concrete file paths
+3. **Derive key links:** For each artifact, "What must be CONNECTED?" — this is where stubs hide
+4. **Document must-haves** before proceeding
+
+Success Criteria from ROADMAP.md are the contract — they take priority over Goal-derived truths.
+
+### Option C: Derive from phase goal (fallback)
+
+If no must_haves in frontmatter AND no Success Criteria in ROADMAP:
+
+1. **State the goal** from ROADMAP.md
+2. **Derive truths:** "What must be TRUE?" — list 3-7 observable, testable behaviors
+3. **Derive artifacts:** For each truth, "What must EXIST?" — map to concrete file paths
+4. **Derive key links:** For each artifact, "What must be CONNECTED?" — this is where stubs hide
+5. **Document derived must-haves** before proceeding

package/rcode/agents/rules/verifier/gap-output.md

@@ -0,0 +1,51 @@
+# Verifier — Status Determination + Gap Output (Steps 8–10)
+
+## Step 8: Identify Human Verification Needs
+
+**Always needs human:** Visual appearance, user flow completion, real-time behavior, external service integration, performance feel, error message clarity.
+
+**Needs human if uncertain:** Complex wiring grep can't trace, dynamic state behavior, edge cases.
+
+**Format:**
+
+```markdown
+### 1. {Test Name}
+
+**Test:** {What to do}
+**Expected:** {What should happen}
+**Why human:** {Why can't verify programmatically}
+```
+
+## Step 9: Determine Overall Status
+
+**Status: passed** — All truths VERIFIED, all artifacts pass levels 1-3, all key links WIRED, no blocker anti-patterns.
+
+**Status: gaps_found** — One or more truths FAILED, artifacts MISSING/STUB, key links NOT_WIRED, or blocker anti-patterns found.
+
+**Status: human_needed** — All automated checks pass but items flagged for human verification.
+
+**Score:** `verified_truths / total_truths`
+
+## Step 10: Structure Gap Output (If Gaps Found)
+
+Structure gaps in YAML frontmatter for `/rcode-plan --gaps`:
+
+```yaml
+gaps:
+  - truth: "Observable truth that failed"
+    status: failed
+    reason: "Brief explanation"
+    artifacts:
+      - path: "src/path/to/file.tsx"
+        issue: "What's wrong"
+    missing:
+      - "Specific thing to add/fix"
+```
+
+- `truth`: The observable truth that failed
+- `status`: failed | partial
+- `reason`: Brief explanation
+- `artifacts`: Files with issues
+- `missing`: Specific things to add/fix
+
+**Group related gaps by concern** — if multiple truths fail from the same root cause, note this to help the planner create focused plans.