mindsystem-cc 3.0.0

package/mindsystem/templates/DEBUG.md

@@ -0,0 +1,159 @@
+# 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 /ms: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/mindsystem/templates/UAT.md

@@ -0,0 +1,403 @@
+# UAT Template
+
+Template for `.planning/phases/XX-name/{phase}-UAT.md` — persistent UAT session tracking with mock support and inline fixing.
+
+---
+
+## File Template
+
+```markdown
+---
+status: testing | fixing | complete
+phase: XX-name
+source: [list of SUMMARY.md files tested]
+started: [ISO timestamp]
+updated: [ISO timestamp]
+current_batch: [N]
+mock_stash: [stash name or null]
+pre_work_stash: [stash name or null]
+---
+
+## Progress
+
+total: [N]
+tested: [N]
+passed: [N]
+issues: [N]
+fixing: [N]
+pending: [N]
+skipped: [N]
+
+## Current Batch
+
+batch: [N] of [total]
+name: "[batch name]"
+mock_type: [type or null]
+tests: [list of test numbers]
+status: pending | testing | complete
+
+## Tests
+
+### 1. [Test Name]
+expected: [observable behavior - what user should see]
+mock_required: [true/false]
+mock_type: [type or null]
+result: [pending]
+
+### 2. [Test Name]
+expected: [observable behavior]
+mock_required: false
+mock_type: null
+result: pass
+
+### 3. [Test Name]
+expected: [observable behavior]
+mock_required: true
+mock_type: error_state
+result: issue
+reported: "[verbatim user response]"
+severity: major
+fix_status: [investigating | applied | verified]
+fix_commit: [hash or null]
+retry_count: [0-2]
+
+### 4. [Test Name]
+expected: [observable behavior]
+mock_required: false
+mock_type: null
+result: blocked
+
+### 5. [Test Name]
+expected: [observable behavior]
+mock_required: true
+mock_type: premium_user
+result: skipped
+reason: [why couldn't be tested]
+
+...
+
+## Fixes Applied
+
+- commit: [hash]
+  test: [N]
+  description: "[what was fixed]"
+  files: [list of changed files]
+
+- commit: [hash]
+  test: [N]
+  description: "[what was fixed]"
+  files: [list of changed files]
+
+## Batches
+
+### Batch 1: No Mocks Required
+tests: [1, 2, 3]
+status: complete
+mock_type: null
+passed: 3
+issues: 0
+
+### Batch 2: Error States
+tests: [4, 5, 6, 7]
+status: in_progress
+mock_type: error_state
+passed: 1
+issues: 1
+
+### Batch 3: Premium Features
+tests: [8, 9, 10]
+status: pending
+mock_type: premium_user
+
+### Batch 4: Empty States
+tests: [11, 12]
+status: pending
+mock_type: empty_response
+
+## Assumptions
+
+- test: [N]
+  name: "[Test Name]"
+  expected: "[what should happen]"
+  reason: "[why it couldn't be tested]"
+
+- test: [N]
+  name: "[Test Name]"
+  expected: "[what should happen]"
+  reason: "[user-provided reason when skipping batch]"
+```
+
+---
+
+<section_rules>
+
+**Frontmatter:**
+- `status`: OVERWRITE - "testing", "fixing", 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_batch`: OVERWRITE - current batch number
+- `mock_stash`: OVERWRITE - name of stashed mocks or null
+- `pre_work_stash`: OVERWRITE - user's pre-existing work stash or null
+
+**Progress:**
+- OVERWRITE after each test result or fix
+- Tracks: total, tested, passed, issues, fixing, pending, skipped
+
+**Current Batch:**
+- OVERWRITE entirely on batch transitions
+- Shows which batch is active
+
+**Tests:**
+- Each test: OVERWRITE result/fix fields when status changes
+- `result` values: [pending], pass, issue, blocked, skipped
+- If issue: add `reported` (verbatim), `severity` (inferred), `fix_status`, `fix_commit`, `retry_count`
+- If blocked: no additional fields (will be re-tested)
+- If skipped: add `reason`
+
+**Fixes Applied:**
+- APPEND only when fix committed
+- Records commit hash, test number, description, files
+
+**Batches:**
+- Each batch: OVERWRITE status and counts as batch progresses
+- Tracks: tests, status, mock_type, passed, issues
+
+**Assumptions:**
+- APPEND when test is skipped
+- Records test number, name, expected behavior, reason
+
+</section_rules>
+
+<fix_lifecycle>
+
+**When issue reported:**
+1. result → "issue"
+2. Add `reported`, `severity`
+3. Add `fix_status: investigating`, `retry_count: 0`
+
+**When fix committed:**
+4. `fix_status: applied`
+5. `fix_commit: {hash}`
+6. Append to "Fixes Applied" section
+
+**When re-test passes:**
+7. result → "pass"
+8. `fix_status: verified`
+
+**When re-test fails:**
+9. Increment `retry_count`
+10. If `retry_count >= 2`: offer skip/escalate options
+11. If user chooses skip: result → "skipped", add reason
+
+</fix_lifecycle>
+
+<mock_lifecycle>
+
+**When batch needs mocks:**
+1. Generate mock files (uncommitted)
+2. User enables mocks
+3. Testing proceeds
+
+**When fix needed:**
+1. `git stash push -m "mocks-batch-N"`
+2. Update `mock_stash` in frontmatter
+3. Fix applied, committed
+4. `git stash pop` to restore mocks
+5. Clear `mock_stash` if no conflicts
+
+**On batch transition (different mock_type):**
+1. Discard old mocks: `git stash drop`
+2. Generate new mocks for new batch
+
+**On session complete:**
+1. Discard all mocks: `git stash drop`
+2. Restore pre_work_stash if exists
+
+</mock_lifecycle>
+
+<resume_behavior>
+
+On `/ms:verify-work` with existing UAT.md:
+
+1. Check `status`:
+   - "complete" → offer to re-run or view results
+   - "testing" or "fixing" → resume
+
+2. Check `mock_stash`:
+   - If exists, offer to restore or discard
+
+3. Check `current_batch`:
+   - Resume from that batch
+
+4. Check for tests with `fix_status: investigating` or `fix_status: applied`:
+   - Resume fix/re-test flow for those
+
+5. Present remaining tests in current batch
+
+</resume_behavior>
+
+<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, off, minor, small | minor |
+| Color, font, spacing, alignment, looks off | cosmetic |
+
+Default: **major** (safe default, user can clarify if wrong)
+
+</severity_guide>
+
+<good_example>
+```markdown
+---
+status: fixing
+phase: 04-comments
+source: 04-01-SUMMARY.md, 04-02-SUMMARY.md
+started: 2025-01-15T10:30:00Z
+updated: 2025-01-15T11:15:00Z
+current_batch: 2
+mock_stash: mocks-batch-2
+pre_work_stash: null
+---
+
+## Progress
+
+total: 12
+tested: 7
+passed: 5
+issues: 1
+fixing: 1
+pending: 5
+skipped: 0
+
+## Current Batch
+
+batch: 2 of 4
+name: "Error States"
+mock_type: error_state
+tests: [4, 5, 6, 7]
+status: testing
+
+## Tests
+
+### 1. View Comments on Post
+expected: Comments section expands, shows count and comment list
+mock_required: false
+mock_type: null
+result: pass
+
+### 2. Create Top-Level Comment
+expected: Submit comment via rich text editor, appears in list with author info
+mock_required: false
+mock_type: null
+result: pass
+
+### 3. Reply to a Comment
+expected: Click Reply, inline composer appears, submit shows nested reply
+mock_required: false
+mock_type: null
+result: pass
+
+### 4. Login Error Message
+expected: Invalid credentials show "Invalid email or password" message
+mock_required: true
+mock_type: error_state
+result: issue
+reported: "Shows 'Something went wrong' instead of specific error"
+severity: major
+fix_status: applied
+fix_commit: abc123f
+retry_count: 0
+
+### 5. Network Error Handling
+expected: No connection shows "Check your internet connection" with retry button
+mock_required: true
+mock_type: error_state
+result: [pending]
+
+### 6. Server Error Display
+expected: 500 error shows "Try again later" message
+mock_required: true
+mock_type: error_state
+result: [pending]
+
+### 7. Rate Limit Message
+expected: Too many requests shows "Too many attempts" with countdown
+mock_required: true
+mock_type: error_state
+result: [pending]
+
+### 8. Premium Badge Display
+expected: Premium users show gold badge on profile
+mock_required: true
+mock_type: premium_user
+result: [pending]
+
+### 9. Premium Feature Access
+expected: Premium features accessible, non-premium shows upgrade prompt
+mock_required: true
+mock_type: premium_user
+result: [pending]
+
+### 10. Subscription Status
+expected: Account page shows current subscription tier and expiry
+mock_required: true
+mock_type: premium_user
+result: [pending]
+
+### 11. Empty Comments List
+expected: Post with no comments shows "No comments yet" placeholder
+mock_required: true
+mock_type: empty_response
+result: [pending]
+
+### 12. Empty Search Results
+expected: Search with no matches shows "No results found" with suggestions
+mock_required: true
+mock_type: empty_response
+result: [pending]
+
+## Fixes Applied
+
+- commit: abc123f
+  test: 4
+  description: "Display actual error message from API response"
+  files: [src/components/ErrorBanner.tsx]
+
+## Batches
+
+### Batch 1: No Mocks Required
+tests: [1, 2, 3]
+status: complete
+mock_type: null
+passed: 3
+issues: 0
+
+### Batch 2: Error States
+tests: [4, 5, 6, 7]
+status: in_progress
+mock_type: error_state
+passed: 0
+issues: 1
+
+### Batch 3: Premium Features
+tests: [8, 9, 10]
+status: pending
+mock_type: premium_user
+
+### Batch 4: Empty States
+tests: [11, 12]
+status: pending
+mock_type: empty_response
+
+## Assumptions
+
+[none yet]
+```
+</good_example>

package/mindsystem/templates/adhoc-summary.md

@@ -0,0 +1,153 @@
+# Adhoc Summary Template
+
+Template for `.planning/adhoc/{timestamp}-{slug}-SUMMARY.md` — documentation for small work items executed via `/ms:do-work`.
+
+---
+
+## File Template
+
+```markdown
+---
+type: adhoc
+description: [user's original description]
+completed: [ISO timestamp]
+duration: [X min]
+related_phase: [current phase from STATE.md, or "none"]
+files_modified:
+  - [path/to/file1.ts]
+  - [path/to/file2.ts]
+commit: [git hash]
+---
+
+# Adhoc: [Description]
+
+**[Substantive one-liner describing what was done]**
+
+## What Was Done
+
+- [Most important outcome]
+- [Second accomplishment if applicable]
+
+## Files Modified
+
+- `[path/to/file.ts]`: [what changed]
+- `[path/to/other.ts]`: [what changed]
+
+## Verification
+
+- [what was verified]: [result]
+```
+
+<purpose>
+
+Adhoc summaries document small work items executed outside the normal phase workflow.
+
+**Differences from phase SUMMARY.md:**
+- Simplified frontmatter (no waves, depends_on, subsystem, tags)
+- No dependency graph (adhoc work is isolated by design)
+- No "Next Phase Readiness" (not part of phase sequence)
+- No deviations section (adhoc work is already unplanned)
+
+**Purpose:**
+- Audit trail for quick fixes
+- Context for future sessions (what was done between phases)
+- Git commit documentation
+
+</purpose>
+
+<frontmatter_fields>
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| type | Yes | Always "adhoc" |
+| description | Yes | User's original work description |
+| completed | Yes | ISO timestamp when work completed |
+| duration | Yes | Time spent (e.g., "12 min") |
+| related_phase | Yes | Current phase from STATE.md, or "none" if between phases |
+| files_modified | Yes | List of file paths changed |
+| commit | Yes | Git commit hash |
+
+</frontmatter_fields>
+
+<one_liner_rules>
+
+The one-liner MUST be substantive:
+
+**Good:**
+- "Added null check to prevent crash on empty user array"
+- "Fixed auth token refresh by handling 401 in interceptor"
+- "Added missing index on user_id for query performance"
+
+**Bad:**
+- "Fixed the bug"
+- "Made it work"
+- "Quick fix"
+
+The one-liner should tell someone what actually changed.
+
+</one_liner_rules>
+
+<example>
+
+```markdown
+---
+type: adhoc
+description: Fix auth token not refreshing on 401
+completed: 2026-01-20T14:32:00Z
+duration: 8 min
+related_phase: 03-user-dashboard
+files_modified:
+  - src/lib/api-client.ts
+  - src/hooks/useAuth.ts
+commit: abc123f
+---
+
+# Adhoc: Fix auth token not refreshing on 401
+
+**Added 401 response interceptor to trigger token refresh before retrying failed request**
+
+## What Was Done
+
+- Added response interceptor in api-client.ts to catch 401 errors
+- Integrated with useAuth hook to call refresh token endpoint
+- Added retry logic for original request after successful refresh
+
+## Files Modified
+
+- `src/lib/api-client.ts`: Added response interceptor with 401 handling
+- `src/hooks/useAuth.ts`: Exposed refreshToken function for interceptor use
+
+## Verification
+
+- Manually tested: Token expires → 401 → refresh triggered → request succeeds
+- No console errors during token refresh flow
+```
+
+</example>
+
+<guidelines>
+
+**When to create:**
+- After completing adhoc work via `/ms:do-work`
+- Required output from do-work workflow
+
+**Size:**
+- Keep brief — adhoc work is small by definition
+- 1-2 accomplishments typical
+- 1-3 files typical
+
+**Commit reference:**
+- Always include commit hash in frontmatter
+- Hash links summary to actual code changes
+- Enables `git show [hash]` for full diff
+
+**Related phase:**
+- If during phase execution: use current phase (e.g., "03-user-dashboard")
+- If between phases: use "none"
+- Helps contextualize when this work happened
+
+**After creation:**
+- STATE.md updated with entry in "Recent Adhoc Work"
+- File remains in `.planning/adhoc/` for audit trail
+
+</guidelines>