qualia-framework 4.0.5 → 4.1.0

package/skills/qualia-debug/SKILL.md

@@ -1,93 +1,185 @@
 ---
 name: qualia-debug
-description: "Structured debugging — symptom gathering, diagnosis confirmation, root cause analysis. Trigger on 'debug', 'find bug', 'fix error', 'something is broken', 'not working', 'weird behavior', 'layout broken', 'CSS issue', 'slow page', 'performance'."
+description: "Investigative debugging — parses symptom from arguments, runs diagnostic scans, identifies root cause, applies minimal fix, writes DEBUG report. Trigger on 'debug', 'find bug', 'fix error', 'something is broken', 'not working', 'weird behavior', 'layout broken', 'CSS issue', 'slow page', 'performance'."
 allowed-tools:
   - Bash
   - Read
+  - Edit
+  - Write
   - Grep
   - Glob
   - Agent
 ---
 
-# /qualia-debug — Structured Debugging
+# /qualia-debug — Investigative Debugging (one-shot)
 
-Systematic debugging. Don't guess — gather symptoms, confirm diagnosis, then fix.
+Parse the symptom. Run diagnostics. Find root cause. Apply minimal fix. Write report. **One-shot — no mandatory user questions.**
 
 ## Usage
 
-- `/qualia-debug` — Interactive (gather symptoms, diagnose, fix)
-- `/qualia-debug --frontend` — CSS/layout/visual issues
-- `/qualia-debug --perf` — Performance issues
+- `/qualia-debug {symptom}` — investigate a specific symptom
+- `/qualia-debug` — no symptom given: investigate recently-changed files for obvious bugs
+- `/qualia-debug --frontend {symptom}` — layout/z-index/overflow bias
+- `/qualia-debug --perf {symptom}` — performance bias
 
-## Interactive Mode (Default)
+## Tool Budget
+
+Max 10 Read/Grep/Bash calls for investigation. If you haven't narrowed to root cause in 10, return `INSUFFICIENT EVIDENCE after 10 steps. Narrowed to: {files}. Recommend: {next diagnostic}.` Do not keep guessing.
+
+## Process
 
 ```bash
 node ~/.claude/bin/qualia-ui.js banner debug
 ```
 
-### 0. Check Known Fixes First
+### 1. Parse Symptom from $ARGUMENTS
+
+- If arguments provided → that's the symptom. Extract: what's broken, where (file/page/feature), when (on click? on load? after change?).
+- If arguments empty → run `git diff HEAD~3 --stat` to find recently-touched files. Treat those as the suspect set. Symptom = "something in recent changes".
+
+### 2. Check Known Fixes First (cheap)
+
+```bash
+cat ~/.claude/knowledge/common-fixes.md 2>/dev/null | grep -i "{symptom_keywords}"
+```
+
+If a known fix matches, apply it and jump to step 5 (verify). Known fixes are pre-verified patterns — no need to re-investigate.
+
+### 3. Diagnostic Scan
+
+Run the scan matching the symptom type. All commands in a scan block run as parallel Bash calls in a single response turn.
+
+**General mode (default):**
+```bash
+# Compile errors
+npx tsc --noEmit 2>&1 | grep "error TS" | head -20
+
+# Empty catch / swallowed errors
+grep -rn "catch\s*{}\|catch\s*(.*)\s*{\s*}" --include="*.ts" --include="*.tsx" app/ components/ src/ lib/ 2>/dev/null | head -10
+
+# Recent console.error or thrown errors
+grep -rn "console\.error\|throw new" --include="*.ts" --include="*.tsx" app/ components/ src/ lib/ 2>/dev/null | head -10
+
+# Broken imports
+npx tsc --noEmit 2>&1 | grep -i "Cannot find module\|has no exported"
+```
+
+**Frontend mode (`--frontend`):**
+```bash
+# Stacking context audit (z-index issues)
+grep -rn "z-index\|z-\[" --include="*.tsx" --include="*.css" app/ components/ src/ 2>/dev/null | head -20
+
+# Overflow candidates (horizontal scroll, clipping)
+grep -rn "100vw\|overflow.*hidden\|overflow-x\|position.*fixed" --include="*.tsx" --include="*.css" app/ components/ src/ 2>/dev/null | head -15
+
+# Fixed dimensions breaking mobile
+grep -rn "width:.*[0-9]\+px\|height:.*[0-9]\+px\|w-\[[0-9]\+px\|h-\[[0-9]\+px" --include="*.tsx" --include="*.css" app/ components/ src/ 2>/dev/null | grep -v "min-\|max-" | head -10
+
+# Flex/grid blowout candidates
+grep -rn "flex\|grid" --include="*.tsx" app/ components/ src/ 2>/dev/null | grep -v "min-w-0\|minmax(0" | wc -l
+```
+
+**Perf mode (`--perf`):**
+```bash
+# Sequential awaits that should be Promise.all
+grep -rn "const.*=.*await" --include="*.tsx" --include="*.ts" app/ src/ 2>/dev/null | grep -v "Promise.all\|Promise.allSettled" | head -15
+
+# Large files
+find app/ components/ src/ -name "*.tsx" -o -name "*.ts" 2>/dev/null | xargs wc -l 2>/dev/null | sort -rn | head -10
+
+# Missing next/image
+grep -rn "<img " --include="*.tsx" --include="*.jsx" app/ components/ src/ 2>/dev/null | grep -v "next/image" | wc -l
+
+# No dynamic imports (possible big bundles)
+grep -rn "import(\|next/dynamic" --include="*.tsx" --include="*.ts" app/ src/ 2>/dev/null | wc -l
+
+# Client-boundary usage
+grep -rln "'use client'" --include="*.tsx" app/ components/ src/ 2>/dev/null | wc -l
+```
 
-Before gathering symptoms, check if we've seen this before:
+### 4. Form Hypothesis + Apply Minimal Fix
+
+From the diagnostic output, state the root cause in one sentence with `file:line` citation. No hedging — either you have evidence or you write `INSUFFICIENT EVIDENCE` and return (step 6).
+
+Apply the minimal fix:
+- Only edit files whose contents caused the symptom
+- One concept per commit — don't fold in cleanup
+- Don't refactor adjacent code
+- If the fix touches > 3 files, stop and ask the user first (major refactor disguised as a debug)
+
+### 5. Verify Fix
 
 ```bash
-cat ~/.claude/knowledge/common-fixes.md 2>/dev/null
+# TypeScript still compiles?
+npx tsc --noEmit 2>&1 | grep -c "error TS"   # Expect 0
+
+# Symptom reproduction — ideally a grep that would have matched the bug
+# and now returns empty:
+grep -rn "{pattern that represented the bug}" {scope} 2>/dev/null
 ```
 
-If the user's description matches a known fix, suggest it first: *"I've seen this before — check {fix title}. Want to try that before we dig deeper?"* Only proceed to full investigation if the known fix doesn't apply.
+If the verification fails, revert and return to step 3 with narrower hypothesis.
 
-### 1. Gather Symptoms
+### 6. Write DEBUG Report
 
-Ask:
-- What's happening? (exact error or behavior)
-- What should happen instead?
-- When did it start? (after what change?)
-- What have you tried?
+Write to `.planning/DEBUG-{YYYY-MM-DD-HHMM}.md`:
 
-### 2. Confirm Diagnosis
+```markdown
+# Debug Report — {YYYY-MM-DD HH:MM}
 
-Before ANY code changes, present your diagnosis:
+**Symptom:** {user description or "recent changes" if no args}
+**Mode:** general | frontend | perf
+**Tool calls used:** {N}/10
 
-> "Based on the symptoms, I think: [diagnosis]. I'll investigate [specific area]. Does that match what you're seeing?"
+## Investigation
+- Diagnostic scans run: {list}
+- Files examined: {list}
+- Patterns searched: {list}
 
-Wait for confirmation. If user corrects → adjust. Never proceed on a wrong diagnosis.
+## Root Cause
+{file:line} — "{quoted problematic code}" — {explanation of why it caused the symptom}
 
-### 3. Investigate and Fix
+## Fix Applied
+- Files: {list}
+- Diff summary: {one paragraph}
+- Verification: {commands run + results}
 
-1. Reproduce the issue
-2. Isolate the cause (binary search: which file, which function, which line)
-3. Identify root cause (not symptoms)
-4. Implement minimal fix
-5. Verify fix works
-6. Check for related issues
+## Related Observations
+- {any adjacent issues noticed but NOT fixed in this debug pass}
+```
 
-### 4. Commit
+### 7. Commit
 
 ```bash
-git add {specific files}
+git add {specific files you changed}
 git commit -m "fix: {what was broken and why}"
 ```
 
-## Frontend Mode (`--frontend`)
+## INSUFFICIENT EVIDENCE Return
 
-For layout breaks, z-index issues, overflow, animation glitches.
+If you exhaust the 10-call budget without a confident root cause:
 
-**Quick diagnostics:**
-- Z-index not working → element needs `position: relative/absolute/fixed`, check parent stacking contexts
-- Horizontal scroll → use `width: 100%` not `100vw`, find overflowing element
-- Flex overflow → add `min-width: 0`
-- Grid blowout → use `minmax(0, 1fr)`
-- Janky animations → only animate `transform` and `opacity`
-- Safari → `-webkit-backdrop-filter`, `100dvh` not `100vh`
+```markdown
+# Debug Report — {YYYY-MM-DD HH:MM}
+
+**Symptom:** {description}
+**Outcome:** INSUFFICIENT EVIDENCE after 10 inspection steps
+
+## Narrowed To
+- Files examined: {list}
+- Ruled out: {list}
+- Remaining suspects: {list}
+
+## Recommended Next Diagnostic
+- {specific next step for the user — e.g., "run `npm run dev` and watch browser console for the specific error", or "add console.log at file:line and reproduce"}
+```
 
-## Performance Mode (`--perf`)
+Do NOT apply a speculative fix. Return the report and stop.
 
-### Investigate
-1. Profile the bottleneck (network, render, compute, database)
-2. Measure baseline
-3. Identify the hot path
+## Rules
 
-### Common fixes
-- Slow queries → check indexes, `EXPLAIN ANALYZE`, optimize joins
-- Large bundles → code split, lazy load, tree shake
-- Slow renders → memoize, virtualize long lists
-- API latency → cache, reduce payload, parallelize requests
+- **No mandatory questions.** This is one-shot. If symptom args are missing, investigate recent changes.
+- **Root cause or INSUFFICIENT EVIDENCE** — no "probably" fixes.
+- **Minimal fix only.** One concept, one commit. No refactors dressed as debug.
+- **Tool budget is hard.** 10 calls, then stop.
+- **Every fix gets a DEBUG report in .planning/** — creates a searchable record.

package/skills/qualia-design/SKILL.md

@@ -41,13 +41,49 @@ If DESIGN.md exists → it is law. Use exact values from sections 1-9 (Visual Th
 - If `--scope`: grep for matching files in `app/` and `components/`
 - If none: find all `page.tsx`, `layout.tsx`, and component files
 
-Read EVERY target file before modifying.
+Count them. If ≤ 5, process in main context (step 3a). If > 5, fan out to parallel agents (step 3b).
 
-### 3. Critique (internal — don't output)
+### 3a. Small File Set (≤ 5 files) — main context
 
-Evaluate each file on: AI slop detection, visual hierarchy, typography, color, states (loading/error/empty), motion, spacing, responsiveness, microcopy.
+Read EVERY target file before modifying. Critique internally using the structured rubric below, then fix everything (step 4).
 
-### 4. Fix Everything
+**Critique rubric (required — produces the findings you then fix):**
+
+| File | Dimension | Issue | Line | Severity |
+|------|-----------|-------|------|----------|
+| {path} | Typography/Color/Spacing/States/Responsive/A11y/Motion/Microcopy | {specific problem with quote} | {N} | CRITICAL/HIGH/MEDIUM/LOW |
+
+Apply fixes to every HIGH and CRITICAL item. MEDIUM items fixed if cheap (same file, same category).
+
+### 3b. Large File Set (> 5 files) — parallel fan-out
+
+Split target files into batches of 5. Spawn one Agent per batch IN THE SAME RESPONSE TURN (parallel execution). Each agent receives DESIGN.md inlined + its 5 files + the Design Quality Rubric from `rules/grounding.md`. Agents return their batch's critique table + the actual edits applied. The skill orchestrator fans in the results and runs the final verification (step 5).
+
+```
+Agent(prompt="
+Read your role: builder for design transformation.
+Grounding + rubrics: @~/.claude/rules/grounding.md
+
+<design_system>
+{inlined DESIGN.md}
+</design_system>
+
+<target_files>
+{5 file paths + their contents}
+</target_files>
+
+Apply the Design Quality Rubric to each file. Fix every dimension scoring below 4. Make the literal edits with the Edit tool. Do NOT change logic — only styling.
+
+Return:
+- Critique table (File | Dimension | Issue | Line | Before-score | After-score)
+- List of files modified
+- Any anti-pattern greps that remain (report, don't fix beyond scope)
+", subagent_type="general-purpose", description="Design batch {N}")
+```
+
+Do not process files serially in main context — that's what wastes a context window.
+
+### 4. Fix Everything (applies to step 3a OR to each agent in 3b)
 
 Use exact values from DESIGN.md when available. Sections map to fixes:
 
@@ -73,11 +109,21 @@ Use exact values from DESIGN.md when available. Sections map to fixes:
 
 ### 5. Verify
 
+Parallel batch — run these in a single response turn:
+
 ```bash
+# TypeScript still compiles?
 npx tsc --noEmit 2>&1 | head -20
+
+# Reverted anti-patterns (any match = regression)
+grep -rn "outline.*none\|outline-none" --include="*.tsx" --include="*.css" app/ components/ src/ 2>/dev/null | grep -v "focus-visible\|focus:"
+grep -rn "font-family.*Inter\|font-family.*Arial\|font-family.*system-ui\|Space Grotesk" --include="*.tsx" --include="*.css" app/ components/ src/ 2>/dev/null
+grep -rn "max-w-\[1200\|max-w-\[1280\|max-width.*1200\|max-w-7xl" --include="*.tsx" --include="*.css" app/ components/ src/ 2>/dev/null
+grep -rn "<img " --include="*.tsx" app/ components/ src/ 2>/dev/null | grep -v "alt="
+grep -rn "from-blue.*to-purple\|from-purple.*to-blue" --include="*.tsx" --include="*.css" app/ components/ src/ 2>/dev/null
 ```
 
-Fix any TypeScript errors before committing.
+Fix any TypeScript errors before committing. If any anti-pattern grep returned matches, re-fix those files — the transformation is not complete until these greps return empty.
 
 ### 6. Commit
 
@@ -105,3 +151,4 @@ git commit -m "style: design transformation"
 - Respect DESIGN.md decisions
 - Don't break functionality — only change styling, never logic
 - TypeScript must pass after changes
+- All anti-pattern greps in step 5 must return empty before commit

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 3), optionally runs discuss/research first. Use when ready to plan a phase."
+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."
 allowed-tools:
   - Bash
   - Read
@@ -15,7 +15,7 @@ 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 3 revision cycles) before routing to build.
+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.
 
 ## Usage
 
@@ -73,6 +73,7 @@ Spawn the planner:
 ```
 Agent(prompt="
 Read your role: @~/.claude/agents/planner.md
+Grounding + rubrics: @~/.claude/rules/grounding.md
 
 <project_context>
 @.planning/PROJECT.md
@@ -116,6 +117,7 @@ Read the generated plan. Spawn the plan-checker:
 ```
 Agent(prompt="
 Read your role: @~/.claude/agents/plan-checker.md
+Grounding + rubrics: @~/.claude/rules/grounding.md
 
 <plan_path>.planning/phase-{N}-plan.md</plan_path>
 <phase_goal>{goal from ROADMAP.md}</phase_goal>
@@ -126,11 +128,12 @@ Validate against the 7 rules. Return PASS or REVISE with structured issues.
 ", subagent_type="qualia-plan-checker", description="Check plan phase {N}")
 ```
 
-**Revision loop (max 3 iterations):**
+**Revision loop (max 2 iterations):**
 
 - Iteration 1: Check → if REVISE, re-spawn planner with checker issues
-- Iteration 2: Re-check → if REVISE, re-spawn planner with new issues
-- Iteration 3: Final check → if REVISE or BLOCKED, escalate to user
+- Iteration 2: Re-check → if REVISE or 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).
 
 For each revision:
 
@@ -149,12 +152,12 @@ Revise the plan in place. Address every issue. Do NOT add new tasks or change sc
 ", subagent_type="qualia-planner", description="Revise plan phase {N}")
 ```
 
-After revision, spawn the checker again. Max 3 total revision cycles.
+After revision, spawn the checker again. Max 2 total revision cycles.
 
-**If checker returns BLOCKED after 3 cycles:**
+**If checker returns BLOCKED after 2 cycles:**
 
 ```bash
-node ~/.claude/bin/qualia-ui.js fail "Plan failed validation after 3 revisions"
+node ~/.claude/bin/qualia-ui.js fail "Plan failed validation after 2 revisions"
 ```
 
 Show the remaining issues. Ask:

package/skills/qualia-review/SKILL.md

@@ -40,9 +40,11 @@ ls package.json next.config.* tsconfig.json supabase/ app/ src/ 2>/dev/null
 
 ### 1. Security Scan
 
-Run every command. Record each finding with severity.
+**Run the independent greps as parallel Bash calls in a single response** (they don't depend on each other — serial execution wastes 15-30s on large codebases). Only the `find … | for` loops are sequential.
 
 ```bash
+# PARALLEL BATCH (issue these in one response turn):
+
 # CRITICAL: service_role in client code
 grep -rn "service_role" --include="*.ts" --include="*.tsx" --include="*.js" app/ components/ src/ lib/ 2>/dev/null | grep -v node_modules | grep -v "\.server\.\|[\\/]server[\\/]\|[\\/]app[\\/]api[\\/]\|route\.\|middleware\."
 
@@ -55,21 +57,26 @@ grep -rn "dangerouslySetInnerHTML\|eval(" --include="*.ts" --include="*.tsx" --i
 # CRITICAL: .env files tracked in git
 git ls-files | grep -i "\.env" | grep -v "\.example\|\.template\|\.sample"
 
+# HIGH: client-side database mutations
+grep -rn "\.insert\|\.update\|\.delete\|\.upsert" --include="*.tsx" --include="*.jsx" app/ components/ 2>/dev/null | grep -v "use server" | grep -v "\.server\."
+
+# MEDIUM: npm vulnerabilities
+npm audit --json 2>/dev/null | node -e "try{const d=JSON.parse(require('fs').readFileSync(0,'utf8'));const v=d.metadata?.vulnerabilities||{};console.log('critical:',v.critical||0,'high:',v.high||0,'moderate:',v.moderate||0)}catch{console.log('audit unavailable')}"
+
+# END PARALLEL BATCH
+
+# SEQUENTIAL (depends on find):
 # HIGH: API routes without auth
 for f in $(find app/api -name "route.ts" -o -name "route.js" 2>/dev/null); do
-  grep -qL "getUser\|getSession\|auth()\|createClient" "$f" && echo "UNPROTECTED: $f"
+  if ! grep -q "getUser\|getSession\|auth()\|createClient" "$f" 2>/dev/null; then
+    echo "UNPROTECTED: $f"
+  fi
 done
 
 # HIGH: API routes without input validation
 for f in $(find app/api -name "route.ts" -o -name "route.js" 2>/dev/null); do
   grep -L "z\.\|zod\|Zod\|parse\|safeParse" "$f" 2>/dev/null
 done
-
-# HIGH: client-side database mutations
-grep -rn "\.insert\|\.update\|\.delete\|\.upsert" --include="*.tsx" --include="*.jsx" app/ components/ 2>/dev/null | grep -v "use server" | grep -v "\.server\."
-
-# MEDIUM: npm vulnerabilities
-npm audit --json 2>/dev/null | node -e "try{const d=JSON.parse(require('fs').readFileSync(0,'utf8'));const v=d.metadata?.vulnerabilities||{};console.log('critical:',v.critical||0,'high:',v.high||0,'moderate:',v.moderate||0)}catch{console.log('audit unavailable')}"
 ```
 
 ### 2. Code Quality Scan
@@ -94,8 +101,14 @@ grep -rn "console\.log" --include="*.ts" --include="*.tsx" app/ components/ src/
 ### 3. Performance Scan
 
 ```bash
-# Build output — route sizes and first load JS
-npx next build 2>&1 | grep -E "Route|First Load|shared by all|○|●|ƒ|λ" | tail -25
+# Build output — read existing build artifacts (don't trigger a fresh build during a scan)
+if [ -d ".next" ]; then
+  du -sh .next/static/chunks/*.js 2>/dev/null | sort -rh | head -10
+  echo "---"
+  find .next -name "*.js" -size +200k 2>/dev/null | head -5
+else
+  echo "No .next/ build output — run 'npx next build' separately for bundle analysis (review skill does NOT trigger builds — it's a scan)"
+fi
 
 # Heavy files (>300 lines often means split needed)
 find app/ components/ src/ -name "*.tsx" -o -name "*.ts" 2>/dev/null | xargs wc -l 2>/dev/null | sort -rn | head -10
@@ -144,12 +157,19 @@ Write to `.planning/REVIEW.md`:
 {PASS: no critical/high | FAIL: N blockers — fix before /qualia-ship}
 ```
 
-**Scoring:**
-- 5 = zero high/critical, fewer than 3 medium
-- 4 = zero critical, 1 high or fewer than 5 medium
-- 3 = zero critical, 2-3 high
-- 2 = 1 critical or 4+ high
-- 1 = multiple critical
+**Scoring (deterministic — see `rules/grounding.md` for full rubric):**
+```
+weighted_sum   = (critical × 8) + (high × 4) + (medium × 2) + (low × 1)
+category_score = max(1, 5 − floor(weighted_sum / 8))
+```
+Same inputs always produce the same score. No subjective thresholds.
+
+Quick reference (computed from the formula — verified):
+- 0 findings, or only LOW/MEDIUM, or 1 HIGH → 5
+- 2–3 HIGH, or 1 CRITICAL → 4
+- 2 CRITICAL, or 1 CRITICAL + 2–3 HIGH → 3
+- 3 CRITICAL, or 2 CRITICAL + 2+ HIGH → 2
+- 4+ CRITICAL → 1
 
 ```bash
 node ~/.claude/bin/qualia-ui.js divider

package/skills/qualia-skill-new/SKILL.md

@@ -161,7 +161,7 @@ git add skills/{name}/
 git commit -m "feat: add /{name} skill"
 ```
 
-Remind the user to run `npx qualia-framework update` on their other machines, or bump the version and `npm publish`.
+Remind the user to run `npx qualia-framework@latest update` on their other machines (always pin `@latest` — npx caches aggressively), or bump the version and `npm publish`.
 
 ## Anti-Patterns
 

package/skills/qualia-verify/SKILL.md

@@ -41,6 +41,10 @@ node ~/.claude/bin/qualia-ui.js spawn verifier "Goal-backward check..."
 ```
 Agent(prompt="
 Read your role: @~/.claude/agents/verifier.md
+Grounding + rubrics: @~/.claude/rules/grounding.md
+
+Project conventions (MUST consult before scoring Quality):
+@.planning/PROJECT.md
 
 Phase plan with success criteria AND verification contracts:
 @.planning/phase-{N}-plan.md
@@ -48,7 +52,7 @@ Phase plan with success criteria AND verification contracts:
 {If re-verification: Previous verification with gaps:}
 {@.planning/phase-{N}-verification.md}
 
-Verify this phase. Write report to .planning/phase-{N}-verification.md
+Verify this phase. Apply the Grounding Protocol — every finding needs file:line evidence. Use the Severity Rubric for all severity labels. Write report to .planning/phase-{N}-verification.md
 ", subagent_type="qualia-verifier", description="Verify phase {N}")
 ```