mindsystem-cc 3.20.0 → 3.21.0

package/mindsystem/workflows/complete-milestone.md

@@ -1,6 +1,6 @@
 <purpose>
 
-Mark a shipped version (v1.0, v1.1, v2.0) as complete. This creates a historical record in MILESTONES.md, performs full PROJECT.md evolution review, archives ROADMAP.md and REQUIREMENTS.md, and tags the release in git.
+Mark a shipped milestone as complete. This creates a historical record in MILESTONES.md, performs full PROJECT.md evolution review, and archives ROADMAP.md and REQUIREMENTS.md.
 
 </purpose>
 
@@ -20,9 +20,9 @@ Mark a shipped version (v1.0, v1.1, v2.0) as complete. This creates a historical
 
 When a milestone completes, this workflow:
 
-1. Creates `.planning/milestones/v[X.Y]/` directory for all archive files
-2. Extracts full milestone details to `.planning/milestones/v[X.Y]/ROADMAP.md`
-3. Archives requirements to `.planning/milestones/v[X.Y]/REQUIREMENTS.md`
+1. Creates `.planning/milestones/{slug}/` directory for all archive files
+2. Extracts full milestone details to `.planning/milestones/{slug}/ROADMAP.md`
+3. Archives requirements to `.planning/milestones/{slug}/REQUIREMENTS.md`
 4. Archives milestone files via script (audit, context, research — whichever exist)
 5. Consolidates phase summaries, deletes artifacts, moves phase dirs via script
 6. Deletes REQUIREMENTS.md (fresh one created for next milestone)
@@ -68,7 +68,7 @@ cat .planning/config.json 2>/dev/null
 Run the stats script to get readiness status and git statistics:
 
 ```bash
-~/.claude/mindsystem/scripts/gather-milestone-stats.sh $PHASE_START $PHASE_END
+ms-tools gather-milestone-stats $PHASE_START $PHASE_END
 ```
 
 The script outputs:
@@ -133,7 +133,7 @@ If exists, prepend new entry (reverse chronological order).
 Use template from `templates/milestone.md`:
 
 ```markdown
-## v[Version] [Name] (Shipped: YYYY-MM-DD)
+## [Name] (Shipped: YYYY-MM-DD)
 
 **Delivered:** [One sentence from user]
 
@@ -185,7 +185,7 @@ cat .planning/phases/*-*/*-SUMMARY.md
 
    **Validated section:**
    - All requirements shipped in this milestone → Add to Validated
-   - Format: `- ✓ [Requirement] — v[X.Y]`
+   - Format: `- ✓ [Requirement] — [Name]`
 
    **Out of Scope audit:**
    - Review each item — is the reasoning still valid?
@@ -218,10 +218,10 @@ Make all edits inline. Update "Last updated" footer:
 
 ```markdown
 ---
-*Last updated: [date] after v[X.Y] milestone*
+*Last updated: [date] after [Name] milestone*
 ```
 
-**Example full evolution (v1.0 → v1.1 prep):**
+**Example full evolution (MVP → Security & Polish prep):**
 
 Before:
 
@@ -249,7 +249,7 @@ Currently using Miro or physical whiteboards.
 - Video chat — use external tools
 ```
 
-After v1.0:
+After MVP:
 
 ```markdown
 ## What This Is
@@ -267,9 +267,9 @@ Currently using Miro but frustrated by complexity and latency.
 
 ## Validated
 
-- ✓ Canvas drawing tools — v1.0
-- ✓ Real-time sync < 500ms — v1.0 (achieved 200ms avg)
-- ✓ User authentication — v1.0
+- ✓ Canvas drawing tools — MVP
+- ✓ Real-time sync < 500ms — MVP (achieved 200ms avg)
+- ✓ User authentication — MVP
 
 ## Out of Scope
 
@@ -279,7 +279,7 @@ Currently using Miro but frustrated by complexity and latency.
 
 ## Technical Context
 
-Shipped v1.0 with 2,400 LOC TypeScript.
+Shipped MVP with 2,400 LOC TypeScript.
 Tech stack: Next.js, Supabase, Canvas API.
 Initial user testing showed demand for shape tools.
 ```
@@ -305,9 +305,9 @@ Extract completed milestone details and create archive file.
 
 1. Create milestone directory and archive file:
    ```bash
-   mkdir -p .planning/milestones/v[X.Y]
+   mkdir -p .planning/milestones/{slug}
    ```
-   Archive file path: `.planning/milestones/v[X.Y]/ROADMAP.md`
+   Archive file path: `.planning/milestones/{slug}/ROADMAP.md`
 
 2. Read `~/.claude/mindsystem/templates/milestone-archive.md` template
 
@@ -332,7 +332,7 @@ Extract completed milestone details and create archive file.
    - {{DECISIONS_FROM_PROJECT}} — Key decisions from PROJECT.md
    - {{ISSUES_RESOLVED_DURING_MILESTONE}} — From summaries
 
-6. Write filled template to `.planning/milestones/v[X.Y]/ROADMAP.md`
+6. Write filled template to `.planning/milestones/{slug}/ROADMAP.md`
 
 7. Delete ROADMAP.md (fresh one created for next milestone):
    ```bash
@@ -341,17 +341,17 @@ Extract completed milestone details and create archive file.
 
 8. Verify archive exists:
    ```bash
-   ls .planning/milestones/v[X.Y]/ROADMAP.md
+   ls .planning/milestones/{slug}/ROADMAP.md
    ```
 
 9. Confirm roadmap archive complete:
 
    ```
-   ✅ v[X.Y] roadmap archived to milestones/v[X.Y]/ROADMAP.md
+   ✅ Roadmap archived to milestones/{slug}/ROADMAP.md
    ✅ ROADMAP.md deleted (fresh one for next milestone)
    ```
 
-**Note:** Phase directories are moved to `milestones/v[X.Y]/phases/` by the archive_and_cleanup_phases step. After milestone completion, `.planning/phases/` contains only the next milestone's work. Phase numbering continues (v1.0 phases 1-4, v1.1 phases 5-8, etc.).
+**Note:** Phase directories are moved to `milestones/{slug}/phases/` by the archive_and_cleanup_phases step. After milestone completion, `.planning/phases/` contains only the next milestone's work. Phase numbering continues (MVP phases 1-4, next milestone phases 5-8, etc.).
 
 </step>
 
@@ -366,7 +366,7 @@ Archive requirements and prepare for fresh requirements in next milestone.
    cat .planning/REQUIREMENTS.md
    ```
 
-2. Create archive file: `.planning/milestones/v[X.Y]/REQUIREMENTS.md`
+2. Create archive file: `.planning/milestones/{slug}/REQUIREMENTS.md`
 
 3. Transform requirements for archive:
    - Mark all v1 requirements as `[x]` complete
@@ -379,12 +379,12 @@ Archive requirements and prepare for fresh requirements in next milestone.
 
 4. Write archive file with header:
    ```markdown
-   # Requirements Archive: v[X.Y] [Milestone Name]
+   # Requirements Archive: [Milestone Name]
 
    **Archived:** [DATE]
    **Status:** ✅ SHIPPED
 
-   This is the archived requirements specification for v[X.Y].
+   This is the archived requirements specification for [Milestone Name].
    For current requirements, see `.planning/REQUIREMENTS.md` (created for next milestone).
 
    ---
@@ -400,7 +400,7 @@ Archive requirements and prepare for fresh requirements in next milestone.
    **Dropped:** [list any requirements removed and why]
 
    ---
-   *Archived: [DATE] as part of v[X.Y] milestone completion*
+   *Archived: [DATE] as part of [Milestone Name] milestone completion*
    ```
 
 5. Delete original REQUIREMENTS.md:
@@ -410,7 +410,7 @@ Archive requirements and prepare for fresh requirements in next milestone.
 
 6. Confirm:
    ```
-   ✅ Requirements archived to milestones/v[X.Y]/REQUIREMENTS.md
+   ✅ Requirements archived to milestones/{slug}/REQUIREMENTS.md
    ✅ REQUIREMENTS.md deleted (fresh one needed for next milestone)
    ```
 
@@ -423,7 +423,7 @@ Archive requirements and prepare for fresh requirements in next milestone.
 Archive optional milestone files (audit, context, research) to the milestone directory:
 
 ```bash
-~/.claude/mindsystem/scripts/archive-milestone-files.sh v[X.Y]
+ms-tools archive-milestone-files {slug}
 ```
 
 The script moves whichever files exist and reports what was archived. Files that don't exist are skipped silently.
@@ -435,22 +435,22 @@ The script moves whichever files exist and reports what was archived. Files that
 Consolidate phase summaries, delete raw artifacts, and move phase directories to the milestone archive. This runs after all steps that read summaries (extract_accomplishments, evolve_project_full_review) and after archive_milestone creates the milestone directory.
 
 ```bash
-~/.claude/mindsystem/scripts/archive-milestone-phases.sh $PHASE_START $PHASE_END v[X.Y]
+ms-tools archive-milestone-phases $PHASE_START $PHASE_END {slug}
 ```
 
 Verify archive:
 
 ```bash
-ls .planning/milestones/v[X.Y]/PHASE-SUMMARIES.md
-ls .planning/milestones/v[X.Y]/phases/
+ls .planning/milestones/{slug}/PHASE-SUMMARIES.md
+ls .planning/milestones/{slug}/phases/
 ```
 
 Present:
 
 ```
-✅ Phase summaries consolidated to milestones/v[X.Y]/PHASE-SUMMARIES.md
+✅ Phase summaries consolidated to milestones/{slug}/PHASE-SUMMARIES.md
 ✅ Raw artifacts deleted from phase directories
-✅ Phase directories moved to milestones/v[X.Y]/phases/
+✅ Phase directories moved to milestones/{slug}/phases/
 ✅ .planning/phases/ clean for next milestone
 ```
 
@@ -479,7 +479,7 @@ See: .planning/PROJECT.md (updated [today])
 Phase: [Next phase] of [Total] ([Phase name])
 Plan: Not started
 Status: Ready to plan
-Last activity: [today] — v[X.Y] milestone complete
+Last activity: [today] — [Name] milestone complete
 
 Progress: [updated progress bar]
 ```
@@ -492,45 +492,13 @@ Progress: [updated progress bar]
 
 </step>
 
-<step name="git_tag">
-
-Create git tag for milestone:
-
-```bash
-git tag -a v[X.Y] -m "$(cat <<'EOF'
-v[X.Y] [Name]
-
-Delivered: [One sentence]
-
-Key accomplishments:
-- [Item 1]
-- [Item 2]
-- [Item 3]
-
-See .planning/MILESTONES.md for full details.
-EOF
-)"
-```
-
-Confirm: "Tagged: v[X.Y]"
-
-Ask: "Push tag to remote? (y/n)"
-
-If yes:
-
-```bash
-git push origin v[X.Y]
-```
-
-</step>
-
 <step name="git_commit_milestone">
 
 Commit milestone completion including archive files and deletions.
 
 ```bash
 # Stage archive directory (covers ROADMAP, REQUIREMENTS, AUDIT, CONTEXT, research)
-git add .planning/milestones/v[X.Y]/
+git add .planning/milestones/{slug}/
 
 # Stage updated files
 git add .planning/MILESTONES.md
@@ -542,9 +510,9 @@ git add -u .planning/
 
 # Commit with descriptive message
 git commit -m "$(cat <<'EOF'
-chore: complete v[X.Y] milestone
+chore: complete [Name] milestone
 
-Archived to milestones/v[X.Y]/:
+Archived to milestones/{slug}/:
 - ROADMAP.md
 - REQUIREMENTS.md
 - PHASE-SUMMARIES.md (consolidated from phase directories)
@@ -567,32 +535,29 @@ Updated:
 - MILESTONES.md (new entry)
 - PROJECT.md (requirements → Validated)
 - STATE.md (reset for next milestone)
-
-Tagged: v[X.Y]
 EOF
 )"
 ```
 
-Confirm: "Committed: chore: complete v[X.Y] milestone"
+Confirm: "Committed: chore: complete [Name] milestone"
 
 </step>
 
 <step name="offer_next">
 
 ```
-✅ Milestone v[X.Y] [Name] complete
+✅ Milestone [Name] complete
 
 Shipped:
 - [N] phases ([M] plans, [P] tasks)
 - [One sentence of what shipped]
 
-Archived to milestones/v[X.Y]/:
+Archived to milestones/{slug}/:
 - ROADMAP.md
 - REQUIREMENTS.md
 - research/ (if existed)
 
 Summary: .planning/MILESTONES.md
-Tag: v[X.Y]
 
 ---
 
@@ -624,8 +589,8 @@ Milestone completion is successful when (ordered by skip risk):
 - [ ] All shipped requirements moved to Validated in PROJECT.md
 - [ ] Key Decisions updated with outcomes
 - [ ] MILESTONES.md entry created with stats and accomplishments
-- [ ] Roadmap archive created (milestones/v[X.Y]/ROADMAP.md)
-- [ ] Requirements archive created (milestones/v[X.Y]/REQUIREMENTS.md)
+- [ ] Roadmap archive created (milestones/{slug}/ROADMAP.md)
+- [ ] Requirements archive created (milestones/{slug}/REQUIREMENTS.md)
 - [ ] REQUIREMENTS.md deleted (fresh for next milestone)
 - [ ] STATE.md updated with fresh project reference
 

package/mindsystem/workflows/discuss-phase.md

@@ -1,29 +1,25 @@
 <purpose>
-Gather phase context through collaborative thinking before planning. Help the user articulate their vision for how this phase should work, look, and feel.
+Gather phase context through product-informed collaborative thinking before planning. Act as a collaborative product owner — loading milestone-level artifacts, surfacing assumptions, optionally researching competitors, and grounding every question in product analysis.
 
-You are a thinking partner, not an interviewer. The user is the visionary — you are the builder. Your job is to understand their vision, not interrogate them about technical details you can figure out yourself.
+You are a thinking partner, not an interviewer. The user is the visionary — you are the builder with product sense. Your job is to understand their vision, ground it in industry context, and help them make informed decisions.
 </purpose>
 
 <philosophy>
-**User = founder/visionary. Claude = builder.**
+The user knows vision, priorities, and preferences. They don't know codebase patterns, technical risks, or implementation constraints — you figure those out.
 
-The user doesn't know (and shouldn't need to know):
-- Codebase patterns (you read the code)
-- Technical risks (you identify during research)
-- Implementation constraints (you figure those out)
-- Success metrics (you infer from the work)
-
-The user DOES know:
-- How they imagine it working
-- What it should look/feel like
-- What's essential vs nice-to-have
-- Any specific things they have in mind
+**Product-thinking lens (analytical tool, not checklist):**
+- Ground analysis in target audience (Who It's For from PROJECT.md)
+- Focus on what moves the needle (Core Value)
+- Think in systems, not features — how does this phase connect to the whole?
+- Validate against industry patterns, don't blindly follow them
 
-Ask about vision. Figure out implementation yourself.
+Ask about vision. Apply product thinking. Figure out implementation yourself.
 </philosophy>
 
 <process>
 
+<!-- STAGE 1: LOAD + ASSESS -->
+
 <step name="validate_phase" priority="first">
 Phase number: $ARGUMENTS (required)
 
@@ -51,30 +47,33 @@ Parse phase details from roadmap:
 - Phase description
 - Status (should be "Not started" or "In progress")
 
-Continue to load_prior_knowledge.
+Continue to load_context.
 </step>
 
-<step name="load_prior_knowledge">
-Determine which subsystem(s) this phase touches from ROADMAP.md phase description + config.json:
+<step name="load_context">
+Load milestone artifacts and prior knowledge. Handle gracefully when any file is missing.
 
 ```bash
+cat .planning/PROJECT.md 2>/dev/null
+cat .planning/MILESTONE-CONTEXT.md 2>/dev/null
+cat .planning/REQUIREMENTS.md 2>/dev/null
 jq -r '.subsystems[]' .planning/config.json 2>/dev/null
 grep -A20 "Phase ${PHASE}:" .planning/ROADMAP.md
 ```
 
-Load matching `knowledge/{subsystem}.md` files:
+Extract from PROJECT.md: **Who It's For**, **Core Value**, **How It's Different**
+
+Extract from REQUIREMENTS.md: Requirements mapped to this phase (match phase number/name against requirement tags)
+
+Load matching `knowledge/{subsystem}.md` files for subsystems this phase touches:
 
 ```bash
 cat .planning/knowledge/{subsystem}.md 2>/dev/null
 ```
 
-Handle gracefully when `.planning/knowledge/` doesn't exist (first milestone, no phases executed yet).
-
-**If knowledge exists:** Present a brief "What we know so far" summary to the user before questioning — prior decisions, architectural patterns, and pitfalls relevant to this phase. This grounds the discussion without interrogating.
+**If knowledge exists:** Present a brief "What we know so far" summary — prior decisions, patterns, and pitfalls relevant to this phase.
 
 **If no knowledge files exist:** Skip silently (normal for first phase).
-
-Continue to check_existing.
 </step>
 
 <step name="check_existing">
@@ -98,75 +97,142 @@ What's next?
 
 Wait for user response.
 
-If "Update context": Load existing CONTEXT.md, continue to questioning
+If "Update context": Load existing CONTEXT.md, continue to assess_and_research
 If "View existing": Read and display CONTEXT.md, then offer update/skip
 If "Skip": Exit workflow
 
 **If doesn't exist:**
-Continue to questioning.
+Continue to assess_and_research.
 </step>
 
-<step name="questioning">
-**CRITICAL: ALL questions use AskUserQuestion. Never ask inline text questions.**
+<!-- STAGE 2: BRIEFING + CONDITIONAL RESEARCH -->
+
+<step name="assess_and_research">
+Parse the requirements mapped to this phase from REQUIREMENTS.md and the phase description from ROADMAP.md.
+
+**Assess whether product research would add value:**
 
-Present initial context from roadmap, then immediately use AskUserQuestion:
+Research is valuable when the phase involves user-facing product decisions where competitor context, UX patterns, or audience expectations would inform better choices. Examples: UI layouts, user flows, feature scope, interaction patterns.
+
+Research is NOT valuable for: backend infrastructure, data migrations, build tooling, refactoring, developer-facing work with no UX decisions.
+
+**If research would add value:**
+
+Use AskUserQuestion:
+- header: "Research"
+- question: "This phase involves product decisions where competitor and UX research could help. Want me to research how others handle this before we discuss?"
+- options:
+  - "Research first" — Investigate competitors and UX patterns (~30s)
+  - "Skip research" — Discuss based on what we know
+
+**If user selects "Research first":**
+
+Spawn ms-product-researcher subagent via Task tool:
 
 ```
-Phase ${PHASE}: ${PHASE_NAME}
+<product_context>
+[Who It's For, Core Value, How It's Different from PROJECT.md]
+</product_context>
+
+<phase_requirements>
+[Phase goal, description, mapped requirements from ROADMAP.md/REQUIREMENTS.md]
+</phase_requirements>
 
-From the roadmap: ${PHASE_DESCRIPTION}
+<research_focus>
+[Specific product questions relevant to this phase — what would help the user decide?]
+</research_focus>
 ```
 
-**1. Open:**
+Store research findings for use in present_briefing and questioning steps.
 
-Use AskUserQuestion:
-- header: "Vision"
-- question: "How do you imagine this working?"
-- options: 2-3 interpretations based on the phase description + "Let me describe it"
+**If user selects "Skip research" or research not valuable:**
+Continue without research findings.
+</step>
+
+<step name="present_briefing">
+Present a consolidated briefing that weaves together all loaded context.
+
+```
+## Phase ${PHASE}: ${PHASE_NAME}
 
-**2. Follow the thread:**
+### What This Phase Delivers
+[Requirements mapped to this phase from REQUIREMENTS.md, or phase goal from ROADMAP.md if no requirements mapping]
 
-Based on their response, use AskUserQuestion:
-- header: "[Topic they mentioned]"
-- question: "You mentioned [X] — what would that look like?"
-- options: 2-3 interpretations + "Something else"
+### My Assumptions
+- **Approach:** How Claude would tackle this
+- **Scope:** What's included vs excluded
+- **Risks/Dependencies:** Where Claude expects complexity or unknowns
 
-**3. Sharpen the core:**
+[If research findings available:]
+### Industry Context
+[Key findings from product research — competitor patterns, UX conventions, audience expectations. Dense, prescriptive summary.]
+```
 
-Use AskUserQuestion with multiSelect: true:
-- header: "Essential"
-- question: "What's most important to nail in this phase? Select all that apply."
-- options: Key aspects they've mentioned
+Then use AskUserQuestion:
+- header: "Assumptions"
+- question: "Are these assumptions on track? Anything I'm getting wrong or missing?"
+- options:
+  - "Looks right" — Assumptions are accurate, let's continue
+  - "Some corrections" — I have specific corrections
+  - "Way off" — Let me reframe this
 
-**4. Capture specifics (optional):**
+**If "Some corrections" or "Way off":** Receive corrections, acknowledge, update understanding. Then continue to questioning.
+**If "Looks right":** Continue to questioning.
+</step>
 
-If they seem to have specific ideas, use AskUserQuestion:
-- header: "Specifics"
-- question: "Any particular look/feel/behavior in mind?"
-- options: Contextual options based on what they've said + "No specifics" + "Let me describe"
+<!-- STAGE 3: INFORMED DISCUSSION -->
 
-CRITICAL — What NOT to ask:
+<step name="questioning">
+**ALL questions use AskUserQuestion. Never ask inline text questions.**
+
+What NOT to ask — the user doesn't know and shouldn't be asked about:
 - Technical risks (you figure those out)
 - Codebase patterns (you read the code)
 - Success metrics (too corporate)
 - Constraints they didn't mention (don't interrogate)
 - What's out of scope (implicit from roadmap)
 
-**5. Decision gate:**
+**Scope guardrail:** Phase boundary from ROADMAP.md is FIXED. Discussion clarifies HOW to implement, not WHETHER to add more. If user suggests new capabilities: "That sounds like its own phase. I'll note it in Deferred Ideas."
+
+**Product lens:** Before each question, show brief analysis — audience needs, competitor patterns (from research if available), tradeoffs and recommendation. This grounds the user's decision.
+
+**1. Open:**
+
+Present brief product analysis, then use AskUserQuestion:
+- header: "Vision"
+- question: "How do you imagine this working?"
+- options: 2-3 interpretations based on phase description, requirements, and industry context + "Let me describe it"
+
+**2. Follow the thread (2-4 rounds typical):**
+
+Follow the user's thread. Each round: apply product lens to the topic they raised, then AskUserQuestion with 2-3 interpretations + escape hatch. Use multiSelect for priority/essential questions. Stop when vision is clear — don't over-question.
+
+**3. Decision gate:**
+
+Present a coverage summary before offering to finalize:
+
+```
+### Coverage Summary
+**Discussed:** [Topics covered during this conversation]
+**From artifacts:** [Context loaded from PROJECT.md, REQUIREMENTS.md, research]
+**Open areas:** [Anything from the requirements/roadmap not yet discussed — or "None" if comprehensive]
+```
 
 Use AskUserQuestion:
 - header: "Ready?"
 - question: "Ready to capture this context, or explore more?"
 - options (ALL THREE REQUIRED):
-  - "Create CONTEXT.md" - I've shared my vision
-  - "Ask more questions" - Help me think through this more
-  - "Let me add context" - I have more to share
+  - "Create CONTEXT.md" — I've shared my vision
+  - "Ask more questions" — Help me think through this more
+  - "Let me add context" — I have more to share
 
 If "Ask more questions" → return to step 2 with new probes.
 If "Let me add context" → receive input → return to step 2.
 Loop until "Create CONTEXT.md" selected.
 </step>
 
+<!-- STAGE 4: OUTPUT -->
+
 <step name="write_context">
 Create CONTEXT.md capturing the user's vision and decisions.
 
@@ -188,15 +254,10 @@ Populate template sections:
 - `<notes>`: Any other context gathered
 
 **Decision context (for downstream agents):**
-- `<decisions>`: Concrete choices made during discussion (locked)
+- `<decisions>`: Concrete choices made during discussion (locked). Include inline reasoning grounded in vision, audience, competitor patterns, or tradeoff analysis: `- [Decision] — [Why: reasoning]`
 - `### Claude's Discretion`: Areas where user said "you decide" or didn't express preference
 - `<deferred>`: Ideas mentioned but explicitly out of scope
 
-**Scope guardrail:**
-- Phase boundary from ROADMAP.md is FIXED
-- Discussion clarifies HOW to implement, not WHETHER to add more
-- If user suggests new capabilities: "That sounds like its own phase. I'll note it in Deferred Ideas."
-
 Do NOT populate with your own technical analysis. That comes during research/planning.
 
 Write file.
@@ -254,12 +315,23 @@ EOF
 Confirm: "Committed: docs(${PHASE}): capture phase context"
 </step>
 
+<step name="show_prework_status">
+Read `~/.claude/mindsystem/references/prework-status.md` and present what's done vs still needed for this phase.
+</step>
+
+<step name="update_state">
+Update `.planning/STATE.md` Last Command field:
+
+Format: `Last Command: ms:discuss-phase ${PHASE} | YYYY-MM-DD HH:MM`
+</step>
+
 </process>
 
 <success_criteria>
 
-- Vision gathered through collaborative thinking (not interrogation)
-- User's imagination captured: how it works, what's essential
+- Assumptions surfaced and validated with user before deep questioning
+- Product research offered for user-facing phases (skipped silently for infra/backend)
+- Vision gathered through product-informed collaborative thinking (not interrogation)
+- CONTEXT.md captures: vision, essentials, and decisions with inline reasoning
 - User knows next steps (typically: research or plan the phase)
-- CONTEXT.md committed to git
 </success_criteria>