qualia-framework 4.5.0 → 5.3.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,74 @@ 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 |
+| `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) |
 
-**CRITICAL**: Inline ALL planning context into each agent prompt. `@` references don't work across Agent() boundaries.
+**CRITICAL**: Inline ALL planning context into each prompt. `@` refs don't work across Agent() boundaries.
 
-#### Frontend Agent Prompt
+Spawn parallel: **frontend** (@REFERENCE.md "Frontend agent prompt"), **backend** (@REFERENCE.md "Backend agent prompt"), **perf oracle** (@REFERENCE.md "Performance oracle prompt").
 
-```
-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"
-)
-```
+### Step 5: Wave 2 -- Architecture Strategist
 
-#### Backend Agent Prompt
+`full`: after Wave 1 (synthesizes + deepens). `deepen`: sole agent (no Wave 1).
 
-```
-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"
-)
-```
+Spawn **arch strategist** (@REFERENCE.md "Architecture strategist prompt (deepening lens)").
 
-#### Performance Oracle Prompt
+**Skip Wave 2 for single-mode** (`--perf`, `--ui`, `--backend`, `--alignment`). Run for `full` and `deepen`.
 
-```
-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"
-)
-```
+### Step 5b: Wave 3 -- Parallel Interface Design (`--deepen` only, after candidate selection)
 
-### Step 5: Spawn Wave 2 Agent (after Wave 1 completes)
+After the strategist returns deepening candidates, present a numbered list to the user. User picks ONE candidate (or `--auto` mode picks the highest-severity).
 
-After all Wave 1 agents return, spawn the architecture strategist with their combined findings:
+For the chosen candidate, spawn **3 fan-out agents in parallel, in the same response turn**, each producing a *radically different* interface design for the proposed deep module. From Matt Pocock's improve-codebase-architecture skill: "spawn three sub-agents in parallel, each must produce a radically different interface for the deepened module."
 
-```
-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 3 (@REFERENCE.md "Parallel interface design prompt"). Each receives:
+- The candidate's files, problem, and current shallow signature
+- CONTEXT.md domain glossary (use shared terms)
+- A *different* design constraint (functional / OOP / event-driven / minimal-surface / hexagonal — assigned per agent so the variants differ in shape, not just naming)
+
+Collect all 3 proposals. Present to the user as a side-by-side table:
 
-**Skip Wave 2 for single-mode runs** (`--perf`, `--ui`, `--backend`). Only run for `full` mode.
+| # | Interface shape | Locality gain | Testability | Migration cost |
+|---|---|---|---|---|
+| 1 | {sketch} | {what concentrates} | {seams} | {N callers updated} |
+| 2 | ... | ... | ... | ... |
+| 3 | ... | ... | ... | ... |
 
-### Step 6: Alignment Check (always runs in `full` and `alignment` modes)
+User picks `1`, `2`, `3`, or `hybrid` (with notes on which elements from which proposals to combine). The synthesizer then writes a "Refactor RFC" to `.planning/REFACTOR-{slug}.md` and optionally opens a GH issue (mirrors `/qualia-prd` flow).
 
-For `alignment` mode, this is the sole analysis. For `full` mode, run alongside Wave 1.
+**Why parallel + radically different**: a single deepening proposal anchors on the first idea the LLM has. Three parallel proposals with diverse design constraints surface trade-offs the user can see at a glance — and the human's "taste" dominates the choice rather than the agent's first instinct. Empirically (Matt Pocock + Qualia internal testing) this produces dramatically better refactor RFCs than a single-pass proposal.
 
-Read REQUIREMENTS.md and ROADMAP.md. For each requirement marked "Complete" or mapped to a completed phase:
+**Skip Wave 3 for `full` mode** (too many candidates to fan out per-candidate). Run for `--deepen` only when a candidate is selected.
+
+### Step 6: Alignment Check (`full` and `alignment` modes)
+
+`alignment`: sole analysis. `full`: alongside Wave 1.
+
+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 +175,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 +261,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`"