qualia-framework 2.5.1 → 3.1.0

package/framework/qualia-framework/workflows/diagnose-issues.md

@@ -1,219 +0,0 @@
-<purpose>
-Orchestrate parallel debug agents to investigate UAT gaps and find root causes.
-
-After UAT finds gaps, spawn one debug agent per gap. Each agent investigates autonomously with symptoms pre-filled from UAT. Collect root causes, update UAT.md gaps with diagnosis, then hand off to plan-phase --gaps with actual diagnoses.
-
-Orchestrator stays lean: parse gaps, spawn agents, collect results, update UAT.
-</purpose>
-
-<paths>
-DEBUG_DIR=.planning/debug
-
-Debug files use the `.planning/debug/` path (hidden directory with leading dot).
-</paths>
-
-<core_principle>
-**Diagnose before planning fixes.**
-
-UAT tells us WHAT is broken (symptoms). Debug agents find WHY (root cause). plan-phase --gaps then creates targeted fixes based on actual causes, not guesses.
-
-Without diagnosis: "Comment doesn't refresh" → guess at fix → maybe wrong
-With diagnosis: "Comment doesn't refresh" → "useEffect missing dependency" → precise fix
-</core_principle>
-
-<process>
-
-<step name="parse_gaps">
-**Extract gaps from UAT.md:**
-
-Read the "Gaps" section (YAML format):
-```yaml
-- 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
-  artifacts: []
-  missing: []
-```
-
-For each gap, also read the corresponding test from "Tests" section to get full context.
-
-Build gap list:
-```
-gaps = [
-  {truth: "Comment appears immediately...", severity: "major", test_num: 2, reason: "..."},
-  {truth: "Reply button positioned correctly...", severity: "minor", test_num: 5, reason: "..."},
-  ...
-]
-```
-</step>
-
-<step name="report_plan">
-**Report diagnosis plan to user:**
-
-```
-## Diagnosing {N} Gaps
-
-Spawning parallel debug agents to investigate root causes:
-
-| Gap (Truth) | Severity |
-|-------------|----------|
-| Comment appears immediately after submission | major |
-| Reply button positioned correctly | minor |
-| Delete removes comment | blocker |
-
-Each agent will:
-1. Create DEBUG-{slug}.md with symptoms pre-filled
-2. Investigate autonomously (read code, form hypotheses, test)
-3. Return root cause
-
-This runs in parallel - all gaps investigated simultaneously.
-```
-</step>
-
-<step name="spawn_agents">
-**Spawn debug agents in parallel:**
-
-For each gap, fill the debug-subagent-prompt template and spawn:
-
-```
-Task(
-  prompt=filled_debug_subagent_prompt,
-  subagent_type="general-purpose",
-  description="Debug: {truth_short}"
-)
-```
-
-**All agents spawn in single message** (parallel execution).
-
-Template placeholders:
-- `{truth}`: The expected behavior that failed
-- `{expected}`: From UAT test
-- `{actual}`: Verbatim user description from reason field
-- `{errors}`: Any error messages from UAT (or "None reported")
-- `{reproduction}`: "Test {test_num} in UAT"
-- `{timeline}`: "Discovered during UAT"
-- `{goal}`: `find_root_cause_only` (UAT flow - plan-phase --gaps handles fixes)
-- `{slug}`: Generated from truth
-</step>
-
-<step name="collect_results">
-**Collect root causes from agents:**
-
-Each agent returns with:
-```
-## ROOT CAUSE FOUND
-
-**Debug Session:** ${DEBUG_DIR}/{slug}.md
-
-**Root Cause:** {specific cause with evidence}
-
-**Evidence Summary:**
-- {key finding 1}
-- {key finding 2}
-- {key finding 3}
-
-**Files Involved:**
-- {file1}: {what's wrong}
-- {file2}: {related issue}
-
-**Suggested Fix Direction:** {brief hint for plan-phase --gaps}
-```
-
-Parse each return to extract:
-- root_cause: The diagnosed cause
-- files: Files involved
-- debug_path: Path to debug session file
-- suggested_fix: Hint for gap closure plan
-
-If agent returns `## INVESTIGATION INCONCLUSIVE`:
-- root_cause: "Investigation inconclusive - manual review needed"
-- Note which issue needs manual attention
-- Include remaining possibilities from agent return
-</step>
-
-<step name="update_uat">
-**Update UAT.md gaps with diagnosis:**
-
-For each gap in the Gaps section, add artifacts and missing fields:
-
-```yaml
-- 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"
-    - "Trigger re-render when new comment added"
-  debug_session: .planning/debug/comment-not-refreshing.md
-```
-
-Update status in frontmatter to "diagnosed".
-
-Commit the updated UAT.md:
-```bash
-node /home/qualia/.claude/qualia-framework/bin/qualia-tools.js commit "docs({phase}): add root causes from diagnosis" --files ".planning/phases/XX-name/{phase}-UAT.md"
-```
-</step>
-
-<step name="report_results">
-**Report diagnosis results and hand off:**
-
-Display:
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- Qualia ► DIAGNOSIS COMPLETE
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-| Gap (Truth) | Root Cause | Files |
-|-------------|------------|-------|
-| Comment appears immediately | useEffect missing dependency | CommentList.tsx |
-| Reply button positioned correctly | CSS flex order incorrect | ReplyButton.tsx |
-| Delete removes comment | API missing auth header | api/comments.ts |
-
-Debug sessions: ${DEBUG_DIR}/
-
-Proceeding to plan fixes...
-```
-
-Return to verify-work orchestrator for automatic planning.
-Do NOT offer manual next steps - verify-work handles the rest.
-</step>
-
-</process>
-
-<context_efficiency>
-Agents start with symptoms pre-filled from UAT (no symptom gathering).
-Agents only diagnose—plan-phase --gaps handles fixes (no fix application).
-</context_efficiency>
-
-<failure_handling>
-**Agent fails to find root cause:**
-- Mark gap as "needs manual review"
-- Continue with other gaps
-- Report incomplete diagnosis
-
-**Agent times out:**
-- Check DEBUG-{slug}.md for partial progress
-- Can resume with /qualia:debug
-
-**All agents fail:**
-- Something systemic (permissions, git, etc.)
-- Report for manual investigation
-- Fall back to plan-phase --gaps without root causes (less precise)
-</failure_handling>
-
-<success_criteria>
-- [ ] Gaps parsed from UAT.md
-- [ ] Debug agents spawned in parallel
-- [ ] Root causes collected from all agents
-- [ ] UAT.md gaps updated with artifacts and missing
-- [ ] Debug sessions saved to ${DEBUG_DIR}/
-- [ ] Hand off to verify-work for automatic planning
-</success_criteria>

package/framework/qualia-framework/workflows/discovery-phase.md

@@ -1,289 +0,0 @@
-<purpose>
-Execute discovery at the appropriate depth level.
-Produces DISCOVERY.md (for Level 2-3) that informs PLAN.md creation.
-
-Called from plan-phase.md's mandatory_discovery step with a depth parameter.
-
-NOTE: For comprehensive ecosystem research ("how do experts build this"), use /qualia:research-phase instead, which produces RESEARCH.md.
-</purpose>
-
-<depth_levels>
-**This workflow supports three depth levels:**
-
-| Level | Name         | Time      | Output                                       | When                                      |
-| ----- | ------------ | --------- | -------------------------------------------- | ----------------------------------------- |
-| 1     | Quick Verify | 2-5 min   | No file, proceed with verified knowledge     | Single library, confirming current syntax |
-| 2     | Standard     | 15-30 min | DISCOVERY.md                                 | Choosing between options, new integration |
-| 3     | Deep Dive    | 1+ hour   | Detailed DISCOVERY.md with validation gates  | Architectural decisions, novel problems   |
-
-**Depth is determined by plan-phase.md before routing here.**
-</depth_levels>
-
-<source_hierarchy>
-**MANDATORY: Context7 BEFORE WebSearch**
-
-Claude's training data is 6-18 months stale. Always verify.
-
-1. **Context7 MCP FIRST** - Current docs, no hallucination
-2. **Official docs** - When Context7 lacks coverage
-3. **WebSearch LAST** - For comparisons and trends only
-
-See /home/qualia/.claude/qualia-framework/templates/discovery.md `<discovery_protocol>` for full protocol.
-</source_hierarchy>
-
-<process>
-
-<step name="determine_depth">
-Check the depth parameter passed from plan-phase.md:
-- `depth=verify` → Level 1 (Quick Verification)
-- `depth=standard` → Level 2 (Standard Discovery)
-- `depth=deep` → Level 3 (Deep Dive)
-
-Route to appropriate level workflow below.
-</step>
-
-<step name="level_1_quick_verify">
-**Level 1: Quick Verification (2-5 minutes)**
-
-For: Single known library, confirming syntax/version still correct.
-
-**Process:**
-
-1. Resolve library in Context7:
-
-   ```
-   mcp__context7__resolve-library-id with libraryName: "[library]"
-   ```
-
-2. Fetch relevant docs:
-
-   ```
-   mcp__context7__get-library-docs with:
-   - context7CompatibleLibraryID: [from step 1]
-   - topic: [specific concern]
-   ```
-
-3. Verify:
-
-   - Current version matches expectations
-   - API syntax unchanged
-   - No breaking changes in recent versions
-
-4. **If verified:** Return to plan-phase.md with confirmation. No DISCOVERY.md needed.
-
-5. **If concerns found:** Escalate to Level 2.
-
-**Output:** Verbal confirmation to proceed, or escalation to Level 2.
-</step>
-
-<step name="level_2_standard">
-**Level 2: Standard Discovery (15-30 minutes)**
-
-For: Choosing between options, new external integration.
-
-**Process:**
-
-1. **Identify what to discover:**
-
-   - What options exist?
-   - What are the key comparison criteria?
-   - What's our specific use case?
-
-2. **Context7 for each option:**
-
-   ```
-   For each library/framework:
-   - mcp__context7__resolve-library-id
-   - mcp__context7__get-library-docs (mode: "code" for API, "info" for concepts)
-   ```
-
-3. **Official docs** for anything Context7 lacks.
-
-4. **WebSearch** for comparisons:
-
-   - "[option A] vs [option B] {current_year}"
-   - "[option] known issues"
-   - "[option] with [our stack]"
-
-5. **Cross-verify:** Any WebSearch finding → confirm with Context7/official docs.
-
-6. **Create DISCOVERY.md** using /home/qualia/.claude/qualia-framework/templates/discovery.md structure:
-
-   - Summary with recommendation
-   - Key findings per option
-   - Code examples from Context7
-   - Confidence level (should be MEDIUM-HIGH for Level 2)
-
-7. Return to plan-phase.md.
-
-**Output:** `.planning/phases/XX-name/DISCOVERY.md`
-</step>
-
-<step name="level_3_deep_dive">
-**Level 3: Deep Dive (1+ hour)**
-
-For: Architectural decisions, novel problems, high-risk choices.
-
-**Process:**
-
-1. **Scope the discovery** using /home/qualia/.claude/qualia-framework/templates/discovery.md:
-
-   - Define clear scope
-   - Define include/exclude boundaries
-   - List specific questions to answer
-
-2. **Exhaustive Context7 research:**
-
-   - All relevant libraries
-   - Related patterns and concepts
-   - Multiple topics per library if needed
-
-3. **Official documentation deep read:**
-
-   - Architecture guides
-   - Best practices sections
-   - Migration/upgrade guides
-   - Known limitations
-
-4. **WebSearch for ecosystem context:**
-
-   - How others solved similar problems
-   - Production experiences
-   - Gotchas and anti-patterns
-   - Recent changes/announcements
-
-5. **Cross-verify ALL findings:**
-
-   - Every WebSearch claim → verify with authoritative source
-   - Mark what's verified vs assumed
-   - Flag contradictions
-
-6. **Create comprehensive DISCOVERY.md:**
-
-   - Full structure from /home/qualia/.claude/qualia-framework/templates/discovery.md
-   - Quality report with source attribution
-   - Confidence by finding
-   - If LOW confidence on any critical finding → add validation checkpoints
-
-7. **Confidence gate:** If overall confidence is LOW, present options before proceeding.
-
-8. Return to plan-phase.md.
-
-**Output:** `.planning/phases/XX-name/DISCOVERY.md` (comprehensive)
-</step>
-
-<step name="identify_unknowns">
-**For Level 2-3:** Define what we need to learn.
-
-Ask: What do we need to learn before we can plan this phase?
-
-- Technology choices?
-- Best practices?
-- API patterns?
-- Architecture approach?
-  </step>
-
-<step name="create_discovery_scope">
-Use /home/qualia/.claude/qualia-framework/templates/discovery.md.
-
-Include:
-
-- Clear discovery objective
-- Scoped include/exclude lists
-- Source preferences (official docs, Context7, current year)
-- Output structure for DISCOVERY.md
-  </step>
-
-<step name="execute_discovery">
-Run the discovery:
-- Use web search for current info
-- Use Context7 MCP for library docs
-- Prefer current year sources
-- Structure findings per template
-</step>
-
-<step name="create_discovery_output">
-Write `.planning/phases/XX-name/DISCOVERY.md`:
-- Summary with recommendation
-- Key findings with sources
-- Code examples if applicable
-- Metadata (confidence, dependencies, open questions, assumptions)
-</step>
-
-<step name="confidence_gate">
-After creating DISCOVERY.md, check confidence level.
-
-If confidence is LOW:
-Use AskUserQuestion:
-
-- header: "Low Confidence"
-- question: "Discovery confidence is LOW: [reason]. How would you like to proceed?"
-- options:
-  - "Dig deeper" - Do more research before planning
-  - "Proceed anyway" - Accept uncertainty, plan with caveats
-  - "Pause" - I need to think about this
-
-If confidence is MEDIUM:
-Inline: "Discovery complete (medium confidence). [brief reason]. Proceed to planning?"
-
-If confidence is HIGH:
-Proceed directly, just note: "Discovery complete (high confidence)."
-</step>
-
-<step name="open_questions_gate">
-If DISCOVERY.md has open_questions:
-
-Present them inline:
-"Open questions from discovery:
-
-- [Question 1]
-- [Question 2]
-
-These may affect implementation. Acknowledge and proceed? (yes / address first)"
-
-If "address first": Gather user input on questions, update discovery.
-</step>
-
-<step name="offer_next">
-```
-Discovery complete: .planning/phases/XX-name/DISCOVERY.md
-Recommendation: [one-liner]
-Confidence: [level]
-
-What's next?
-
-1. Discuss phase context (/qualia:discuss-phase [current-phase])
-2. Create phase plan (/qualia:plan-phase [current-phase])
-3. Refine discovery (dig deeper)
-4. Review discovery
-
-```
-
-NOTE: DISCOVERY.md is NOT committed separately. It will be committed with phase completion.
-</step>
-
-</process>
-
-<success_criteria>
-**Level 1 (Quick Verify):**
-- Context7 consulted for library/topic
-- Current state verified or concerns escalated
-- Verbal confirmation to proceed (no files)
-
-**Level 2 (Standard):**
-- Context7 consulted for all options
-- WebSearch findings cross-verified
-- DISCOVERY.md created with recommendation
-- Confidence level MEDIUM or higher
-- Ready to inform PLAN.md creation
-
-**Level 3 (Deep Dive):**
-- Discovery scope defined
-- Context7 exhaustively consulted
-- All WebSearch findings verified against authoritative sources
-- DISCOVERY.md created with comprehensive analysis
-- Quality report with source attribution
-- If LOW confidence findings → validation checkpoints defined
-- Confidence gate passed
-- Ready to inform PLAN.md creation
-</success_criteria>