qualia-framework 4.0.3 → 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-new/SKILL.md

@@ -21,8 +21,9 @@ Initialize a project with the **entire arc mapped from kickoff to handoff**. All
 
 ## Flags
 
-- `/qualia-new` — full-journey flow, stops after approval (default, backward-compatible)
+- `/qualia-new` — full-journey flow, stops after approval (default, backward-compatible). **Progressive detail**: Milestone 1 gets full phase detail; M2..M{N-1} get sketched (names + one-line goals). Full detail for later milestones is filled in by `/qualia-milestone` when each one opens. This matches how real projects unfold — M1's discoveries reshape M3's plan, so deep-planning M3 now tends to waste effort.
 - `/qualia-new --auto` — full-journey flow, then auto-chains into `/qualia-plan 1 → /qualia-build → /qualia-verify` for Milestone 1
+- `/qualia-new --full-detail` — ALL milestones get full phase-level detail upfront (success criteria per phase for every milestone, not just M1). Use when the client wants a fully-committed plan at kickoff. Trade-off: later milestones often need revision as M1 ships. Combinable with `--auto`.
 - `/qualia-new --quick` — 4-phase flat wizard for trivial projects (landing pages, prototypes). Skips research and journey mapping.
 
 ## The Shift From Previous Versions
@@ -238,7 +239,7 @@ Gather any additional requirements the user wants that research missed.
 node ~/.claude/bin/qualia-ui.js banner roadmap
 ```
 
-Spawn the roadmapper with full-journey mandate:
+Spawn the roadmapper with full-journey mandate. If the user passed `--full-detail`, include `<full_detail>true</full_detail>` in the prompt so the roadmapper writes complete phase detail for ALL milestones.
 
 ```
 Agent(prompt="
@@ -248,7 +249,7 @@ Read your role: @~/.claude/agents/roadmapper.md
 Create the FULL JOURNEY for this project:
   - .planning/JOURNEY.md — all milestones (2-5 including Handoff) with exit criteria
   - .planning/REQUIREMENTS.md — requirements grouped by milestone
-  - .planning/ROADMAP.md — Milestone 1's phase detail only (ready for /qualia-plan 1)
+  - .planning/ROADMAP.md — Milestone 1's phase detail (and ALL milestones if full_detail=true)
 
 User-scoped v1 features:
 {list of features selected in Step 9, grouped by category}
@@ -256,6 +257,10 @@ User-scoped v1 features:
 Template type: {template_type from config.json}
 If set, use ~/.claude/qualia-templates/projects/{type}.md as the milestone arc starting point.
 
+<full_detail>{true if --full-detail, else false}</full_detail>
+  - false (default): Milestone 1 gets full phase detail; M2..M{N-1} stay as sketches. Detail fills in when each milestone opens via /qualia-milestone.
+  - true: every milestone (M1..Handoff) gets full phase-level detail in ROADMAP.md upfront. Useful when the client wants a fully-committed plan at kickoff.
+
 The final milestone MUST be named 'Handoff' with the fixed 4 phases
 (Polish, Content + SEO, Final QA, Handoff). Do not omit it.
 
@@ -331,6 +336,16 @@ git add .planning/JOURNEY.md .planning/REQUIREMENTS.md .planning/ROADMAP.md .pla
 git commit -m "docs: journey + requirements + milestone 1 roadmap ({N} milestones)"
 ```
 
+**After approval, show the progressive-detail reminder explicitly:**
+
+```bash
+node ~/.claude/bin/qualia-ui.js info "Milestone 1 is fully planned now."
+node ~/.claude/bin/qualia-ui.js info "Milestones 2..{N-1} are sketched (names + one-line goals)."
+node ~/.claude/bin/qualia-ui.js info "Full phase detail for each later milestone gets written when /qualia-milestone opens it."
+```
+
+(Skip this block when `--full-detail` was used — all milestones are already fully planned in that case.)
+
 ### Step 13. Environment Setup
 
 Supabase project? `supabase link` or create. Vercel project? `vercel link`. Env vars? `.env.local` with placeholders from PROJECT.md stack.

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: