qualia-framework 2.1.0

package/framework/qualia-engine/workflows/discuss-phase.md

@@ -0,0 +1,534 @@
+<purpose>
+Extract implementation decisions that downstream agents need. Analyze the phase to identify gray areas, let the user choose what to discuss, then deep-dive each selected area until satisfied.
+
+You are a thinking partner, not an interviewer. The user is the visionary — you are the builder. Your job is to capture decisions that will guide research and planning, not to figure out implementation yourself.
+</purpose>
+
+<downstream_awareness>
+**CONTEXT.md feeds into:**
+
+1. **qualia-phase-researcher** — Reads CONTEXT.md to know WHAT to research
+   - "User wants card-based layout" → researcher investigates card component patterns
+   - "Infinite scroll decided" → researcher looks into virtualization libraries
+
+2. **qualia-planner** — Reads CONTEXT.md to know WHAT decisions are locked
+   - "Pull-to-refresh on mobile" → planner includes that in task specs
+   - "Claude's Discretion: loading skeleton" → planner can decide approach
+
+**Your job:** Capture decisions clearly enough that downstream agents can act on them without asking the user again.
+
+**Not your job:** Figure out HOW to implement. That's what research and planning do with the decisions you capture.
+</downstream_awareness>
+
+<philosophy>
+**User = founder/visionary. Claude = builder.**
+
+The user knows:
+- How they imagine it working
+- What it should look/feel like
+- What's essential vs nice-to-have
+- Specific behaviors or references they have in mind
+
+The user doesn't know (and shouldn't be asked):
+- Codebase patterns (researcher reads the code)
+- Technical risks (researcher identifies these)
+- Implementation approach (planner figures this out)
+- Success metrics (inferred from the work)
+
+Ask about vision and implementation choices. Capture decisions for downstream agents.
+</philosophy>
+
+<scope_guardrail>
+**CRITICAL: No scope creep.**
+
+The phase boundary comes from ROADMAP.md and is FIXED. Discussion clarifies HOW to implement what's scoped, never WHETHER to add new capabilities.
+
+**Allowed (clarifying ambiguity):**
+- "How should posts be displayed?" (layout, density, info shown)
+- "What happens on empty state?" (within the feature)
+- "Pull to refresh or manual?" (behavior choice)
+
+**Not allowed (scope creep):**
+- "Should we also add comments?" (new capability)
+- "What about search/filtering?" (new capability)
+- "Maybe include bookmarking?" (new capability)
+
+**The heuristic:** Does this clarify how we implement what's already in the phase, or does it add a new capability that could be its own phase?
+
+**When user suggests scope creep:**
+```
+"[Feature X] would be a new capability — that's its own phase.
+Want me to note it for the roadmap backlog?
+
+For now, let's focus on [phase domain]."
+```
+
+Capture the idea in a "Deferred Ideas" section. Don't lose it, don't act on it.
+</scope_guardrail>
+
+<gray_area_identification>
+Gray areas are **implementation decisions the user cares about** — things that could go multiple ways and would change the result.
+
+**How to identify gray areas:**
+
+1. **Read the phase goal** from ROADMAP.md
+2. **Understand the domain** — What kind of thing is being built?
+   - Something users SEE → visual presentation, interactions, states matter
+   - Something users CALL → interface contracts, responses, errors matter
+   - Something users RUN → invocation, output, behavior modes matter
+   - Something users READ → structure, tone, depth, flow matter
+   - Something being ORGANIZED → criteria, grouping, handling exceptions matter
+3. **Generate phase-specific gray areas** — Not generic categories, but concrete decisions for THIS phase
+
+**Don't use generic category labels** (UI, UX, Behavior). Generate specific gray areas:
+
+```
+Phase: "User authentication"
+→ Session handling, Error responses, Multi-device policy, Recovery flow
+
+Phase: "Organize photo library"
+→ Grouping criteria, Duplicate handling, Naming convention, Folder structure
+
+Phase: "CLI for database backups"
+→ Output format, Flag design, Progress reporting, Error recovery
+
+Phase: "API documentation"
+→ Structure/navigation, Code examples depth, Versioning approach, Interactive elements
+```
+
+**The key question:** What decisions would change the outcome that the user should weigh in on?
+
+**Claude handles these (don't ask):**
+- Technical implementation details
+- Architecture patterns
+- Performance optimization
+- Scope (roadmap defines this)
+</gray_area_identification>
+
+<process>
+
+<step name="initialize" priority="first">
+Phase number from argument (required).
+
+```bash
+INIT=$(node /home/qualia/.claude/qualia-engine/bin/qualia-tools.js init phase-op "${PHASE}")
+```
+
+Parse JSON for: `commit_docs`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`, `has_research`, `has_context`, `has_plans`, `has_verification`, `plan_count`, `roadmap_exists`, `planning_exists`.
+
+**If `phase_found` is false:**
+```
+Phase [X] not found in roadmap.
+
+Use /qualia:progress to see available phases.
+```
+Exit workflow.
+
+**If `phase_found` is true:** Continue to check_existing.
+</step>
+
+<step name="check_existing">
+Check if CONTEXT.md already exists using `has_context` from init.
+
+```bash
+ls ${phase_dir}/*-CONTEXT.md 2>/dev/null
+```
+
+**If exists:**
+Use AskUserQuestion:
+- header: "Existing context"
+- question: "Phase [X] already has context. What do you want to do?"
+- options:
+  - "Update it" — Review and revise existing context
+  - "View it" — Show me what's there
+  - "Skip" — Use existing context as-is
+
+If "Update": Load existing, continue to analyze_phase
+If "View": Display CONTEXT.md, then offer update/skip
+If "Skip": Exit workflow
+
+**If doesn't exist:** Continue to analyze_phase.
+</step>
+
+<step name="analyze_phase">
+Analyze the phase to identify gray areas worth discussing.
+
+**Read the phase description from ROADMAP.md and determine:**
+
+1. **Domain boundary** — What capability is this phase delivering? State it clearly.
+
+2. **Gray areas by category** — For each relevant category (UI, UX, Behavior, Empty States, Content), identify 1-2 specific ambiguities that would change implementation.
+
+3. **Skip assessment** — If no meaningful gray areas exist (pure infrastructure, clear-cut implementation), the phase may not need discussion.
+
+**Output your analysis internally, then present to user.**
+
+Example analysis for "Post Feed" phase:
+```
+Domain: Displaying posts from followed users
+Gray areas:
+- UI: Layout style (cards vs timeline vs grid)
+- UI: Information density (full posts vs previews)
+- Behavior: Loading pattern (infinite scroll vs pagination)
+- Empty State: What shows when no posts exist
+- Content: What metadata displays (time, author, reactions count)
+```
+
+**Frontend detection:**
+
+Determine if this phase involves frontend work by checking:
+1. Phase name/goal contains: UI, frontend, design, component, page, layout, dashboard, form, landing, hero, website, app
+2. Phase requirements reference visual/interactive deliverables
+3. ROADMAP.md phase description mentions user-facing interfaces
+
+Set `is_frontend_phase = true` if any indicator matches. This flag controls whether the design_consultation step runs.
+</step>
+
+<step name="present_gray_areas">
+Present the domain boundary and gray areas to user.
+
+**First, state the boundary:**
+```
+Phase [X]: [Name]
+Domain: [What this phase delivers — from your analysis]
+
+We'll clarify HOW to implement this.
+(New capabilities belong in other phases.)
+```
+
+**Then use AskUserQuestion (multiSelect: true):**
+- header: "Discuss"
+- question: "Which areas do you want to discuss for [phase name]?"
+- options: Generate 3-4 phase-specific gray areas, each formatted as:
+  - "[Specific area]" (label) — concrete, not generic
+  - [1-2 questions this covers] (description)
+
+**Do NOT include a "skip" or "you decide" option.** User ran this command to discuss — give them real choices.
+
+**Examples by domain:**
+
+For "Post Feed" (visual feature):
+```
+☐ Layout style — Cards vs list vs timeline? Information density?
+☐ Loading behavior — Infinite scroll or pagination? Pull to refresh?
+☐ Content ordering — Chronological, algorithmic, or user choice?
+☐ Post metadata — What info per post? Timestamps, reactions, author?
+```
+
+For "Database backup CLI" (command-line tool):
+```
+☐ Output format — JSON, table, or plain text? Verbosity levels?
+☐ Flag design — Short flags, long flags, or both? Required vs optional?
+☐ Progress reporting — Silent, progress bar, or verbose logging?
+☐ Error recovery — Fail fast, retry, or prompt for action?
+```
+
+For "Organize photo library" (organization task):
+```
+☐ Grouping criteria — By date, location, faces, or events?
+☐ Duplicate handling — Keep best, keep all, or prompt each time?
+☐ Naming convention — Original names, dates, or descriptive?
+☐ Folder structure — Flat, nested by year, or by category?
+```
+
+Continue to discuss_areas with selected areas.
+</step>
+
+<step name="discuss_areas">
+For each selected area, conduct a focused discussion loop.
+
+**Philosophy: 4 questions, then check.**
+
+Ask 4 questions per area before offering to continue or move on. Each answer often reveals the next question.
+
+**For each area:**
+
+1. **Announce the area:**
+   ```
+   Let's talk about [Area].
+   ```
+
+2. **Ask 4 questions using AskUserQuestion:**
+   - header: "[Area]"
+   - question: Specific decision for this area
+   - options: 2-3 concrete choices (AskUserQuestion adds "Other" automatically)
+   - Include "You decide" as an option when reasonable — captures Claude discretion
+
+3. **After 4 questions, check:**
+   - header: "[Area]"
+   - question: "More questions about [area], or move to next?"
+   - options: "More questions" / "Next area"
+
+   If "More questions" → ask 4 more, then check again
+   If "Next area" → proceed to next selected area
+
+4. **After all areas complete:**
+   - header: "Done"
+   - question: "That covers [list areas]. Ready to create context?"
+   - options: "Create context" / "Revisit an area"
+
+**Question design:**
+- Options should be concrete, not abstract ("Cards" not "Option A")
+- Each answer should inform the next question
+- If user picks "Other", receive their input, reflect it back, confirm
+
+**Scope creep handling:**
+If user mentions something outside the phase domain:
+```
+"[Feature] sounds like a new capability — that belongs in its own phase.
+I'll note it as a deferred idea.
+
+Back to [current area]: [return to current question]"
+```
+
+Track deferred ideas internally.
+</step>
+
+<step name="write_context">
+Create CONTEXT.md capturing decisions made.
+
+**Find or create phase directory:**
+
+Use values from init: `phase_dir`, `phase_slug`, `padded_phase`.
+
+If `phase_dir` is null (phase exists in roadmap but no directory):
+```bash
+mkdir -p ".planning/phases/${padded_phase}-${phase_slug}"
+```
+
+**File location:** `${phase_dir}/${padded_phase}-CONTEXT.md`
+
+**Structure the content by what was discussed:**
+
+```markdown
+# Phase [X]: [Name] - Context
+
+**Gathered:** [date]
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+[Clear statement of what this phase delivers — the scope anchor]
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### [Category 1 that was discussed]
+- [Decision or preference captured]
+- [Another decision if applicable]
+
+### [Category 2 that was discussed]
+- [Decision or preference captured]
+
+### Claude's Discretion
+[Areas where user said "you decide" — note that Claude has flexibility here]
+
+</decisions>
+
+<specifics>
+## Specific Ideas
+
+[Any particular references, examples, or "I want it like X" moments from discussion]
+
+[If none: "No specific requirements — open to standard approaches"]
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+[Ideas that came up but belong in other phases. Don't lose them.]
+
+[If none: "None — discussion stayed within phase scope"]
+
+</deferred>
+
+---
+
+*Phase: XX-name*
+*Context gathered: [date]*
+```
+
+Write file.
+</step>
+
+<step name="design_consultation">
+**Only runs if `is_frontend_phase = true`.** If false, skip to confirm_creation.
+
+**Check for existing DESIGN.md:**
+
+```bash
+find "$(pwd)" -maxdepth 1 -name "DESIGN.md" -o -path "./.planning/DESIGN.md" 2>/dev/null | head -1
+```
+
+**If DESIGN.md exists:** Read it, present current decisions, ask if user wants to update for this phase or keep as-is. If updating, proceed with consultation below but pre-fill known decisions.
+
+**If DESIGN.md does not exist:** Conduct full design consultation.
+
+**Design Consultation Flow:**
+
+Use AskUserQuestion for each design dimension. Present concrete options based on frontend-master skill principles.
+
+**1. Brand Personality & Aesthetic Direction**
+
+```
+header: "Design Direction"
+question: "What aesthetic direction fits this project?"
+options:
+  - "Brutally minimal — stark, purposeful, every element earns its place"
+  - "Editorial/magazine — strong typography, reading-focused, content-first"
+  - "Luxury/refined — subtle details, premium feel, sophisticated restraint"
+  - "Playful/energetic — bold colors, dynamic motion, personality-forward"
+  - "Other — I have a specific direction in mind"
+```
+
+**2. Color Palette**
+
+```
+header: "Color Palette"
+question: "What color direction do you want?"
+options:
+  - "Warm palette — earthy tones, terracotta, amber, warm neutrals"
+  - "Cool palette — ocean blues, slate, cool grays, mint"
+  - "Bold contrast — strong primary with sharp accents"
+  - "Muted/sophisticated — desaturated, tinted neutrals, subtle accents"
+  - "I have specific brand colors"
+```
+
+If "specific brand colors" selected, ask for hex values via follow-up question.
+
+**3. Typography**
+
+```
+header: "Typography"
+question: "What typography personality fits?"
+options:
+  - "Modern geometric — clean, structured, contemporary (e.g., Satoshi, General Sans)"
+  - "Elegant serif — refined, editorial, literary (e.g., Playfair Display, Cormorant)"
+  - "Humanist — warm, approachable, friendly (e.g., Source Sans, Nunito)"
+  - "Monospace accent — technical, developer-focused with monospace headings"
+  - "You decide — pick something distinctive that avoids Inter/Roboto/Arial"
+```
+
+**4. Motion Approach**
+
+```
+header: "Motion & Animation"
+question: "How much motion should the interface have?"
+options:
+  - "Minimal — subtle state transitions only, no entrance animations"
+  - "Purposeful — page load choreography + interaction feedback, nothing decorative"
+  - "Rich — orchestrated entrances, scroll effects, micro-interactions throughout"
+  - "You decide — match the aesthetic direction"
+```
+
+**5. Layout Philosophy**
+
+```
+header: "Layout"
+question: "What layout approach?"
+options:
+  - "Content-first — generous whitespace, single column focus, wide margins"
+  - "Information-dense — compact, multi-column, dashboard-style"
+  - "Asymmetric — editorial layouts, intentional grid-breaking, visual tension"
+  - "You decide — match the aesthetic direction"
+```
+
+**After all 5 dimensions discussed:**
+
+Generate DESIGN.md using the template from `@/home/qualia/.claude/qualia-engine/templates/DESIGN.md`, populating sections with the user's decisions.
+
+Write to `.planning/DESIGN.md` in the current project (NOT in the phase directory -- DESIGN.md is project-level).
+
+Update the `updated_in_phase` frontmatter field to the current phase number.
+
+```bash
+# Write DESIGN.md to project root's .planning directory
+cat > .planning/DESIGN.md << 'DESIGN_EOF'
+{populated template content}
+DESIGN_EOF
+```
+
+Announce:
+```
+Created: .planning/DESIGN.md
+
+Design decisions captured:
+- Aesthetic: {chosen direction}
+- Palette: {chosen palette}
+- Typography: {chosen approach}
+- Motion: {chosen approach}
+- Layout: {chosen approach}
+
+All design skills (/critique, /polish, /bolder, etc.) will read this file as their authoritative source.
+```
+</step>
+
+<step name="confirm_creation">
+Present summary and next steps:
+
+```
+Created: .planning/phases/${PADDED_PHASE}-${SLUG}/${PADDED_PHASE}-CONTEXT.md
+{If is_frontend_phase and DESIGN.md was created:}
+Created: .planning/DESIGN.md (design decisions)
+
+## Decisions Captured
+
+### [Category]
+- [Key decision]
+
+### [Category]
+- [Key decision]
+
+[If deferred ideas exist:]
+## Noted for Later
+- [Deferred idea] — future phase
+
+---
+
+## ▶ Next Up
+
+**Phase ${PHASE}: [Name]** — [Goal from ROADMAP.md]
+
+`/clear` then `/qualia:plan-phase ${PHASE}`
+
+---
+
+**Also available:**
+- `/qualia:plan-phase ${PHASE} --skip-research` — plan without research
+- Review/edit CONTEXT.md before continuing
+
+---
+```
+</step>
+
+<step name="git_commit">
+Commit phase context (uses `commit_docs` from init internally):
+
+```bash
+node /home/qualia/.claude/qualia-engine/bin/qualia-tools.js commit "docs(${padded_phase}): capture phase context" --files "${phase_dir}/${padded_phase}-CONTEXT.md"
+```
+
+If DESIGN.md was created/updated, include it in the commit:
+```bash
+node /home/qualia/.claude/qualia-engine/bin/qualia-tools.js commit "docs(${padded_phase}): capture phase context" --files "${phase_dir}/${padded_phase}-CONTEXT.md" ".planning/DESIGN.md"
+```
+
+Confirm: "Committed: docs(${padded_phase}): capture phase context"
+</step>
+
+</process>
+
+<success_criteria>
+- Phase validated against roadmap
+- Gray areas identified through intelligent analysis (not generic questions)
+- User selected which areas to discuss
+- Each selected area explored until user satisfied
+- Scope creep redirected to deferred ideas
+- CONTEXT.md captures actual decisions, not vague vision
+- Deferred ideas preserved for future phases
+- User knows next steps
+</success_criteria>