qualia-framework 2.6.0 → 3.2.0

package/framework/qualia-framework/templates/DEBUG.md

@@ -1,159 +0,0 @@
-# Debug Template
-
-Template for `.planning/debug/[slug].md` — active debug session tracking.
-
----
-
-## File Template
-
-```markdown
----
-status: gathering | investigating | fixing | verifying | resolved
-trigger: "[verbatim user input]"
-created: [ISO timestamp]
-updated: [ISO timestamp]
----
-
-## Current Focus
-<!-- OVERWRITE on each update - always reflects NOW -->
-
-hypothesis: [current theory being tested]
-test: [how testing it]
-expecting: [what result means if true/false]
-next_action: [immediate next step]
-
-## Symptoms
-<!-- Written during gathering, then immutable -->
-
-expected: [what should happen]
-actual: [what actually happens]
-errors: [error messages if any]
-reproduction: [how to trigger]
-started: [when it broke / always broken]
-
-## Eliminated
-<!-- APPEND only - prevents re-investigating after /clear -->
-
-- hypothesis: [theory that was wrong]
-  evidence: [what disproved it]
-  timestamp: [when eliminated]
-
-## Evidence
-<!-- APPEND only - facts discovered during investigation -->
-
-- timestamp: [when found]
-  checked: [what was examined]
-  found: [what was observed]
-  implication: [what this means]
-
-## Resolution
-<!-- OVERWRITE as understanding evolves -->
-
-root_cause: [empty until found]
-fix: [empty until applied]
-verification: [empty until verified]
-files_changed: []
-```
-
----
-
-<section_rules>
-
-**Frontmatter (status, trigger, timestamps):**
-- `status`: OVERWRITE - reflects current phase
-- `trigger`: IMMUTABLE - verbatim user input, never changes
-- `created`: IMMUTABLE - set once
-- `updated`: OVERWRITE - update on every change
-
-**Current Focus:**
-- OVERWRITE entirely on each update
-- Always reflects what Claude is doing RIGHT NOW
-- If Claude reads this after /clear, it knows exactly where to resume
-- Fields: hypothesis, test, expecting, next_action
-
-**Symptoms:**
-- Written during initial gathering phase
-- IMMUTABLE after gathering complete
-- Reference point for what we're trying to fix
-- Fields: expected, actual, errors, reproduction, started
-
-**Eliminated:**
-- APPEND only - never remove entries
-- Prevents re-investigating dead ends after context reset
-- Each entry: hypothesis, evidence that disproved it, timestamp
-- Critical for efficiency across /clear boundaries
-
-**Evidence:**
-- APPEND only - never remove entries
-- Facts discovered during investigation
-- Each entry: timestamp, what checked, what found, implication
-- Builds the case for root cause
-
-**Resolution:**
-- OVERWRITE as understanding evolves
-- May update multiple times as fixes are tried
-- Final state shows confirmed root cause and verified fix
-- Fields: root_cause, fix, verification, files_changed
-
-</section_rules>
-
-<lifecycle>
-
-**Creation:** Immediately when /qualia:debug is called
-- Create file with trigger from user input
-- Set status to "gathering"
-- Current Focus: next_action = "gather symptoms"
-- Symptoms: empty, to be filled
-
-**During symptom gathering:**
-- Update Symptoms section as user answers questions
-- Update Current Focus with each question
-- When complete: status → "investigating"
-
-**During investigation:**
-- OVERWRITE Current Focus with each hypothesis
-- APPEND to Evidence with each finding
-- APPEND to Eliminated when hypothesis disproved
-- Update timestamp in frontmatter
-
-**During fixing:**
-- status → "fixing"
-- Update Resolution.root_cause when confirmed
-- Update Resolution.fix when applied
-- Update Resolution.files_changed
-
-**During verification:**
-- status → "verifying"
-- Update Resolution.verification with results
-- If verification fails: status → "investigating", try again
-
-**On resolution:**
-- status → "resolved"
-- Move file to .planning/debug/resolved/
-
-</lifecycle>
-
-<resume_behavior>
-
-When Claude reads this file after /clear:
-
-1. Parse frontmatter → know status
-2. Read Current Focus → know exactly what was happening
-3. Read Eliminated → know what NOT to retry
-4. Read Evidence → know what's been learned
-5. Continue from next_action
-
-The file IS the debugging brain. Claude should be able to resume perfectly from any interruption point.
-
-</resume_behavior>
-
-<size_constraint>
-
-Keep debug files focused:
-- Evidence entries: 1-2 lines each, just the facts
-- Eliminated: brief - hypothesis + why it failed
-- No narrative prose - structured data only
-
-If evidence grows very large (10+ entries), consider whether you're going in circles. Check Eliminated to ensure you're not re-treading.
-
-</size_constraint>

package/framework/qualia-framework/templates/DESIGN.md

@@ -1,81 +0,0 @@
----
-project: {project_name}
-created: {date}
-last_updated: {date}
-updated_in_phase: {phase_number}
----
-
-# Design System: {project_name}
-
-> Authoritative design decisions for this project. All design skills read this file first.
-> Contains DECISIONS and CONSTRAINTS only — no CSS, no component code, no implementation details.
-
-## Color Palette
-
-**Primary:** {color name and hex/oklch value}
-**Secondary:** {color name and hex/oklch value}
-**Accent:** {color name and hex/oklch value}
-**Neutrals:** {warm/cool tint direction, base tones}
-**Semantic:** success, error, warning, info color choices
-
-**Constraints:**
-- {e.g., "No pure black or pure white", "Neutrals tinted toward primary hue"}
-- {e.g., "Avoid purple-blue gradients (AI slop)"}
-
-## Typography
-
-**Display/Heading font:** {font name} — {why chosen, personality}
-**Body font:** {font name} — {why chosen, readability}
-**Monospace (if needed):** {font name}
-**Scale approach:** {e.g., "Modular scale with fluid clamp() sizing"}
-
-**Constraints:**
-- {e.g., "Never use Inter, Roboto, Arial, Open Sans"}
-- {e.g., "Minimum 14px body on mobile"}
-
-## Spacing & Layout
-
-**Grid system:** {e.g., "8px base unit", "12-column grid"}
-**Spacing approach:** {e.g., "Varied rhythm — tight groupings with generous separations"}
-**Max content width:** {e.g., "full-width with 2rem-4rem side padding" — avoid hardcoded pixel caps like 1200px/1280px}
-**Layout philosophy:** {e.g., "Asymmetric, left-aligned, break grid for emphasis"}
-
-**Constraints:**
-- {e.g., "No card grids — use varied layouts"}
-- {e.g., "No nesting cards inside cards"}
-
-## Component Patterns
-
-**Buttons:** {hierarchy approach — primary, secondary, ghost}
-**Cards/Surfaces:** {when to use, when not to use}
-**Navigation:** {pattern choice — sidebar, top nav, tabs}
-**Forms:** {input style, validation approach}
-**Empty states:** {approach — illustrative, instructive, minimal}
-
-**Constraints:**
-- {e.g., "No modals unless truly no alternative"}
-- {e.g., "Progressive disclosure over everything-visible"}
-
-## Motion & Animation
-
-**Overall approach:** {e.g., "Minimal and purposeful", "Rich and orchestrated"}
-**Page transitions:** {approach}
-**Micro-interactions:** {approach}
-**Easing:** {e.g., "ease-out-quart for all transitions, never bounce/elastic"}
-**Duration range:** {e.g., "100-500ms, never over 800ms"}
-
-**Constraints:**
-- {e.g., "Always respect prefers-reduced-motion"}
-- {e.g., "Transform and opacity only — no layout property animation"}
-
-## Brand Personality
-
-**Tone:** {e.g., "Professional but warm", "Bold and energetic", "Minimal and refined"}
-**Aesthetic direction:** {chosen direction from frontend-master — brutalist, editorial, luxury, etc.}
-**Differentiation:** {what makes this project's design memorable}
-
----
-
-*This file is the authoritative source for all design decisions in this project.*
-*Updated by /qualia:discuss-phase during frontend phases.*
-*Read by /critique, /polish, /bolder, /colorize, /animate, /design-quieter, /distill, /delight, /normalize.*

package/framework/qualia-framework/templates/UAT.md

@@ -1,247 +0,0 @@
-# UAT Template
-
-Template for `.planning/phases/XX-name/{phase}-UAT.md` — persistent UAT session tracking.
-
----
-
-## File Template
-
-```markdown
----
-status: testing | complete | diagnosed
-phase: XX-name
-source: [list of SUMMARY.md files tested]
-started: [ISO timestamp]
-updated: [ISO timestamp]
----
-
-## Current Test
-<!-- OVERWRITE each test - shows where we are -->
-
-number: [N]
-name: [test name]
-expected: |
-  [what user should observe]
-awaiting: user response
-
-## Tests
-
-### 1. [Test Name]
-expected: [observable behavior - what user should see]
-result: [pending]
-
-### 2. [Test Name]
-expected: [observable behavior]
-result: pass
-
-### 3. [Test Name]
-expected: [observable behavior]
-result: issue
-reported: "[verbatim user response]"
-severity: major
-
-### 4. [Test Name]
-expected: [observable behavior]
-result: skipped
-reason: [why skipped]
-
-...
-
-## Summary
-
-total: [N]
-passed: [N]
-issues: [N]
-pending: [N]
-skipped: [N]
-
-## Gaps
-
-<!-- YAML format for plan-phase --gaps consumption -->
-- truth: "[expected behavior from test]"
-  status: failed
-  reason: "User reported: [verbatim response]"
-  severity: blocker | major | minor | cosmetic
-  test: [N]
-  root_cause: ""     # Filled by diagnosis
-  artifacts: []      # Filled by diagnosis
-  missing: []        # Filled by diagnosis
-  debug_session: ""  # Filled by diagnosis
-```
-
----
-
-<section_rules>
-
-**Frontmatter:**
-- `status`: OVERWRITE - "testing" or "complete"
-- `phase`: IMMUTABLE - set on creation
-- `source`: IMMUTABLE - SUMMARY files being tested
-- `started`: IMMUTABLE - set on creation
-- `updated`: OVERWRITE - update on every change
-
-**Current Test:**
-- OVERWRITE entirely on each test transition
-- Shows which test is active and what's awaited
-- On completion: "[testing complete]"
-
-**Tests:**
-- Each test: OVERWRITE result field when user responds
-- `result` values: [pending], pass, issue, skipped
-- If issue: add `reported` (verbatim) and `severity` (inferred)
-- If skipped: add `reason` if provided
-
-**Summary:**
-- OVERWRITE counts after each response
-- Tracks: total, passed, issues, pending, skipped
-
-**Gaps:**
-- APPEND only when issue found (YAML format)
-- After diagnosis: fill `root_cause`, `artifacts`, `missing`, `debug_session`
-- This section feeds directly into /qualia:plan-phase --gaps
-
-</section_rules>
-
-<diagnosis_lifecycle>
-
-**After testing complete (status: complete), if gaps exist:**
-
-1. User runs diagnosis (from verify-work offer or manually)
-2. diagnose-issues workflow spawns parallel debug agents
-3. Each agent investigates one gap, returns root cause
-4. UAT.md Gaps section updated with diagnosis:
-   - Each gap gets `root_cause`, `artifacts`, `missing`, `debug_session` filled
-5. status → "diagnosed"
-6. Ready for /qualia:plan-phase --gaps with root causes
-
-**After diagnosis:**
-```yaml
-## Gaps
-
-- truth: "Comment appears immediately after submission"
-  status: failed
-  reason: "User reported: works but doesn't show until I refresh the page"
-  severity: major
-  test: 2
-  root_cause: "useEffect in CommentList.tsx missing commentCount dependency"
-  artifacts:
-    - path: "src/components/CommentList.tsx"
-      issue: "useEffect missing dependency"
-  missing:
-    - "Add commentCount to useEffect dependency array"
-  debug_session: ".planning/debug/comment-not-refreshing.md"
-```
-
-</diagnosis_lifecycle>
-
-<lifecycle>
-
-**Creation:** When /qualia:verify-work starts new session
-- Extract tests from SUMMARY.md files
-- Set status to "testing"
-- Current Test points to test 1
-- All tests have result: [pending]
-
-**During testing:**
-- Present test from Current Test section
-- User responds with pass confirmation or issue description
-- Update test result (pass/issue/skipped)
-- Update Summary counts
-- If issue: append to Gaps section (YAML format), infer severity
-- Move Current Test to next pending test
-
-**On completion:**
-- status → "complete"
-- Current Test → "[testing complete]"
-- Commit file
-- Present summary with next steps
-
-**Resume after /clear:**
-1. Read frontmatter → know phase and status
-2. Read Current Test → know where we are
-3. Find first [pending] result → continue from there
-4. Summary shows progress so far
-
-</lifecycle>
-
-<severity_guide>
-
-Severity is INFERRED from user's natural language, never asked.
-
-| User describes | Infer |
-|----------------|-------|
-| Crash, error, exception, fails completely, unusable | blocker |
-| Doesn't work, nothing happens, wrong behavior, missing | major |
-| Works but..., slow, weird, minor, small issue | minor |
-| Color, font, spacing, alignment, visual, looks off | cosmetic |
-
-Default: **major** (safe default, user can clarify if wrong)
-
-</severity_guide>
-
-<good_example>
-```markdown
----
-status: diagnosed
-phase: 04-comments
-source: 04-01-SUMMARY.md, 04-02-SUMMARY.md
-started: 2025-01-15T10:30:00Z
-updated: 2025-01-15T10:45:00Z
----
-
-## Current Test
-
-[testing complete]
-
-## Tests
-
-### 1. View Comments on Post
-expected: Comments section expands, shows count and comment list
-result: pass
-
-### 2. Create Top-Level Comment
-expected: Submit comment via rich text editor, appears in list with author info
-result: issue
-reported: "works but doesn't show until I refresh the page"
-severity: major
-
-### 3. Reply to a Comment
-expected: Click Reply, inline composer appears, submit shows nested reply
-result: pass
-
-### 4. Visual Nesting
-expected: 3+ level thread shows indentation, left borders, caps at reasonable depth
-result: pass
-
-### 5. Delete Own Comment
-expected: Click delete on own comment, removed or shows [deleted] if has replies
-result: pass
-
-### 6. Comment Count
-expected: Post shows accurate count, increments when adding comment
-result: pass
-
-## Summary
-
-total: 6
-passed: 5
-issues: 1
-pending: 0
-skipped: 0
-
-## Gaps
-
-- truth: "Comment appears immediately after submission in list"
-  status: failed
-  reason: "User reported: works but doesn't show until I refresh the page"
-  severity: major
-  test: 2
-  root_cause: "useEffect in CommentList.tsx missing commentCount dependency"
-  artifacts:
-    - path: "src/components/CommentList.tsx"
-      issue: "useEffect missing dependency"
-  missing:
-    - "Add commentCount to useEffect dependency array"
-  debug_session: ".planning/debug/comment-not-refreshing.md"
-```
-</good_example>