qualia-framework 4.5.0 → 5.1.0

package/skills/qualia-optimize/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-optimize
-description: "Deep optimization pass — reads .planning/ AND codebase to find performance, design, UI, backend, and frontend issues. Spawns parallel specialist agents. Use this skill whenever the user says 'optimize', 'optimization pass', 'find issues', 'qualia-optimize', 'deep optimize', 'performance audit', 'design alignment check', 'speed up', 'slow', 'bundle size', or wants a comprehensive quality sweep. Supports --perf, --ui, --backend, --alignment, --fix flags."
+description: "Deep optimization pass — reads .planning/ AND codebase to find performance, design, UI, backend, frontend, AND architecture-deepening opportunities. Spawns parallel specialist agents. Use whenever the user says 'optimize', 'optimization pass', 'find issues', 'qualia-optimize', 'deep optimize', 'performance audit', 'design alignment check', 'speed up', 'slow', 'bundle size', 'refactor architecture', 'shallow modules', 'simplify', or wants a comprehensive quality sweep. Supports --perf, --ui, --backend, --alignment, --deepen, --fix flags."
 allowed-tools:
   - Bash
   - Read
@@ -13,30 +13,35 @@ allowed-tools:
 
 # Qualia Optimize — Deep Codebase + Planning Optimization
 
-Comprehensive optimization that reads BOTH `.planning/` docs AND the actual codebase. Never analyze one without the other.
+## Reference templates
+
+Detailed agent-prompt templates live in `REFERENCE.md` (in this same skill folder). When a step below says "see REFERENCE.md section X", read that section before generating the spawn.
+
+---
+
+Reads `.planning/` docs AND codebase. Never analyze one without the other.
 
 ## Usage
 
-- `/qualia-optimize` — Full optimization (all 6 dimensions)
+- `/qualia-optimize` — Full (all 7 dimensions + architecture deepening)
 - `/qualia-optimize --perf` — Performance only (queries, bundle, render, latency)
 - `/qualia-optimize --ui` — Frontend/design/UI only
-- `/qualia-optimize --backend` — Backend only (RLS, auth, queries, edge functions)
-- `/qualia-optimize --alignment` — Planning-code alignment check only
-- `/qualia-optimize --fix` — Auto-fix LOW/MEDIUM findings from existing OPTIMIZE.md
+- `/qualia-optimize --backend` — Backend only (RLS, auth, queries, edge fns)
+- `/qualia-optimize --alignment` — Planning-code alignment only
+- `/qualia-optimize --deepen` — Architecture deepening only (Ousterhout: shallow modules, deeper interfaces)
+- `/qualia-optimize --fix` — Auto-fix LOW/MEDIUM from existing OPTIMIZE.md
 
 ## Process
 
 ### Step 1: Parse Arguments
 
-Extract mode from $ARGUMENTS. Default to `full`.
+Mode from $ARGUMENTS. Default: `full`.
+Modes: `full`, `perf`, `ui`, `backend`, `alignment`, `deepen`, `fix`.
+`--fix` skips to Step 9 (requires `.planning/OPTIMIZE.md`).
 
-Supported modes: `full`, `perf`, `ui`, `backend`, `alignment`, `fix`.
+### Step 2: Load Planning Context (MANDATORY)
 
-If `--fix`: skip to Step 9 (requires existing `.planning/OPTIMIZE.md`).
-
-### Step 2: Load Planning Context (MANDATORY — never skip)
-
-Read ALL of these (skip silently if file doesn't exist, but always attempt):
+Read all (skip silently if missing):
 
 ```bash
 cat .planning/PROJECT.md 2>/dev/null || echo "NO_PROJECT"
@@ -58,15 +63,23 @@ cat .planning/STATE.md 2>/dev/null || echo "NO_STATE"
 cat .planning/DESIGN.md 2>/dev/null || echo "NO_DESIGN"
 ```
 
-Also read the rules:
+```bash
+cat .planning/CONTEXT.md 2>/dev/null || echo "NO_CONTEXT"
+```
+
+```bash
+ls .planning/decisions/ 2>/dev/null && cat .planning/decisions/*.md 2>/dev/null || echo "NO_ADRS"
+```
+
+Also read rules:
 ```bash
 cat ~/.claude/rules/frontend.md 2>/dev/null
 cat ~/.claude/rules/security.md 2>/dev/null
 ```
 
-Store all content — you will inline it into agent prompts.
+Store all; inline into agent prompts.
 
-**If NO planning docs exist at all**: warn the user but proceed. The optimization still works on raw codebase — it just can't check alignment.
+**No planning docs:** warn, proceed. Can optimize raw codebase; can't check alignment.
 
 ### Step 3: Discover Codebase
 
@@ -87,224 +100,49 @@ git diff --stat HEAD~10..HEAD 2>/dev/null | tail -5
 ls -d app/ src/ pages/ components/ lib/ actions/ hooks/ supabase/ types/ 2>/dev/null
 ```
 
-Classify project type: `web` | `voice` | `mobile` | `agent` | `edge-functions` | `unknown`
+Classify: `web` | `voice` | `mobile` | `agent` | `edge-functions` | `unknown`
 
 ### Step 4: Spawn Wave 1 Agents (parallel)
 
-Based on mode, spawn agents in a **single message** with multiple Agent() calls.
+Spawn in **single message** with multiple Agent() calls per mode:
 
 | Mode | Agents |
 |------|--------|
-| `full` | frontend-agent + backend-agent + performance-oracle (3 parallel) |
-| `perf` | performance-oracle only |
-| `ui` | frontend-agent only |
-| `backend` | backend-agent only |
-| `alignment` | general-purpose with alignment prompt |
-
-**CRITICAL**: Inline ALL planning context into each agent prompt. `@` references don't work across Agent() boundaries.
-
-#### Frontend Agent Prompt
+| `full` | frontend + backend + perf-oracle (3 parallel), then arch-strategist (Wave 2) |
+| `perf` | perf-oracle only |
+| `ui` | frontend only |
+| `backend` | backend only |
+| `alignment` | alignment prompt only |
+| `deepen` | arch-strategist only (skip Wave 1) |
 
-```
-Agent(
-  prompt="You are optimizing a project's frontend. Read the planning docs and codebase rules below, then analyze the actual code.
-
-<planning>
-{PROJECT.md content}
-{REQUIREMENTS.md content}
-{DESIGN.md content}
-</planning>
-
-<rules>
-{rules/frontend.md content}
-</rules>
-
-<task>
-Analyze the frontend codebase for issues in these categories:
-
-1. **UI Quality**
-   - Loading states: every async operation should show a loading indicator
-   - Error states: every data-fetching component should handle errors gracefully
-   - Empty states: lists/tables should handle zero items with helpful messaging
-   - Responsive: check for fixed pixel widths on containers, missing breakpoint handling
-   - Accessibility: alt text on images, ARIA labels on interactive elements, keyboard navigation
-
-2. **Design Alignment**
-   - Compare actual components against DESIGN.md decisions (colors, typography, spacing)
-   - Check rules/frontend.md compliance: distinctive fonts? sharp accents? transitions? No card grids or blue-purple gradients?
-   - Consistency: are the same patterns used throughout? (button styles, spacing, color usage)
-
-3. **Frontend Performance**
-   - Bundle: large library imports that could be tree-shaken or dynamically imported
-   - Images: using next/image? width/height set? lazy loading below fold?
-   - Fonts: using next/font? No render-blocking font loads?
-   - CSS: unused Tailwind classes? conflicting styles?
-   - Rendering: unnecessary re-renders, missing React.memo on list items, heavy computations in render
-
-For EVERY finding, output in this exact format:
-- **What**: [description]
-- **Where**: [file:line]
-- **Why**: [impact on users/performance]
-- **Fix**: [concrete fix suggestion]
-- **Severity**: CRITICAL | HIGH | MEDIUM | LOW
-</task>",
-  subagent_type="general-purpose",
-  description="Frontend optimization analysis"
-)
-```
-
-#### Backend Agent Prompt
-
-```
-Agent(
-  prompt="You are optimizing a project's backend. Read the planning docs and security rules below, then analyze the actual code.
-
-<planning>
-{PROJECT.md content}
-{REQUIREMENTS.md content}
-</planning>
-
-<rules>
-{rules/security.md content}
-</rules>
-
-<task>
-Analyze the backend codebase for issues:
-
-1. **Security**
-   - RLS: every Supabase table must have ROW LEVEL SECURITY enabled with policies
-   - Service role: grep for service_role key usage in client-side code (app/, components/, src/) — should be ZERO
-   - Auth: all mutations use server-side auth check (supabase.auth.getUser())
-   - Validation: input validated with Zod before database operations
-   - No dangerouslySetInnerHTML or eval()
-
-2. **Data Access Patterns**
-   - Server actions vs client mutations: data writes should use 'use server' actions, not direct Supabase client calls
-   - Proper error handling: try/catch with meaningful error messages
-   - Revalidation: revalidatePath/revalidateTag after mutations
-
-3. **Edge Functions** (if supabase/functions/ exists)
-   - Cold start optimization: bundle size, dependency count
-   - Error handling and logging
-   - CORS configuration
-   - Timeout protection (maxDuration)
-
-4. **API Quality**
-   - Rate limiting on public endpoints
-   - Proper HTTP status codes
-   - Consistent error response format
-
-For EVERY finding, output:
-- **What**: [description]
-- **Where**: [file:line]
-- **Why**: [impact]
-- **Fix**: [concrete suggestion]
-- **Severity**: CRITICAL | HIGH | MEDIUM | LOW
-</task>",
-  subagent_type="general-purpose",
-  description="Backend optimization analysis"
-)
-```
-
-#### Performance Oracle Prompt
+**CRITICAL**: Inline ALL planning context into each prompt. `@` refs don't work across Agent() boundaries.
 
-```
-Agent(
-  prompt="You are analyzing cross-cutting performance issues. Read the project context, then analyze the codebase.
-
-<planning>
-{PROJECT.md content}
-</planning>
-
-<task>
-Analyze for performance issues across the full stack:
-
-1. **Database Queries**
-   - N+1 queries: Supabase .from() calls inside loops or .map()
-   - Missing indexes: .eq()/.filter()/.order() columns without corresponding indexes in migrations
-   - Sequential queries that could be parallel (Promise.all)
-   - Over-fetching: SELECT * when only specific columns needed
-
-2. **API Latency**
-   - Sequential API calls from client that could be batched
-   - Missing caching (SWR/React Query stale times, HTTP cache headers)
-   - Large payloads without pagination
-
-3. **Bundle Size**
-   - Barrel exports (index.ts re-exporting everything) preventing tree-shaking
-   - Large libraries imported for single functions (lodash, moment)
-   - Missing dynamic imports for heavy components (charts, editors, maps)
-
-4. **Render Performance**
-   - Expensive computations in render path without useMemo
-   - Event handlers recreated on every render without useCallback
-   - Large lists without virtualization
-   - Context providers causing unnecessary re-renders
-
-For EVERY finding, output:
-- **What**: [description]
-- **Where**: [file:line]
-- **Why**: [performance impact, quantified if possible]
-- **Fix**: [concrete suggestion]
-- **Severity**: CRITICAL | HIGH | MEDIUM | LOW
-</task>",
-  subagent_type="general-purpose",
-  description="Performance optimization analysis"
-)
-```
+Spawn parallel: **frontend** (@REFERENCE.md "Frontend agent prompt"), **backend** (@REFERENCE.md "Backend agent prompt"), **perf oracle** (@REFERENCE.md "Performance oracle prompt").
 
-### Step 5: Spawn Wave 2 Agent (after Wave 1 completes)
+### Step 5: Wave 2 -- Architecture Strategist
 
-After all Wave 1 agents return, spawn the architecture strategist with their combined findings:
+`full`: after Wave 1 (synthesizes + deepens). `deepen`: sole agent (no Wave 1).
 
-```
-Agent(
-  prompt="You are synthesizing optimization findings from 3 specialist agents. Look for cross-cutting architectural issues.
-
-<wave1_findings>
-{All findings from frontend-agent, backend-agent, performance-oracle}
-</wave1_findings>
-
-<planning>
-{PROJECT.md content}
-{REQUIREMENTS.md content}
-</planning>
-
-<task>
-1. Identify patterns across findings — recurring issues that point to a structural problem
-2. Find coupling issues between frontend and backend
-3. Check for inconsistent patterns (e.g., some routes use server actions, others use API routes)
-4. Identify missing abstractions (same pattern repeated 3+ times)
-5. Check for dead code and unused exports
-
-Output:
-- **Structural findings** (architectural issues, not covered by Wave 1)
-- **Pattern consolidation** (where Wave 1 findings share a root cause)
-- Each finding in the same format: What/Where/Why/Fix/Severity
-</task>",
-  subagent_type="general-purpose",
-  description="Architecture synthesis"
-)
-```
+Spawn **arch strategist** (@REFERENCE.md "Architecture strategist prompt (deepening lens)").
 
-**Skip Wave 2 for single-mode runs** (`--perf`, `--ui`, `--backend`). Only run for `full` mode.
+**Skip Wave 2 for single-mode** (`--perf`, `--ui`, `--backend`, `--alignment`). Run for `full` and `deepen`.
 
-### Step 6: Alignment Check (always runs in `full` and `alignment` modes)
+### Step 6: Alignment Check (`full` and `alignment` modes)
 
-For `alignment` mode, this is the sole analysis. For `full` mode, run alongside Wave 1.
+`alignment`: sole analysis. `full`: alongside Wave 1.
 
-Read REQUIREMENTS.md and ROADMAP.md. For each requirement marked "Complete" or mapped to a completed phase:
+Read REQUIREMENTS.md + ROADMAP.md. Per req marked "Complete" or mapped to completed phase:
 
 ```bash
 # Find completed requirements
 grep -E "Complete|✓" .planning/REQUIREMENTS.md 2>/dev/null
 ```
 
-For each completed requirement:
-- Grep the codebase for evidence it actually exists (routes, components, API endpoints)
-- If not found: flag as "Claimed complete but not implemented"
+Per completed req:
+- Grep for evidence (routes, components, endpoints)
+- Not found: flag "Claimed complete but not implemented"
 
-Then scan for orphan features:
+Orphan scan:
 ```bash
 # Find all routes/pages
 find app -name "page.tsx" -o -name "route.ts" 2>/dev/null
@@ -312,16 +150,15 @@ find app -name "page.tsx" -o -name "route.ts" 2>/dev/null
 find app/api -name "route.ts" 2>/dev/null
 ```
 
-Cross-reference with REQUIREMENTS.md — any route/feature NOT in requirements is flagged as "Undocumented feature".
+Cross-ref with REQUIREMENTS.md; route NOT in reqs: "Undocumented feature".
 
-### Step 7: Collect and Score Findings
+### Step 7: Collect and Score
 
-After all agents return:
-1. Deduplicate (same file:line from multiple agents → keep the most detailed one)
-2. Sort by severity: CRITICAL first
-3. Group by dimension: Performance, Design Alignment, UI Quality, Backend, Frontend, Planning-Code Alignment, Architecture
-
-Count totals per severity.
+All agents done:
+1. Deduplicate (same file:line, keep most detailed)
+2. Sort: CRITICAL first
+3. Group by dimension: Perf, Design, UI, Backend, Frontend, Alignment, Architecture
+4. Count per severity.
 
 ### Step 8: Write OPTIMIZE.md and Present Results
 
@@ -399,27 +236,25 @@ Run /qualia-optimize --fix to auto-fix LOW/MEDIUM findings.
 
 ### Step 9: --fix Mode
 
-When `--fix` is provided:
-
-1. Read existing `.planning/OPTIMIZE.md` — if not found, error: "Run /qualia-optimize first"
-2. Filter to LOW and MEDIUM findings only
-3. For each finding with a clear, safe fix:
-   - Read the target file
-   - Apply the fix
-   - Verify it doesn't break (npx tsc --noEmit if TypeScript)
-4. Update OPTIMIZE.md: mark fixed findings, recount severities
-5. Commit changes
-6. Report what was fixed and what remains
+`--fix` mode:
 
-**Never auto-fix CRITICAL or HIGH** — those require human judgment.
+1. Read `.planning/OPTIMIZE.md`; missing: "Run /qualia-optimize first"
+2. Filter to LOW + MEDIUM only
+3. Per finding with clear, safe fix:
+   - Read target file
+   - Apply fix
+   - Verify (npx tsc --noEmit if TS)
+4. Update OPTIMIZE.md: mark fixed, recount severities
+5. Commit
+6. Report fixed vs remaining
 
-### Step 10: Gap Phase Creation (if user selects option 1 from Step 8)
+**Never auto-fix CRITICAL/HIGH.** Require human judgment.
 
-If user wants a fix phase for critical issues:
+### Step 10: Gap Phase Creation (user picks option 1)
 
-1. Read ROADMAP.md, find current phase number
-2. Insert a decimal phase: `Phase {N}.1: Optimization Fixes (INSERTED)`
-3. Map CRITICAL and HIGH findings as success criteria
+1. Read ROADMAP.md, find current phase
+2. Insert `Phase {N}.1: Optimization Fixes (INSERTED)`
+3. Map CRITICAL + HIGH findings as success criteria
 4. Update STATE.md
 5. Commit
 6. Suggest: "Fix phase created. Run `/qualia-plan {N}.1`"

package/skills/qualia-plan/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-plan
-description: "Plan the current phase — spawns planner, validates with plan-checker in a revision loop (max 2), optionally runs discuss/research first. Use when ready to plan a phase."
+description: "Plans the current phase by spawning a planner agent to break it into executable tasks with waves, then validates via a plan-checker revision loop (max 2 cycles). Supports gap-closure mode for verification failures. Use when the user says 'plan this phase', 'break this into tasks', 'create the plan', 'qualia-plan', 'plan phase 2', or after /qualia-new sets up the journey."
 allowed-tools:
   - Bash
   - Read
@@ -15,15 +15,15 @@ allowed-tools:
 
 # /qualia-plan — Plan a Phase
 
-Spawn a planner agent to break the current phase into executable tasks, then validate the plan with a checker (up to 2 revision cycles) before routing to build.
+Spawn planner to break phase into tasks, validate with checker (max 2 revision cycles), route to build.
 
 ## Usage
 
-`/qualia-plan` — plan the next unplanned phase
+`/qualia-plan` — plan next unplanned phase
 `/qualia-plan {N}` — plan specific phase N
 `/qualia-plan {N} --gaps` — plan fixes for verification failures
-`/qualia-plan {N} --skip-check` — skip the plan-checker validation loop (not recommended)
-`/qualia-plan {N} --auto` — plan + auto-chain into `/qualia-build {N} --auto` when done (no human approval between plan and build)
+`/qualia-plan {N} --skip-check` — skip plan-checker loop (not recommended)
+`/qualia-plan {N} --auto` — plan + chain into `/qualia-build {N} --auto` (no human gate)
 
 ## Process
 
@@ -38,9 +38,9 @@ node ~/.claude/bin/knowledge.js load patterns
 node ~/.claude/bin/knowledge.js load client
 ```
 
-If no phase number given, use the current phase from STATE.md.
+No phase number → current phase from STATE.md.
 
-**Read phase-specific context if it exists:**
+**Phase-specific context (if exists):**
 ```bash
 cat .planning/phase-{N}-context.md 2>/dev/null   # from /qualia-discuss
 cat .planning/phase-{N}-research.md 2>/dev/null  # from /qualia-research
@@ -48,19 +48,17 @@ cat .planning/phase-{N}-research.md 2>/dev/null  # from /qualia-research
 
 ### 2. Optional: Suggest Deeper Prep
 
-**If ROADMAP.md marked this phase as a "research flag" AND no phase-{N}-research.md exists:**
+**If ROADMAP.md flagged phase for research AND no phase-{N}-research.md:**
 
 - header: "Research first?"
-- question: "This phase was flagged for deeper research. Run /qualia-research {N} first?"
+- question: "Phase flagged for research. Run /qualia-research {N} first?"
 - options:
-  - "Yes, research first" — Run /qualia-research {N} inline, then continue
-  - "Skip, plan directly" — I know enough
+  - "Yes, research first"
+  - "Skip, plan directly"
 
-**If phase involves compliance/regulatory/architectural stakes AND no phase-{N}-context.md exists:**
+**If phase has compliance/regulatory/architectural stakes AND no phase-{N}-context.md:**
 
-Briefly suggest: *"Want to run /qualia-discuss {N} first to lock decisions? Optional."*
-
-Don't force it. Some phases don't need it.
+Suggest: *"Run /qualia-discuss {N} first to lock decisions? Optional."*
 
 ### 3. Spawn Planner (Fresh Context)
 
@@ -69,12 +67,9 @@ node ~/.claude/bin/qualia-ui.js banner plan {N} "{phase name from ROADMAP.md}"
 node ~/.claude/bin/qualia-ui.js spawn planner "Breaking phase into tasks..."
 ```
 
-Spawn the planner:
-
 ```
 Agent(prompt="
-Read your role: @~/.claude/agents/planner.md
-Grounding + rubrics: @~/.claude/rules/grounding.md
+Role: @~/.claude/agents/planner.md
 
 <project_context>
 @.planning/PROJECT.md
@@ -89,86 +84,84 @@ Phase {N} from ROADMAP.md:
 @.planning/ROADMAP.md
 
 Goal: {goal from ROADMAP.md}
-Requirements: {REQ-IDs from ROADMAP.md}
+Reqs: {REQ-IDs from ROADMAP.md}
 Success criteria: {success criteria from ROADMAP.md}
 </phase_details>
 
 <locked_decisions>
-{if phase-{N}-context.md exists, inline its Locked Decisions section; else 'none'}
+{phase-{N}-context.md Locked Decisions if exists, else 'none'}
 </locked_decisions>
 
 <research_findings>
-{if phase-{N}-research.md exists, inline its recommendation; else 'none'}
+{phase-{N}-research.md recommendation if exists, else 'none'}
 </research_findings>
 
-{If --gaps: Also read @.planning/phase-{N}-verification.md for failures to fix. Create gap-closure plan.}
+{--gaps → read @.planning/phase-{N}-verification.md failures. Create gap-closure plan.}
 
 <relevant_learnings>
-{inline any applicable patterns from knowledge/learned-patterns.md}
+{applicable patterns from knowledge/learned-patterns.md}
 </relevant_learnings>
 
-Create the plan at .planning/phase-{N}-plan.md (or .planning/phase-{N}-gaps-plan.md for --gaps).
+Output: .planning/phase-{N}-plan.md (or phase-{N}-gaps-plan.md for --gaps).
 ", subagent_type="qualia-planner", description="Plan phase {N}")
 ```
 
-### 4. Validate the Plan (unless --skip-check)
+### 4. Validate Plan (unless --skip-check)
 
-Read the generated plan. Spawn the plan-checker:
+Read generated plan. Spawn checker:
 
 ```
 Agent(prompt="
-Read your role: @~/.claude/agents/plan-checker.md
-Grounding + rubrics: @~/.claude/rules/grounding.md
+Role: @~/.claude/agents/plan-checker.md
 
 <plan_path>.planning/phase-{N}-plan.md</plan_path>
 <phase_goal>{goal from ROADMAP.md}</phase_goal>
 <success_criteria>{criteria from ROADMAP.md}</success_criteria>
 <project_context>@.planning/PROJECT.md</project_context>
 
-Validate against the 7 rules. Return PASS or REVISE with structured issues.
+Validate against 7 rules. Return PASS or REVISE with structured issues.
 ", subagent_type="qualia-plan-checker", description="Check plan phase {N}")
 ```
 
-**Revision loop (max 2 iterations):**
+**Revision loop (max 2):**
 
-- Iteration 1: Check → if REVISE, re-spawn planner with checker issues
-- Iteration 2: Re-check → if REVISE or BLOCKED, escalate to user
+- Iter 1: Check → REVISE → re-spawn planner with checker issues
+- Iter 2: Re-check → REVISE/BLOCKED → escalate to user
 
-Rationale: Amazon/NeurIPS 2025 measured reflection gains at 74→86% for 1 round, 88% for 3 rounds. Iteration 3 only added 2pp over iteration 1 — not worth the extra planner spawn (serial cost ~30-60s).
+(74→86% after 1 round, 88% after 3. Iter 3 adds only 2pp; not worth extra spawn.)
 
-For each revision:
+Per revision:
 
 ```
 Agent(prompt="
-Read your role: @~/.claude/agents/planner.md
+Role: @~/.claude/agents/planner.md
 
 <revision_mode>true</revision_mode>
 <current_plan>@.planning/phase-{N}-plan.md</current_plan>
 <checker_feedback>
-{inline REVISE output from plan-checker}
+{REVISE output from plan-checker}
 </checker_feedback>
 
-Revise the plan in place. Address every issue. Do NOT add new tasks or change scope
-— only fix what the checker flagged.
+Revise in place. Address every issue. Do NOT add tasks or change scope; fix only what checker flagged.
 ", subagent_type="qualia-planner", description="Revise plan phase {N}")
 ```
 
-After revision, spawn the checker again. Max 2 total revision cycles.
+After revision, re-spawn checker. Max 2 total cycles.
 
-**If checker returns BLOCKED after 2 cycles:**
+**BLOCKED after 2 cycles:**
 
 ```bash
 node ~/.claude/bin/qualia-ui.js fail "Plan failed validation after 2 revisions"
 ```
 
-Show the remaining issues. Ask:
-- "Skip validation and proceed anyway" (use `--skip-check`)
-- "Adjust the roadmap" (phase scope may be wrong)
-- "Adjust the phase goal" (success criteria may be under-specified)
+Show remaining issues. Options:
+- "Skip validation" (`--skip-check`)
+- "Adjust roadmap" (scope wrong)
+- "Adjust phase goal" (criteria under-specified)
 
 ### 5. Present Final Plan
 
-Render the story-file dashboard — this is a single command that parses the plan and shows the phase goal, waves, tasks, personas, dependencies, acceptance-criteria counts, and validation counts:
+Render story-file dashboard:
 
 ```bash
 node ~/.claude/bin/qualia-ui.js plan-summary .planning/phase-{N}-plan.md
@@ -184,19 +177,19 @@ If "adjust" — get feedback, re-spawn planner with revision context, re-validat
 node ~/.claude/bin/state.js transition --to planned --phase {N}
 ```
 
-If state.js returns an error, show it and stop. Do NOT manually edit STATE.md or tracking.json.
+Error → show, stop. Do NOT edit STATE.md or tracking.json manually.
 
 ### 7. Route (auto-chain aware)
 
-**If invoked with `--auto`:** immediately invoke `/qualia-build {N} --auto` inline. The user already approved the whole journey at `/qualia-new` time — no additional approval needed per phase plan.
+**`--auto`:** invoke `/qualia-build {N} --auto` inline. User approved at `/qualia-new`; no per-phase gate.
 
 ```bash
 node ~/.claude/bin/qualia-ui.js info "Auto mode — chaining into /qualia-build {N}"
 ```
 
-Then invoke the `qualia-build` skill inline with `--auto`.
+Then invoke `qualia-build` inline with `--auto`.
 
-**Otherwise (guided mode):** stop and show the next step:
+**Guided mode:** stop, show next step:
 
 ```bash
 node ~/.claude/bin/qualia-ui.js end "PHASE {N} PLANNED" "/qualia-build {N}"
@@ -204,22 +197,22 @@ node ~/.claude/bin/qualia-ui.js end "PHASE {N} PLANNED" "/qualia-build {N}"
 
 ## Gap Closure Mode (`--gaps`)
 
-When invoked as `/qualia-plan {N} --gaps`, the planner is in gap-closure mode:
+With `--gaps`, planner enters gap-closure mode:
 
-1. Read `.planning/phase-{N}-verification.md` — extract ONLY the FAIL items
-2. For each FAIL item, create a targeted fix task:
-   - **Files:** specific files that failed verification
-   - **Action:** specific fix (not "fix auth" — "add session persistence check in src/lib/auth.ts signIn function")
-   - **Acceptance Criteria:** the exact verification criterion that previously failed, restated as an observable behavior
-3. Do NOT re-plan passing items. Do NOT add new features. Gap plans are surgical.
-4. Write to `.planning/phase-{N}-gaps-plan.md` (separate from original plan)
-5. All gap tasks are Wave 1 (parallel) unless they share files
-6. Plan-checker still validates the gap plan — same 7 rules apply
+1. Read `.planning/phase-{N}-verification.md` → extract ONLY FAIL items
+2. Per FAIL, create targeted fix task:
+   - **Files:** specific files that failed
+   - **Action:** specific fix (not "fix auth"; "add session persistence check in src/lib/auth.ts signIn fn")
+   - **AC:** failed criterion restated as observable behavior
+3. Do NOT re-plan passing items. No new features. Surgical only.
+4. Output: `.planning/phase-{N}-gaps-plan.md`
+5. All gap tasks Wave 1 (parallel) unless they share files
+6. Plan-checker still validates; same 7 rules
 
 ## Rules
 
-1. **Plan-checker is mandatory by default.** Only skip with `--skip-check`, and only if you know what you're doing.
-2. **Max 3 revision cycles.** After 3 failed checks, escalate — the phase scope is probably wrong.
-3. **Honor locked decisions.** If phase-{N}-context.md exists, its locked decisions are non-negotiable.
-4. **One plan file per phase.** Don't create phase-1-plan.md AND phase-1-plan-v2.md. Edit in place.
-5. **Revision is surgical.** When revising, only fix what the checker flagged — no scope creep.
+1. **Plan-checker mandatory by default.** Skip only with `--skip-check`.
+2. **Max 3 revision cycles.** 3 fails → escalate; scope probably wrong.
+3. **Honor locked decisions.** phase-{N}-context.md locked decisions non-negotiable.
+4. **One plan file per phase.** No phase-1-plan-v2.md. Edit in place.
+5. **Revision is surgical.** Fix only what checker flagged; no scope creep.