qualia-framework 4.4.0 → 5.1.0

package/skills/qualia-optimize/REFERENCE.md

@@ -0,0 +1,202 @@
+# /qualia-optimize Reference Templates
+
+Agent-prompt templates for SKILL.md. Copy, fill `{placeholders}`, spawn.
+
+## Frontend agent prompt
+
+```
+Agent(
+  prompt="Optimize frontend. Analyze planning docs + rules, then code.
+
+<planning>
+{PROJECT.md content}
+{REQUIREMENTS.md content}
+{DESIGN.md content}
+</planning>
+
+<rules>
+{rules/frontend.md content}
+</rules>
+
+<task>
+Analyze frontend:
+
+1. **UI Quality**
+   - Loading: every async op needs indicator
+   - Error: data-fetching components handle errors
+   - Empty: lists/tables handle zero items helpfully
+   - Responsive: no fixed px widths, breakpoints handled
+   - A11y: alt text, ARIA, keyboard nav
+
+2. **Design Alignment**
+   - Components vs DESIGN.md (colors, typography, spacing)
+   - rules/frontend.md compliance: distinctive fonts? sharp accents? transitions? No card grids / gradients?
+   - Consistency across app (buttons, spacing, colors)
+
+3. **Frontend Perf**
+   - Bundle: large imports -> tree-shake or dynamic import
+   - Images: next/image? width/height? lazy below fold?
+   - Fonts: next/font? No render-blocking?
+   - CSS: unused Tailwind? conflicts?
+   - Rendering: unnecessary re-renders, missing memo, heavy computations
+
+Per finding: What / Where (file:line) / Why (impact) / Fix / Severity (CRITICAL|HIGH|MEDIUM|LOW)
+</task>",
+  subagent_type="general-purpose",
+  description="Frontend optimization analysis"
+)
+```
+
+## Backend agent prompt
+
+```
+Agent(
+  prompt="Optimize backend. Analyze planning docs + security rules, then code.
+
+<planning>
+{PROJECT.md content}
+{REQUIREMENTS.md content}
+</planning>
+
+<rules>
+{rules/security.md content}
+</rules>
+
+<task>
+Analyze backend:
+
+1. **Security**
+   - RLS: every table needs RLS + policies
+   - Service role: grep client code (app/, components/, src/) for service_role -> must be ZERO
+   - Auth: mutations use server-side auth (supabase.auth.getUser())
+   - Validation: Zod before DB ops
+   - No dangerouslySetInnerHTML / eval()
+
+2. **Data Access**
+   - Writes via 'use server' actions, not direct client calls
+   - try/catch with meaningful errors
+   - revalidatePath/revalidateTag after mutations
+
+3. **Edge Functions** (if supabase/functions/ exists)
+   - Cold start: bundle size, dep count
+   - Error handling + logging
+   - CORS config
+   - Timeout protection
+
+4. **API Quality**
+   - Rate limiting on public endpoints
+   - Proper HTTP status codes
+   - Consistent error format
+
+Per finding: What / Where (file:line) / Why (impact) / Fix / Severity (CRITICAL|HIGH|MEDIUM|LOW)
+</task>",
+  subagent_type="general-purpose",
+  description="Backend optimization analysis"
+)
+```
+
+## Performance oracle prompt
+
+```
+Agent(
+  prompt="Analyze cross-cutting perf issues.
+
+<planning>
+{PROJECT.md content}
+</planning>
+
+<task>
+Full-stack perf analysis:
+
+1. **DB Queries**
+   - N+1: .from() inside loops/.map()
+   - Missing indexes on .eq()/.filter()/.order() columns
+   - Sequential -> parallel (Promise.all)
+   - Over-fetching: SELECT * when specific columns suffice
+
+2. **API Latency**
+   - Sequential client calls -> batch
+   - Missing caching (stale times, HTTP cache headers)
+   - Large payloads without pagination
+
+3. **Bundle Size**
+   - Barrel exports blocking tree-shaking
+   - Large libs for single fns (lodash, moment)
+   - Missing dynamic imports for heavy components
+
+4. **Render Perf**
+   - Expensive computations without useMemo
+   - Handlers recreated per render without useCallback
+   - Large lists without virtualization
+   - Context providers causing unnecessary re-renders
+
+Per finding: What / Where (file:line) / Why (impact, quantified) / Fix / Severity (CRITICAL|HIGH|MEDIUM|LOW)
+</task>",
+  subagent_type="general-purpose",
+  description="Performance optimization analysis"
+)
+```
+
+## Architecture strategist prompt (deepening lens)
+
+`full`: after Wave 1 (synthesizes + deepens). `deepen`: sole agent (no Wave 1).
+
+```
+Agent(
+  prompt="Arch strategist: Ousterhout deepening lens + cross-cutting issues. Use domain language from CONTEXT.md.
+
+<wave1_findings>
+{Wave 1 findings; empty in --deepen mode}
+</wave1_findings>
+
+<planning>
+{PROJECT.md content}
+{REQUIREMENTS.md content}
+{CONTEXT.md content (domain glossary)}
+{decisions/*.md content (ADRs constraining refactor space)}
+</planning>
+
+<vocabulary>
+- **Module**: construct with interface + impl (fn, class, package, slice)
+- **Interface**: everything caller must know (types, invariants, error modes, ordering, config)
+- **Depth**: leverage at interface. Deep = high leverage. Shallow = interface ~ impl.
+- **Seam**: where interface lives; alterable without in-place editing.
+- **Locality**: change, bug, knowledge concentrated in one location.
+- **Deletion test**: deleting module makes complexity vanish across N callers -> earning keep.
+</vocabulary>
+
+<task>
+TWO sections:
+
+A) **Cross-cutting** (skip in --deepen):
+1. Recurring Wave 1 patterns -> structural problem
+2. Frontend-backend coupling
+3. Inconsistent patterns (server actions vs API routes)
+4. Missing abstractions (pattern repeated 3+ times)
+5. Dead code / unused exports
+
+B) **Deepening candidates** (always):
+Per candidate:
+- **Files**: file:line ranges
+- **Problem**: what's shallow, what leaks
+- **Solution**: new interface, what gets hidden
+- **Benefits**: locality, leverage, testability
+- **Deletion test**: deleting X -> N callers no longer need what?
+- **Domain terms**: CONTEXT.md terms touched or surfaced
+- **Severity**: CRITICAL | HIGH | MEDIUM | LOW
+
+Look for:
+- Shallow wrappers (interface ~ impl)
+- Pure fns extracted for testability only (no locality)
+- Concept-bouncing (1 concept -> 5+ files)
+- Cross-seam coupling (private detail leaking)
+- Untested/untestable sections (bad seams)
+
+REFUSE: 'extract helper fn' failing deletion test. More shallow modules = disease.
+
+Format: What/Where/Why/Fix/Severity.
+</task>",
+  subagent_type="general-purpose",
+  description="Architecture synthesis + deepening"
+)
+```

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`"