qualia-framework 6.2.9 → 6.2.10

package/skills/qualia-debug/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-debug
-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'."
+description: "Investigation lane for unclear bugs and weird behavior. Parses symptoms, runs diagnostic scans, identifies root cause, and either reports insufficient evidence or routes actionable repair work to /qualia-fix. Trigger on 'debug', 'find bug', 'why is this broken', 'something is weird', 'investigate', 'root cause', 'not sure what's failing', 'CSS issue', 'slow page', 'performance'."
 allowed-tools:
   - Bash
   - Read
@@ -13,7 +13,7 @@ allowed-tools:
 
 # /qualia-debug — Investigative Debugging (one-shot)
 
-Parse the symptom. Run diagnostics. Find root cause. Apply minimal fix. Write report. **One-shot — no mandatory user questions.**
+Parse the symptom. Run diagnostics. Find root cause. Write report, or route to `/qualia-fix` when the repair is actionable. **One-shot — no mandatory user questions.**
 
 ## Usage
 
@@ -22,6 +22,8 @@ Parse the symptom. Run diagnostics. Find root cause. Apply minimal fix. Write re
 - `/qualia-debug --frontend {symptom}` — layout/z-index/overflow bias
 - `/qualia-debug --perf {symptom}` — performance bias
 
+If the user says "fix it" and the expected behavior is known, prefer `/qualia-fix`. Debug is for uncertainty; fix is for repair.
+
 ## 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.
@@ -29,7 +31,7 @@ Max 10 Read/Grep/Bash calls for investigation. If you haven't narrowed to root c
 ## Process
 
 ```bash
-node ~/.claude/bin/qualia-ui.js banner debug
+node ${QUALIA_BIN}/qualia-ui.js banner debug
 ```
 
 ### 1. Parse Symptom from $ARGUMENTS
@@ -40,7 +42,7 @@ node ~/.claude/bin/qualia-ui.js banner debug
 ### 2. Check Known Fixes First (cheap)
 
 ```bash
-node ~/.claude/bin/knowledge.js search "{symptom_keywords}"
+node ${QUALIA_BIN}/knowledge.js search "{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.
@@ -97,10 +99,12 @@ grep -rn "import(\|next/dynamic" --include="*.tsx" --include="*.ts" app/ src/ 2>
 grep -rln "'use client'" --include="*.tsx" app/ components/ src/ 2>/dev/null | wc -l
 ```
 
-### 4. Form Hypothesis + Apply Minimal Fix
+### 4. Form Hypothesis + Route or 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).
 
+If the user explicitly asked for repair and the fix is <= 3 files, route to `/qualia-fix {symptom}` with the root cause summary. If this debug invocation is already mid-repair, apply the minimal fix here for backward compatibility.
+
 Apply the minimal fix:
 - Only edit files whose contents caused the symptom
 - One concept per commit — don't fold in cleanup
@@ -122,7 +126,11 @@ If the verification fails, revert and return to step 3 with narrower hypothesis.
 
 ### 6. Write DEBUG Report
 
-Write to `.planning/DEBUG-{YYYY-MM-DD-HHMM}.md`:
+Create the report directory and write to `.planning/reports/debug/DEBUG-{YYYY-MM-DD-HHMM}.md`:
+
+```bash
+mkdir -p .planning/reports/debug
+```
 
 ```markdown
 # Debug Report — {YYYY-MM-DD HH:MM}
@@ -180,6 +188,6 @@ Do NOT apply a speculative fix. Return the report and stop.
 
 - **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.
+- **Minimal fix only.** One concept, one commit. No refactors dressed as debug. Prefer `/qualia-fix` for explicit repair requests.
 - **Tool budget is hard.** 10 calls, then stop.
-- **Every fix gets a DEBUG report in .planning/** — creates a searchable record.
+- **Every investigation gets a DEBUG report in `.planning/reports/debug/`** — creates a searchable record without cluttering the root.

package/skills/qualia-discuss/SKILL.md

@@ -64,7 +64,7 @@ This is the only fork. Demo runs §1-§8 of the discovery template. Full project
 ### P2. Banner and open
 
 ```bash
-node ~/.claude/bin/qualia-ui.js banner discuss-project
+node ${QUALIA_BIN}/qualia-ui.js banner discuss-project
 ```
 
 Say: **"Eight quick questions for the demo path"** or **"Fourteen questions to shape the full project — we'll move fast"** depending on type.
@@ -85,20 +85,20 @@ Allowed `[Enter]` defaults exist on §2, §3, §5 only (inferred from project ty
 
 ### P4. Write `.planning/project-discovery.md`
 
-Fill the template at `~/.claude/qualia-templates/project-discovery.md` with the user's verbatim answers. Set frontmatter `project_type` and `discovered_at`.
+Fill the template at `${QUALIA_TEMPLATES}/project-discovery.md` with the user's verbatim answers. Set frontmatter `project_type` and `discovered_at`.
 
 ### P5. Hand back to `/qualia-new`
 
 ```bash
 git add .planning/project-discovery.md
 git commit -m "docs: project discovery interview ($PROJECT_TYPE)"
-node ~/.claude/bin/qualia-ui.js ok "Discovery captured — back to /qualia-new"
+node ${QUALIA_BIN}/qualia-ui.js ok "Discovery captured — back to /qualia-new"
 ```
 
 If invoked standalone (not from `/qualia-new`), end with:
 
 ```bash
-node ~/.claude/bin/qualia-ui.js end "DISCOVERY CAPTURED" "/qualia-new"
+node ${QUALIA_BIN}/qualia-ui.js end "DISCOVERY CAPTURED" "/qualia-new"
 ```
 
 If invoked inline by `/qualia-new`, return control silently — `/qualia-new` continues from Step 2.
@@ -135,19 +135,19 @@ Surface and lock the decisions, trade-offs, and constraints that must inform a p
 ### 1. Load substrate
 
 ```bash
-node ~/.claude/bin/state.js check 2>/dev/null
+node ${QUALIA_BIN}/state.js check 2>/dev/null
 cat .planning/PROJECT.md .planning/ROADMAP.md .planning/CONTEXT.md 2>/dev/null
 ls .planning/decisions/ 2>/dev/null
 cat .planning/research/SUMMARY.md 2>/dev/null
 ```
 
-If `.planning/CONTEXT.md` is missing, copy `~/.claude/qualia-templates/CONTEXT.md` to `.planning/CONTEXT.md` first.
-If `.planning/decisions/` is missing, create it. Copy `~/.claude/qualia-templates/decisions/ADR-template.md` next to it for reference.
+If `.planning/CONTEXT.md` is missing, copy `${QUALIA_TEMPLATES}/CONTEXT.md` to `.planning/CONTEXT.md` first.
+If `.planning/decisions/` is missing, create it. Copy `${QUALIA_TEMPLATES}/decisions/ADR-template.md` next to it for reference.
 
 ### 2. Open the conversation
 
 ```bash
-node ~/.claude/bin/qualia-ui.js banner discuss {N} "{phase name from ROADMAP.md}"
+node ${QUALIA_BIN}/qualia-ui.js banner discuss {N} "{phase name from ROADMAP.md}"
 ```
 
 Then state the goal in one sentence and the open questions you found in priority order (highest-stakes / hardest-to-reverse first).
@@ -200,14 +200,14 @@ Loop until "Lock it in".
 
 ### 6. Write phase-{N}-context.md
 
-Fill `~/.claude/qualia-templates/phase-context.md` with concrete content. Reference any ADRs written, any CONTEXT.md terms added.
+Fill `${QUALIA_TEMPLATES}/phase-context.md` with concrete content. Reference any ADRs written, any CONTEXT.md terms added.
 
 ### 7. Commit and route
 
 ```bash
 git add .planning/phase-{N}-context.md .planning/CONTEXT.md .planning/decisions/
 git commit -m "docs(phase-{N}): lock context, glossary terms, ADRs"
-node ~/.claude/bin/qualia-ui.js end "PHASE {N} CONTEXT LOCKED" "/qualia-plan {N}"
+node ${QUALIA_BIN}/qualia-ui.js end "PHASE {N} CONTEXT LOCKED" "/qualia-plan {N}"
 ```
 
 ## Rules — PHASE MODE

package/skills/qualia-doctor/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: qualia-doctor
+description: "Employee-facing framework health check. Wraps `qualia-framework doctor`, checks install targets, project state, contract coverage, planning-folder hygiene, hooks, memory, ERP queue health, and gives safe repair commands. Trigger on 'doctor', 'health check', 'framework broken', 'is Qualia installed correctly', 'Codex not picking up Qualia', 'hooks not running', 'memory broken', 'ERP queue stuck', '.planning messy'."
+allowed-tools:
+  - Bash
+  - Read
+  - Grep
+---
+
+# /qualia-doctor
+
+Diagnose whether the framework harness itself is healthy before blaming the project or the model.
+
+## 1. Install Health
+
+Run:
+
+```bash
+qualia-framework doctor
+qualia-framework trust
+```
+
+If it fails, report the failed checks first. Use safe repair commands only:
+
+```bash
+npx qualia-framework@latest install
+```
+
+Do not delete user files, configs, knowledge, or hooks manually.
+
+## 2. Project State Health
+
+Run from the project root:
+
+```bash
+node ${QUALIA_BIN}/state.js check
+```
+
+If installed under Codex only, use:
+
+```bash
+node ~/.codex/bin/state.js check
+```
+
+Classify:
+- `NO_PROJECT` -> project has not been initialized; next command is `/qualia-new` or `/qualia-map` for brownfield.
+- `schema_errors` -> recommend `node ${QUALIA_BIN}/state.js fix` or Codex equivalent.
+- `gap_cycles` at limit -> recommend replanning or escalation.
+
+## 3. Contract Health
+
+For the current phase, check whether a machine-readable contract exists:
+
+```bash
+node ${QUALIA_BIN}/state.js validate-plan --phase {N}
+```
+
+If `contract_status` is `missing`, `invalid`, or `drifted`, the harness is not at full-trust mode yet.
+
+When a contract exists, run:
+
+```bash
+node ${QUALIA_BIN}/contract-runner.js .planning/phase-{N}-contract.json
+```
+
+Use the Codex path on Codex-only installs.
+
+## 4. Planning Folder Hygiene
+
+Run:
+
+```bash
+qualia-framework planning-hygiene scan
+```
+
+If it reports loose files, show the dry-run result first. Only organize when the user approves:
+
+```bash
+qualia-framework planning-hygiene organize --write
+```
+
+Do not move files by hand; the script keeps phase-critical root files in place and moves loose reports/assets into `.planning/reports/`, `.planning/assets/`, `.planning/design/`, or `.planning/archive/loose/`.
+
+## 5. Memory Health
+
+Run:
+
+```bash
+node ${QUALIA_BIN}/knowledge.js
+node ${QUALIA_BIN}/knowledge.js list
+```
+
+Healthy memory has at least `index.md`, `agents.md`, and a writable `daily-log/` directory. Missing curated memory is not fatal, but missing installed memory files means reinstall.
+
+## 6. ERP Queue Health
+
+Run:
+
+```bash
+qualia-framework erp-flush show
+```
+
+If the queue has entries, run:
+
+```bash
+qualia-framework erp-flush drain
+```
+
+If the queue fails with `401`, the ERP API key is invalid. Use:
+
+```bash
+printf '%s' "$QUALIA_ERP_KEY" | qualia-framework set-erp-key
+```
+
+## Output
+
+End with:
+
+```text
+Harness health: PASS | DEGRADED | FAIL
+Trust score: {N}/100
+Install: ...
+State: ...
+State ledger: ...
+Contracts: ...
+Planning hygiene: ...
+Memory: ...
+Design/UI: ...
+Employee experience: ...
+ERP: ...
+Next: ...
+```
+
+## Rules
+
+1. Read diagnostics before repair.
+2. Never remove user-owned files.
+3. Treat missing contracts as degraded trust, not a project failure.
+4. Prefer reinstall for missing framework files.
+5. Prefer `state.js fix` only for malformed generated state.

package/skills/qualia-feature/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-feature
-description: "Auto-scoped single feature build. Picks inline (≤1 trivial file, no spawn) or fresh builder spawn (1-5 logic files, atomic commit) automatically from the task description. Refuses and routes to /qualia-plan for 5+ files or full phases. Flags: --force-spawn forces a builder, --force-inline forces inline. Trigger phrases: 'build this one thing', 'add a component', 'implement this feature', 'quick fix', 'small change', 'tweak', 'hot fix', 'one-line fix', 'typo', 'config tweak', 'qualia-feature'."
+description: "Auto-scoped single feature build for adding net-new capability. Picks inline (≤1 trivial file, no spawn) or fresh builder spawn (1-5 logic files, atomic commit). Refuses and routes to /qualia-plan for phase-sized work, and routes broken existing behavior to /qualia-fix. Trigger phrases: 'build this one thing', 'add a component', 'implement this feature', 'small change', 'tweak', 'one-line copy change', 'config tweak', 'qualia-feature'."
 allowed-tools:
   - Bash
   - Read
@@ -14,7 +14,7 @@ allowed-tools:
 
 # /qualia-feature — Auto-scoped Single Feature
 
-One command for everything between a typo and a phase. Auto-detects scope from the task description and picks the right execution path.
+One command for adding a small new capability outside the planned Road. Auto-detects scope from the task description and picks the right execution path.
 
 ## Usage
 
@@ -26,7 +26,7 @@ One command for everything between a typo and a phase. Auto-detects scope from t
 ## When to use
 
 - One feature outside a planned phase
-- A bug fix, typo, config tweak, or one-line change
+- A copy tweak, config tweak, or one-line non-repair change
 - A 1-5 file feature, component, API route, or integration
 - A refactor of a single module
 
@@ -34,6 +34,7 @@ One command for everything between a typo and a phase. Auto-detects scope from t
 
 - 5+ files or multiple subsystems touched → `/qualia-plan`
 - Part of a planned phase → `/qualia-build`
+- Broken existing behavior, regression, failing test, or hotfix → `/qualia-fix`
 - Investigating a symptom you can't name yet → `/qualia-debug`
 - Optimization or polish pass → `/qualia-optimize` or `/qualia-polish`
 
@@ -68,6 +69,7 @@ Classify the description into one of three buckets:
 - "add a", "implement", "build", "create" + a single noun (component, route, page, table, form, modal, hook, util, migration)
 - Description names a single feature with multiple touch points (e.g. "add a feedback form" → migration + API + UI = 3-4 files, but still one cohesive thing)
 - The work needs a fresh context to avoid contaminating the current conversation
+- The work repairs a non-trivial bug only if invoked explicitly with `/qualia-feature --force-spawn`; otherwise use `/qualia-fix`
 
 **Refuse signals** (any one is sufficient):
 - "build the X system", "implement the entire Y", "add complete Z support"
@@ -79,9 +81,9 @@ Classify the description into one of three buckets:
 Show the user what was detected. Always offer the escape hatch:
 
 ```bash
-node ~/.claude/bin/qualia-ui.js banner feature
-node ~/.claude/bin/qualia-ui.js info "Detected scope: {inline|spawn|refuse}"
-node ~/.claude/bin/qualia-ui.js info "Reason: {one-line rationale}"
+node ${QUALIA_BIN}/qualia-ui.js banner feature
+node ${QUALIA_BIN}/qualia-ui.js info "Detected scope: {inline|spawn|refuse}"
+node ${QUALIA_BIN}/qualia-ui.js info "Reason: {one-line rationale}"
 ```
 
 Then:
@@ -114,13 +116,13 @@ git commit -m "fix: {description}"
 5. Record in state:
 
 ```bash
-node ~/.claude/bin/state.js transition --to note --notes "{brief description}" --tasks-done 1
+node ${QUALIA_BIN}/state.js transition --to note --notes "{brief description}" --tasks-done 1
 ```
 
 6. End with:
 
 ```bash
-node ~/.claude/bin/qualia-ui.js end "FEATURE SHIPPED (inline)"
+node ${QUALIA_BIN}/qualia-ui.js end "FEATURE SHIPPED (inline)"
 ```
 
 ### 5. Execute the spawn path
@@ -130,9 +132,9 @@ For spawn scope:
 1. Build a quick task spec (don't write to a file, just confirm with user):
 
 ```bash
-node ~/.claude/bin/qualia-ui.js info "What: {what to build}"
-node ~/.claude/bin/qualia-ui.js info "Files: {files to create/modify, comma list}"
-node ~/.claude/bin/qualia-ui.js info "Done: {observable acceptance criteria, 1-3 bullets}"
+node ${QUALIA_BIN}/qualia-ui.js info "What: {what to build}"
+node ${QUALIA_BIN}/qualia-ui.js info "Files: {files to create/modify, comma list}"
+node ${QUALIA_BIN}/qualia-ui.js info "Done: {observable acceptance criteria, 1-3 bullets}"
 ```
 
 Ask: **"Good to build?"** Wait for confirmation.
@@ -142,7 +144,7 @@ Ask: **"Good to build?"** Wait for confirmation.
 ```
 Agent(subagent_type="qualia-builder", description="Feature: {short title}")
   prompt: |
-    Read your role: @~/.claude/agents/builder.md
+    Read your role: @${QUALIA_AGENTS}/builder.md
 
     <task>
     {task description verbatim from user}
@@ -172,17 +174,17 @@ Agent(subagent_type="qualia-builder", description="Feature: {short title}")
 4. Report:
 
 ```bash
-node ~/.claude/bin/qualia-ui.js divider
-node ~/.claude/bin/qualia-ui.js ok "Feature: {description}"
-node ~/.claude/bin/qualia-ui.js ok "Files: {files changed}"
-node ~/.claude/bin/qualia-ui.js ok "Commit: {commit hash}"
-node ~/.claude/bin/qualia-ui.js end "FEATURE SHIPPED (spawn)"
+node ${QUALIA_BIN}/qualia-ui.js divider
+node ${QUALIA_BIN}/qualia-ui.js ok "Feature: {description}"
+node ${QUALIA_BIN}/qualia-ui.js ok "Files: {files changed}"
+node ${QUALIA_BIN}/qualia-ui.js ok "Commit: {commit hash}"
+node ${QUALIA_BIN}/qualia-ui.js end "FEATURE SHIPPED (spawn)"
 ```
 
 5. Record in state:
 
 ```bash
-node ~/.claude/bin/state.js transition --to note --notes "{description}" --tasks-done 1
+node ${QUALIA_BIN}/state.js transition --to note --notes "{description}" --tasks-done 1
 ```
 
 ### 6. Execute the refuse path
@@ -190,9 +192,9 @@ node ~/.claude/bin/state.js transition --to note --notes "{description}" --tasks
 For refuse scope, do NOT build. Explain why and route:
 
 ```bash
-node ~/.claude/bin/qualia-ui.js warn "This is too big for /qualia-feature (5+ files or multi-step workflow)."
-node ~/.claude/bin/qualia-ui.js info "Reason: {one-line — e.g. 'description names the entire auth system, not a slice'}"
-node ~/.claude/bin/qualia-ui.js end "ROUTED" "/qualia-plan"
+node ${QUALIA_BIN}/qualia-ui.js warn "This is too big for /qualia-feature (5+ files or multi-step workflow)."
+node ${QUALIA_BIN}/qualia-ui.js info "Reason: {one-line — e.g. 'description names the entire auth system, not a slice'}"
+node ${QUALIA_BIN}/qualia-ui.js end "ROUTED" "/qualia-plan"
 ```
 
 If the user is sure it's small and the classifier got it wrong, they can re-invoke with `--force-spawn`.

package/skills/qualia-fix/SKILL.md

@@ -0,0 +1,216 @@
+---
+name: qualia-fix
+description: "Practical repair lane for broken existing behavior. Blends /qualia-debug root-cause discipline with /qualia-feature execution. Use when the user says 'fix this', 'bug', 'broken', 'error', 'failing test', 'regression', 'hotfix', 'not working', 'layout broken', 'slow page', or 'config is wrong'."
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+  - Agent
+argument-hint: "[--quick|--frontend|--perf|--test|--no-commit] <symptom>"
+---
+
+# /qualia-fix - Repair Broken Existing Behavior
+
+Fix is the practical lane for "this used to work, or should work, and now it does not." It combines the evidence discipline of `/qualia-debug` with the small-work execution path of `/qualia-feature`.
+
+## Usage
+
+- `/qualia-fix {symptom}` - diagnose and repair a named problem
+- `/qualia-fix --quick {symptom}` - micro-fix, max 1 file, direct edit
+- `/qualia-fix --frontend {symptom}` - bias diagnostics toward layout, CSS, hydration, responsive, and visual bugs
+- `/qualia-fix --perf {symptom}` - bias diagnostics toward slow pages, wasteful renders, bundles, queries, and sequential awaits
+- `/qualia-fix --test {failing command}` - start from a failing test/build command
+- `/qualia-fix --no-commit {symptom}` - patch and verify, but leave changes uncommitted
+
+## When To Use
+
+- A failing test, build, typecheck, lint, deploy, or runtime path
+- A broken existing UI, route, form, API, config, or integration
+- A regression after recent work
+- A small bug report with enough detail to reproduce or inspect
+- A hotfix where the expected behavior is already known
+
+## When Not To Use
+
+- Net-new capability -> `/qualia-feature`
+- Phase-sized work or 5+ likely files -> `/qualia-plan`
+- Read-only audit -> `/qualia-review`
+- No concrete symptom and no failing command -> `/qualia-debug`
+- Visual craft/design quality with no functional bug -> `/qualia-polish`
+- Whole-site aesthetic pivot -> `/qualia-vibe`
+
+## Process
+
+```bash
+node ${QUALIA_BIN}/qualia-ui.js banner fix
+```
+
+### 1. Classify The Request
+
+Parse `$ARGUMENTS` into:
+
+- symptom
+- mode: quick | frontend | perf | test | general
+- expected behavior
+- observed behavior
+- named files/routes/tests if provided
+
+If the request is actually a new feature, stop and route:
+
+```bash
+node ${QUALIA_BIN}/qualia-ui.js end "ROUTED" "/qualia-feature"
+```
+
+If the request is phase-sized, stop and route:
+
+```bash
+node ${QUALIA_BIN}/qualia-ui.js end "ROUTED" "/qualia-plan"
+```
+
+### 2. Build The Feedback Loop
+
+Use the cheapest check that can prove the bug is real and later prove it is fixed.
+
+Prefer, in order:
+
+1. User-provided failing command
+2. Targeted test
+3. Typecheck or lint error
+4. Reproduction grep or route/component inspection
+5. Recent diff inspection
+
+Useful starting commands:
+
+```bash
+git status --short
+git diff --stat
+npm test -- --runInBand 2>/dev/null || npm test 2>/dev/null || true
+npx tsc --noEmit 2>&1 | head -40
+```
+
+For `--test`, run the exact command first and preserve the failing output.
+
+### 3. Find Root Cause
+
+Use a hard inspection budget of 12 Read/Grep/Bash calls before returning insufficient evidence.
+
+Root cause must include:
+
+- `file:line`
+- the specific bad assumption or broken contract
+- why the symptom follows from it
+
+No root cause, no patch. If evidence is insufficient, write the report and stop.
+
+### 4. Patch Minimally
+
+Patch rules:
+
+- Touch only files required by the root cause.
+- Default max: 3 files.
+- `--quick` max: 1 file.
+- If more than 3 files are required, stop and route to `/qualia-plan` or ask for permission to widen.
+- Do not include cleanup, refactors, formatting churn, or adjacent improvements.
+- Preserve unrelated user changes.
+
+### 5. Verify
+
+Re-run the feedback loop from Step 2. Then run the smallest broad safety check that matches the stack.
+
+Common verification:
+
+```bash
+npx tsc --noEmit
+npm test -- --runInBand 2>/dev/null || npm test 2>/dev/null || true
+```
+
+If verification fails, do not commit. Either repair the verification failure if it is the same root cause, or write the report with the remaining failure.
+
+### 6. Write FIX Report
+
+Create the report directory and write `.planning/reports/fix/FIX-{YYYY-MM-DD-HHMM}.md`:
+
+```bash
+mkdir -p .planning/reports/fix
+```
+
+```markdown
+# Fix Report - {YYYY-MM-DD HH:MM}
+
+**Symptom:** {user symptom}
+**Mode:** general | quick | frontend | perf | test
+**Outcome:** fixed | insufficient-evidence | partial
+
+## Feedback Loop
+- Initial failing check: `{command or inspection}`
+- Final passing check: `{command or inspection}`
+
+## Root Cause
+`{file}:{line}` - {one sentence}
+
+## Patch
+- Files changed: {list}
+- Change summary: {brief summary}
+
+## Verification
+- `{command}` - PASS|FAIL
+- `{command}` - PASS|FAIL
+
+## Remaining Notes
+- {adjacent issue not fixed, or "None"}
+```
+
+### 7. Commit
+
+Unless `--no-commit` was passed:
+
+```bash
+git add {specific changed files} .planning/reports/fix/FIX-{timestamp}.md
+git commit -m "fix: {short symptom/root-cause summary}"
+```
+
+Record state:
+
+```bash
+node ${QUALIA_BIN}/state.js transition --to note --notes "{short fix summary}" --tasks-done 1
+```
+
+### 8. Output
+
+```bash
+node ${QUALIA_BIN}/qualia-ui.js divider
+node ${QUALIA_BIN}/qualia-ui.js ok "Root cause: {file:line}"
+node ${QUALIA_BIN}/qualia-ui.js ok "Files: {changed files}"
+node ${QUALIA_BIN}/qualia-ui.js ok "Verification: {commands}"
+node ${QUALIA_BIN}/qualia-ui.js end "FIXED" "{next command if any}"
+```
+
+## Insufficient Evidence Return
+
+If no confident root cause after 12 inspection calls, write the same FIX report with:
+
+```markdown
+**Outcome:** insufficient-evidence
+
+## Narrowed To
+- Files examined: {list}
+- Ruled out: {list}
+- Remaining suspects: {list}
+
+## Recommended Next Diagnostic
+- {specific command or reproduction step}
+```
+
+Do not patch and do not commit speculative work.
+
+## Rules
+
+1. **Repair existing behavior only.** New work belongs in `/qualia-feature`.
+2. **Feedback loop first.** Know how the bug will be proven fixed before editing.
+3. **Root cause or stop.** No plausible patches.
+4. **Small patch.** Default max 3 files; quick max 1 file.
+5. **Report every run.** The FIX report becomes searchable repair memory.
+6. **Commit only after verification.** `--no-commit` is the only exception.