@massu/core 0.5.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (118) hide show
  1. package/README.md +40 -0
  2. package/agents/massu-architecture-reviewer.md +104 -0
  3. package/agents/massu-blast-radius-analyzer.md +84 -0
  4. package/agents/massu-competitive-scorer.md +126 -0
  5. package/agents/massu-help-sync.md +73 -0
  6. package/agents/massu-migration-writer.md +94 -0
  7. package/agents/massu-output-scorer.md +87 -0
  8. package/agents/massu-pattern-reviewer.md +84 -0
  9. package/agents/massu-plan-auditor.md +170 -0
  10. package/agents/massu-schema-sync-verifier.md +70 -0
  11. package/agents/massu-security-reviewer.md +98 -0
  12. package/agents/massu-ux-reviewer.md +106 -0
  13. package/commands/_shared-preamble.md +53 -23
  14. package/commands/_shared-references/auto-learning-protocol.md +71 -0
  15. package/commands/_shared-references/blast-radius-protocol.md +76 -0
  16. package/commands/_shared-references/security-pre-screen.md +64 -0
  17. package/commands/_shared-references/test-first-protocol.md +87 -0
  18. package/commands/_shared-references/verification-table.md +52 -0
  19. package/commands/massu-article-review.md +343 -0
  20. package/commands/massu-autoresearch/references/eval-runner.md +84 -0
  21. package/commands/massu-autoresearch/references/safety-rails.md +125 -0
  22. package/commands/massu-autoresearch/references/scoring-protocol.md +151 -0
  23. package/commands/massu-autoresearch.md +258 -0
  24. package/commands/massu-batch.md +44 -12
  25. package/commands/massu-bearings.md +42 -8
  26. package/commands/massu-checkpoint.md +588 -0
  27. package/commands/massu-ci-fix.md +2 -2
  28. package/commands/massu-command-health.md +132 -0
  29. package/commands/massu-command-improve.md +232 -0
  30. package/commands/massu-commit.md +205 -44
  31. package/commands/massu-create-plan.md +239 -57
  32. package/commands/massu-data/references/common-queries.md +79 -0
  33. package/commands/massu-data/references/table-guide.md +50 -0
  34. package/commands/massu-data.md +66 -0
  35. package/commands/massu-dead-code.md +29 -34
  36. package/commands/massu-debug/references/auto-learning.md +61 -0
  37. package/commands/massu-debug/references/codegraph-tracing.md +80 -0
  38. package/commands/massu-debug/references/common-shortcuts.md +98 -0
  39. package/commands/massu-debug/references/investigation-phases.md +294 -0
  40. package/commands/massu-debug/references/report-format.md +107 -0
  41. package/commands/massu-debug.md +105 -386
  42. package/commands/massu-docs.md +1 -1
  43. package/commands/massu-full-audit.md +61 -0
  44. package/commands/massu-gap-enhancement-analyzer.md +276 -16
  45. package/commands/massu-golden-path/references/approval-points.md +216 -0
  46. package/commands/massu-golden-path/references/competitive-mode.md +273 -0
  47. package/commands/massu-golden-path/references/error-handling.md +121 -0
  48. package/commands/massu-golden-path/references/phase-0-requirements.md +53 -0
  49. package/commands/massu-golden-path/references/phase-1-plan-creation.md +168 -0
  50. package/commands/massu-golden-path/references/phase-2-implementation.md +397 -0
  51. package/commands/massu-golden-path/references/phase-2.5-gap-analyzer.md +156 -0
  52. package/commands/massu-golden-path/references/phase-3-simplify.md +40 -0
  53. package/commands/massu-golden-path/references/phase-4-commit.md +94 -0
  54. package/commands/massu-golden-path/references/phase-5-push.md +116 -0
  55. package/commands/massu-golden-path/references/phase-5.5-production-verify.md +170 -0
  56. package/commands/massu-golden-path/references/phase-6-completion.md +113 -0
  57. package/commands/massu-golden-path/references/qa-evaluator-spec.md +137 -0
  58. package/commands/massu-golden-path/references/sprint-contract-protocol.md +117 -0
  59. package/commands/massu-golden-path/references/vr-visual-calibration.md +73 -0
  60. package/commands/massu-golden-path.md +114 -848
  61. package/commands/massu-guide.md +72 -69
  62. package/commands/massu-hooks.md +27 -12
  63. package/commands/massu-hotfix.md +221 -144
  64. package/commands/massu-incident.md +49 -20
  65. package/commands/massu-infra-audit.md +187 -0
  66. package/commands/massu-learning-audit.md +211 -0
  67. package/commands/massu-loop/references/auto-learning.md +49 -0
  68. package/commands/massu-loop/references/checkpoint-audit.md +40 -0
  69. package/commands/massu-loop/references/guardrails.md +17 -0
  70. package/commands/massu-loop/references/iteration-structure.md +115 -0
  71. package/commands/massu-loop/references/loop-controller.md +188 -0
  72. package/commands/massu-loop/references/plan-extraction.md +78 -0
  73. package/commands/massu-loop/references/vr-plan-spec.md +140 -0
  74. package/commands/massu-loop-playwright.md +9 -9
  75. package/commands/massu-loop.md +115 -670
  76. package/commands/massu-new-pattern.md +423 -0
  77. package/commands/massu-perf.md +422 -0
  78. package/commands/massu-plan-audit.md +1 -1
  79. package/commands/massu-plan.md +389 -122
  80. package/commands/massu-production-verify.md +433 -0
  81. package/commands/massu-push.md +62 -378
  82. package/commands/massu-recap.md +29 -3
  83. package/commands/massu-rollback.md +613 -0
  84. package/commands/massu-scaffold-hook.md +2 -4
  85. package/commands/massu-scaffold-page.md +2 -3
  86. package/commands/massu-scaffold-router.md +1 -2
  87. package/commands/massu-security.md +619 -0
  88. package/commands/massu-simplify.md +115 -85
  89. package/commands/massu-squirrels.md +2 -2
  90. package/commands/massu-tdd.md +38 -22
  91. package/commands/massu-test.md +3 -3
  92. package/commands/massu-type-mismatch-audit.md +469 -0
  93. package/commands/massu-ui-audit.md +587 -0
  94. package/commands/massu-verify-playwright.md +287 -32
  95. package/commands/massu-verify.md +150 -46
  96. package/dist/cli.js +146 -95
  97. package/package.json +6 -2
  98. package/patterns/build-patterns.md +302 -0
  99. package/patterns/component-patterns.md +246 -0
  100. package/patterns/display-patterns.md +185 -0
  101. package/patterns/form-patterns.md +890 -0
  102. package/patterns/integration-testing-checklist.md +445 -0
  103. package/patterns/security-patterns.md +219 -0
  104. package/patterns/testing-patterns.md +569 -0
  105. package/patterns/tool-routing.md +81 -0
  106. package/patterns/ui-patterns.md +371 -0
  107. package/protocols/plan-implementation.md +267 -0
  108. package/protocols/recovery.md +225 -0
  109. package/protocols/verification.md +404 -0
  110. package/reference/command-taxonomy.md +178 -0
  111. package/reference/cr-rules-reference.md +76 -0
  112. package/reference/hook-execution-order.md +148 -0
  113. package/reference/lessons-learned.md +175 -0
  114. package/reference/patterns-quickref.md +208 -0
  115. package/reference/standards.md +135 -0
  116. package/reference/subagents-reference.md +17 -0
  117. package/reference/vr-verification-reference.md +867 -0
  118. package/src/commands/install-commands.ts +149 -53
@@ -0,0 +1,107 @@
1
+ # Debug Report Format
2
+
3
+ Templates for the debug report and session state update.
4
+
5
+ ---
6
+
7
+ ## Debug Report Template
8
+
9
+ ```markdown
10
+ ## MASSU DEBUG REPORT
11
+
12
+ ### Issue Summary
13
+ - **Reported**: [symptom]
14
+ - **Environment**: [DEV/PROD]
15
+ - **Severity**: P0/P1/P2
16
+
17
+ ### Root Cause
18
+ [Technical explanation]
19
+
20
+ ### CLAUDE.md Alignment
21
+ - Violation found: YES/NO
22
+ - Rule: [if yes]
23
+
24
+ ### Fix
25
+ - Files changed: [list]
26
+ - Pattern applied: [from CLAUDE.md]
27
+
28
+ ### Verification Evidence
29
+ | Check | Command | Result | Status |
30
+ |-------|---------|--------|--------|
31
+ | Build | npm run build | Exit 0 | PASS |
32
+ | Types | npx tsc --noEmit | 0 errors | PASS |
33
+ | Patterns | ./scripts/pattern-scanner.sh | Exit 0 | PASS |
34
+ | VR-NEGATIVE | grep [old] | 0 matches | PASS |
35
+
36
+ ### Regression Check
37
+ - Related code reviewed: YES
38
+ - User flow tested: PASS
39
+
40
+ **DEBUG COMPLETE - Issue Resolved**
41
+ ```
42
+
43
+ ---
44
+
45
+ ## Session State Update Template
46
+
47
+ After debugging, update `session-state/CURRENT.md`:
48
+
49
+ ```markdown
50
+ ## DEBUG SESSION
51
+
52
+ ### Bug
53
+ - **Symptom**: [description]
54
+ - **Root Cause**: [technical cause]
55
+ - **CLAUDE.md Violation**: [if any]
56
+
57
+ ### Investigation Path
58
+ 1. [First thing checked]
59
+ 2. [Second thing checked]
60
+ 3. [Where root cause was found]
61
+
62
+ ### Hypotheses Tested
63
+ | # | Hypothesis | Result |
64
+ |---|------------|--------|
65
+ | 1 | [theory] | REJECTED |
66
+ | 2 | [theory] | CONFIRMED |
67
+
68
+ ### Fix Applied
69
+ - File: [path:line]
70
+ - Change: [description]
71
+
72
+ ### Verification
73
+ - VR-NEGATIVE: [old pattern] -> 0 matches
74
+ - VR-BUILD: Exit 0
75
+ - VR-TYPE: 0 errors
76
+ - User flow: PASS
77
+
78
+ ### Prevention
79
+ [How to prevent this in future]
80
+ ```
81
+
82
+ ---
83
+
84
+ ## Plan Document Update (If Debug From Plan)
85
+
86
+ If debug session was part of a plan, update the plan document:
87
+
88
+ ```markdown
89
+ # IMPLEMENTATION STATUS
90
+
91
+ **Plan**: [Plan Name]
92
+ **Status**: DEBUG COMPLETE / PARTIAL
93
+ **Last Updated**: [YYYY-MM-DD HH:MM]
94
+
95
+ ## Bug Fixes Applied
96
+
97
+ | # | Bug Description | Status | Verification | Date |
98
+ |---|-----------------|--------|--------------|------|
99
+ | 1 | [Bug from plan] | FIXED | VR-BUILD: Pass | [date] |
100
+ | 2 | [Bug from plan] | FIXED | VR-TEST: Pass | [date] |
101
+
102
+ ## Root Causes Identified
103
+
104
+ | Bug | Root Cause | Prevention |
105
+ |-----|-----------|------------|
106
+ | [bug] | [cause] | [how to prevent] |
107
+ ```
@@ -1,31 +1,44 @@
1
1
  ---
2
2
  name: massu-debug
3
- description: Systematic debugging with hypothesis testing, root cause tracing, and verified fixes
3
+ description: "When user reports a bug, error, 500, crash, unexpected behavior, broken feature, or pastes error logs/stack traces"
4
4
  allowed-tools: Bash(*), Read(*), Write(*), Edit(*), Grep(*), Glob(*)
5
5
  ---
6
6
  name: massu-debug
7
7
 
8
- > **Shared rules apply.** Read `.claude/commands/_shared-preamble.md` before proceeding. CR-9, CR-35 enforced.
8
+ > **Shared rules apply.** Read `.claude/commands/_shared-preamble.md` before proceeding.
9
9
 
10
- # CS Debug: Systematic Debugging Protocol
10
+ > **Related Playbooks**: See `.claude/playbooks/debug-production-500.md`
11
11
 
12
- ## Objective
12
+ # Massu Debug: Systematic Debugging Protocol
13
13
 
14
- Trace errors to root cause systematically using hypothesis-driven investigation. Never guess — read the code, form hypotheses, test them, and verify fixes don't break anything else.
14
+ ## Objective
15
15
 
16
- **Usage**: `/massu-debug [error description, test name, or stack trace]`
16
+ Systematically debug issues using **evidence-based investigation**, not guessing. Follow the trace from symptom to root cause with VR-* verification at each step.
17
17
 
18
18
  ---
19
19
 
20
20
  ## NON-NEGOTIABLE RULES
21
21
 
22
- - **Never guess the root cause** read the code
23
- - **Never apply a fix without understanding WHY it works**
24
- - **Always verify the fix doesn't break other tests**
25
- - **Record each hypothesis and its outcome**
26
- - **FIX ALL ISSUES ENCOUNTERED (CR-9)** if you find additional bugs while debugging, fix those too
27
- - **Proof > reasoning. Commands > assumptions.**
28
- - **No blind changes** — Understand before modifying
22
+ - **Evidence over assumptions (CR-1)** - Every hypothesis must be tested with VR-* proof
23
+ - **Trace the full path** - From UI to API to DB and back. Check stored procedures
24
+ - **Verify fixes via browser (CR-41)** - Playwright before/after snapshots for UI issues
25
+ - **Check all environments** - Schema drift causes environment-specific failures. Verify the environment the user is reporting from
26
+ - **Auto-learn every fix (CR-34)** - Ingest bugfix to memory, add wrong->correct pattern, scan codebase-wide (CR-9)
27
+ - **No blind changes (CR-2)** - Run VR-SCHEMA-PRE before any query. See CLAUDE.md "Known Schema Mismatches"
28
+
29
+ ---
30
+
31
+ ## Skill Contents
32
+
33
+ This skill is a folder. The following files are available for reference:
34
+
35
+ | File | Purpose | Read When |
36
+ |------|---------|-----------|
37
+ | `references/investigation-phases.md` | Phases 0-7 investigation detail | Following debug phases |
38
+ | `references/common-shortcuts.md` | Quick diagnosis patterns | Common issue shortcuts |
39
+ | `references/codegraph-tracing.md` | Codegraph MCP tool usage | Tracing code dependencies |
40
+ | `references/auto-learning.md` | Post-debug learning pipeline | After fixing a bug |
41
+ | `references/report-format.md` | Debug report template | Writing debug reports |
29
42
 
30
43
  ---
31
44
 
@@ -58,427 +71,133 @@ DEBUG VERIFICATION LOOP:
58
71
 
59
72
  ## DOMAIN-SPECIFIC PATTERN LOADING
60
73
 
61
- Based on the bug's domain, load relevant pattern sections from CLAUDE.md:
62
-
63
- | Domain | Section | Load When |
64
- |--------|---------|-----------|
65
- | Tool modules | Tool Registration Pattern | Tool registration/handler bugs |
66
- | Config | Config Access Pattern | Config parsing/access bugs |
67
- | Hooks | Hook stdin/stdout Pattern | Hook compilation/runtime bugs |
68
- | Build | Build & Test Commands | Build/compilation errors |
69
- | Database | SQLite Database Pattern | DB access bugs |
70
-
71
- ---
72
-
73
- ## STEP 0: REPRODUCE THE FAILURE (MANDATORY)
74
-
75
- Before investigating root cause, CONFIRM you can trigger the exact error.
76
-
77
- 1. Identify the exact reproduction steps from user report
78
- 2. Execute those steps (or equivalent verification commands)
79
- 3. Capture the actual error output
80
- 4. If you CANNOT reproduce: document that and investigate why
81
-
82
- WHY: Debugging without reproduction is guessing. Fixes without reproduction cannot be verified.
83
-
84
- ### 0.2 Memory Check
85
-
86
- Before investigating, search for past failures related to this issue:
87
-
88
- - Check session state (`.claude/session-state/CURRENT.md`) for recent failures
89
- - Search codebase for similar error patterns
90
- - Check if this is a known issue with an established fix pattern
91
-
92
- If matches found: read the previous failures and avoid repeating failed approaches.
93
-
94
- ---
95
-
96
- ## STEP 1: SYMPTOM CAPTURE
97
-
98
- ### 1.0 Error Category Matrix
99
-
100
- | Error Type | Likely Cause | First Check |
101
- |------------|--------------|-------------|
102
- | TypeError | Null/undefined value | Null guards in source |
103
- | Import error | Missing/wrong module path | ESM import path |
104
- | Config error | Missing config key | massu.config.yaml |
105
- | Build fail | TypeScript/esbuild error | tsc output |
106
- | Test fail | Assertion mismatch | Test expectations |
107
- | Tool not found | Missing registration | tools.ts wiring |
108
- | Hook timeout | Heavy dependency or infinite loop | Hook source |
109
-
110
- Record the exact error from `$ARGUMENTS`:
111
-
112
- ```markdown
113
- ### Symptom
114
- - **Error**: [exact error message or test name]
115
- - **Stack trace**: [if provided]
116
- - **Unexpected behavior**: [what happened vs what was expected]
117
- - **Reproducible**: [how to reproduce — test command, user action, etc.]
118
- ```
119
-
120
- **If `$ARGUMENTS` is a test name:**
121
- ```bash
122
- # Run the specific test to capture the full error
123
- npx vitest run [test-file-or-pattern] 2>&1
124
- ```
125
-
126
- **If `$ARGUMENTS` is an error message:**
127
- ```bash
128
- # Search for the error message in the codebase
129
- grep -rn "[error message]" packages/core/src/ --include="*.ts" --include="*.tsx"
130
- ```
74
+ Based on the bug's domain, load relevant pattern files:
131
75
 
132
- **If `$ARGUMENTS` is vague or missing:**
133
- ```
134
- OUTPUT: "Please provide one of: (1) exact error message, (2) failing test name, (3) stack trace, (4) steps to reproduce"
135
- ABORT
136
- ```
76
+ | Domain | Pattern File | Load When |
77
+ |--------|--------------|-----------|
78
+ | Database errors | `.claude/patterns/database-patterns.md` | 500 errors, query failures |
79
+ | Auth issues | `.claude/patterns/auth-patterns.md` | 401/403 errors, session issues |
80
+ | UI bugs | `.claude/patterns/ui-patterns.md` | Rendering, state, interaction bugs |
81
+ | Realtime issues | `.claude/patterns/realtime-patterns.md` | Subscription failures |
82
+ | Build failures | `.claude/patterns/build-patterns.md` | Compilation, bundling errors |
137
83
 
138
84
  ---
139
85
 
140
- ## STEP 2: LOCATE ERROR SOURCE
86
+ ## MANDATORY DATABASE VERIFICATION (For Database-Related Bugs)
141
87
 
142
- ### From Stack Trace
88
+ ### VR-SCHEMA-PRE: Verify Schema BEFORE Assuming Bug Cause
143
89
 
144
- Parse the stack trace for the originating file and line number:
145
-
146
- ```bash
147
- # Read the file at the error location with 50 lines of surrounding context
148
- # (25 lines before, 25 lines after the error line)
90
+ ```sql
91
+ SELECT column_name, data_type, is_nullable
92
+ FROM information_schema.columns
93
+ WHERE table_name = '[SUSPECTED_TABLE]'
94
+ ORDER BY ordinal_position;
149
95
  ```
150
96
 
151
- ### From Error Message
152
-
153
- ```bash
154
- # Grep for the error message string in source code
155
- grep -rn "[error message text]" packages/core/src/ --include="*.ts"
156
- # Also search in other package directories if applicable
157
- grep -rn "[error message text]" packages/ --include="*.ts" --include="*.tsx"
158
- ```
97
+ **Common Bug Causes VR-SCHEMA-PRE Catches:**
98
+ - Column doesn't exist (but code uses it)
99
+ - Column has different type than expected
100
+ - Column is nullable when code assumes non-null
101
+ - Column name is different than expected (see Known Schema Mismatches in CLAUDE.md)
159
102
 
160
- ### From Test Failure
103
+ ### VR-DATA: Verify Config Data for "No Data" Bugs
161
104
 
162
- ```bash
163
- # Read the failing test to understand what it expects
164
- # Read the source module the test imports
105
+ ```sql
106
+ SELECT DISTINCT jsonb_object_keys(config_column) as config_keys
107
+ FROM [CONFIG_TABLE]
108
+ WHERE config_column IS NOT NULL;
165
109
  ```
166
110
 
167
- ```markdown
168
- ### Error Location
169
- - **File**: [file path]
170
- - **Line**: [line number]
171
- - **Function**: [function name]
172
- - **Context**: [what this code is supposed to do]
173
- ```
111
+ **VR-DATA is the FIRST check for any "no data returned" bug.** Config keys may not match what the code expects.
174
112
 
175
113
  ---
176
114
 
177
- ## STEP 3: TRACE CALL CHAIN
178
-
179
- Follow function calls upstream to understand the full execution path:
180
-
181
- ```bash
182
- # Find who calls this function
183
- grep -rn "[function_name](" packages/core/src/ --include="*.ts"
115
+ ## Gotchas
184
116
 
185
- # Find what arguments are passed
186
- # Read each caller to understand the data flow
187
- ```
188
-
189
- Build the call chain:
190
-
191
- ```markdown
192
- ### Call Chain
193
- ```
194
- caller_1() [file_1.ts:NN]
195
- → caller_2() [file_2.ts:NN]
196
- → error_site() [file_3.ts:NN] ← ERROR HERE
197
- ```
198
-
199
- ### Data Flow
200
- | Step | Variable | Value/Type | Source |
201
- |------|----------|------------|--------|
202
- | 1 | [var] | [value/type] | [where it comes from] |
203
- | 2 | [var] | [value/type] | [transformation] |
204
- | 3 | [var] | [unexpected value] | ← MISMATCH |
205
- ```
117
+ - **Don't guess schema (VR-SCHEMA-PRE)** -- ALWAYS query information_schema.columns before writing any database query. Column names you "remember" may be wrong
118
+ - **Check all environments** -- bugs may manifest differently across environments due to schema drift. Always verify the environment the user is reporting from
119
+ - **Dynamic imports for heavy deps** -- when debugging requires jsdom, cheerio, or other heavy packages, use `await import()` never static import
120
+ - **Stored procedures may reference deleted columns** -- after ANY table migration, audit stored procedures on all databases
121
+ - **Don't fix without understanding** -- read the code path end-to-end before proposing a fix. Surface-level patches create new bugs
206
122
 
207
123
  ---
208
124
 
209
- ## STEP 4: HYPOTHESIS FORMATION
125
+ ## INVESTIGATION PHASES
210
126
 
211
- Based on code reading (NOT guessing), form up to 3 ranked hypotheses:
127
+ Read `references/investigation-phases.md` for full detail on all 8 phases:
212
128
 
213
- ```markdown
214
- ### Hypotheses
215
-
216
- | # | Hypothesis | Confidence | Verification Method |
217
- |---|-----------|------------|---------------------|
218
- | H1 | [most likely cause based on code reading] | HIGH/MED/LOW | [specific command or check to verify] |
219
- | H2 | [alternative cause] | HIGH/MED/LOW | [specific command or check to verify] |
220
- | H3 | [least likely cause] | HIGH/MED/LOW | [specific command or check to verify] |
221
- ```
222
-
223
- **Hypothesis quality requirements:**
224
- - Each hypothesis must be based on SPECIFIC code you read (cite file:line)
225
- - Each verification method must be a CONCRETE action (bash command, grep, read specific file)
226
- - "Something might be wrong" is NOT a valid hypothesis
129
+ 0. **Reproduce the failure** -- confirm you can trigger the exact error; check memory for related failures
130
+ 1. **Symptom capture** -- document the issue, collect initial evidence
131
+ 2. **Categorize & load patterns** -- match error type to pattern file
132
+ 3. **Trace the path** -- UI layer, API layer, database layer investigation
133
+ 4. **Hypothesis testing** -- form and test each hypothesis with evidence
134
+ 5. **Root cause identification** -- document and verify the root cause
135
+ 6. **Fix & verify** -- for CRITICAL bugs, apply test-first protocol (see below); otherwise apply minimal fix, run VR-* protocols, check all environments
136
+ 7. **Regression check** -- verify related functionality, test full user flow
227
137
 
228
138
  ---
229
139
 
230
- ## STEP 5: HYPOTHESIS TESTING
231
-
232
- Test hypotheses in order of confidence (highest first):
140
+ ## CODEGRAPH-ENHANCED TRACING
233
141
 
234
- ```
235
- FOR EACH hypothesis (highest confidence first):
236
- 1. Execute the verification method
237
- 2. Record the result
238
- 3. IF confirmed → proceed to STEP 6
239
- 4. IF rejected → record why and test next hypothesis
240
-
241
- IF all hypotheses rejected:
242
- - Expand search scope
243
- - Read more files in the call chain
244
- - Check for environmental factors (config, DB state, imports)
245
- - Form new hypotheses and repeat from STEP 4
246
- ```
247
-
248
- ```markdown
249
- ### Hypothesis Testing Results
250
-
251
- | # | Hypothesis | Verification | Result | Outcome |
252
- |---|-----------|-------------|--------|---------|
253
- | H1 | [hypothesis] | [what you did] | [what you found] | CONFIRMED / REJECTED |
254
- | H2 | [hypothesis] | [what you did] | [what you found] | CONFIRMED / REJECTED |
255
- | H3 | [hypothesis] | [what you did] | [what you found] | CONFIRMED / REJECTED |
256
- ```
142
+ Read `references/codegraph-tracing.md` for how to use codegraph MCP tools to trace call paths and understand full context before debugging.
257
143
 
258
144
  ---
259
145
 
260
- ## STEP 6: ROOT CAUSE DOCUMENTATION
261
-
262
- Document the confirmed root cause before applying any fix:
263
-
264
- ```markdown
265
- ### Root Cause
266
-
267
- - **What**: [precise description of the bug]
268
- - **Why**: [why this bug exists — missing check, wrong assumption, stale code, etc.]
269
- - **Where**: [file(s) and line(s) affected]
270
- - **When introduced**: [if determinable — recent commit, original code, etc.]
271
- - **Blast radius**: [what else could be affected by this bug and by the fix]
272
- ```
273
-
274
- ---
275
-
276
- ## STEP 7: APPLY FIX
277
-
278
- ### Scope Check
279
-
280
- ```
281
- IF fix touches > 5 files:
282
- OUTPUT: "Fix scope is large ([N] files). Consider using /massu-create-plan for a structured approach."
283
- ASK user whether to proceed or create a plan
284
- ```
285
-
286
- ### Apply the Fix
287
-
288
- 1. **Apply the minimal correct fix** following CLAUDE.md patterns
289
- 2. **Document what was changed and why**
290
- 3. **Do NOT make unrelated improvements** — fix the bug only
291
-
292
- ```markdown
293
- ### Fix Applied
294
-
295
- | File | Change | Reason |
296
- |------|--------|--------|
297
- | [file:line] | [what was changed] | [why this fixes the root cause] |
298
- ```
299
-
300
- ---
301
-
302
- ## STEP 8: VERIFY FIX
303
-
304
- ### 8a. Targeted Test (if exists)
305
-
306
- ```bash
307
- # Run the originally-failing test
308
- npx vitest run [test file] 2>&1
309
- ```
310
-
311
- **Must pass.** If it still fails, go back to STEP 4 with new information.
312
-
313
- ### 8b. Full Test Suite (VR-TEST)
314
-
315
- ```bash
316
- npm test 2>&1
317
- # MUST exit 0, ALL tests pass
318
- ```
319
-
320
- ### 8c. Type Check (VR-TYPE)
321
-
322
- ```bash
323
- cd packages/core && npx tsc --noEmit
324
- # MUST show 0 errors
325
- ```
326
-
327
- ### 8d. Pattern Scanner (VR-PATTERN)
328
-
329
- ```bash
330
- bash scripts/massu-pattern-scanner.sh
331
- # MUST exit 0
332
- ```
333
-
334
- ### 8e. Hook Build (VR-HOOK-BUILD, if hooks modified)
335
-
336
- ```bash
337
- cd packages/core && npm run build:hooks
338
- # MUST exit 0
339
- ```
340
-
341
- **If ANY verification fails:**
342
- 1. Investigate the new failure
343
- 2. Determine if it was caused by the fix or is pre-existing
344
- 3. Fix it (CR-9: fix ALL issues encountered)
345
- 4. Re-run ALL verification from 8a
346
-
347
- ---
348
-
349
- ## STEP 9: RECORD FOR LEARNING
350
-
351
- Update session state with the debugging outcome:
352
-
353
- ```bash
354
- # Update .claude/session-state/CURRENT.md with:
355
- # - Bug description
356
- # - Root cause
357
- # - Fix applied
358
- # - Lesson learned
359
- ```
360
-
361
- ```markdown
362
- ### Learning Record
363
- - **Bug**: [one-line description]
364
- - **Root Cause**: [one-line explanation]
365
- - **Fix**: [one-line description of fix]
366
- - **Lesson**: [what to watch for in the future to prevent similar bugs]
367
- - **Pattern**: [if this reveals a recurring pattern, note it for potential pattern scanner rule]
368
- ```
369
-
370
- ---
371
-
372
- ## ABORT CONDITIONS
146
+ ## AUTO-LEARNING PROTOCOL (MANDATORY after every fix)
373
147
 
374
- | Condition | Action |
375
- |-----------|--------|
376
- | Cannot reproduce the error | Report reproduction failure, ask for more details |
377
- | Root cause is in external dependency | Report finding, suggest dependency update or workaround |
378
- | Fix requires architectural changes | Abort, suggest `/massu-create-plan` |
379
- | All hypotheses rejected after 2 rounds | Report findings, escalate to user with all evidence gathered |
148
+ Read `references/auto-learning.md` for the 4-step learning pipeline. **This is NOT optional.**
380
149
 
381
150
  ---
382
151
 
383
- ## MANDATORY PLAN DOCUMENT UPDATE (If Debug From Plan)
384
-
385
- **If debug session was part of a plan, update the plan document.**
386
-
387
- ```markdown
388
- # IMPLEMENTATION STATUS
389
-
390
- **Plan**: [Plan Name]
391
- **Status**: DEBUG COMPLETE / PARTIAL
392
- **Last Updated**: [YYYY-MM-DD HH:MM]
152
+ ## TEST-FIRST PROTOCOL (CRITICAL bugs)
393
153
 
394
- ## Bug Fixes Applied
154
+ For CRITICAL-severity bug fixes, apply the test-first protocol from `_shared-references/test-first-protocol.md`:
395
155
 
396
- | # | Bug Description | Status | Verification | Date |
397
- |---|-----------------|--------|--------------|------|
398
- | 1 | [Bug from plan] | FIXED | VR-BUILD: Pass | [date] |
156
+ 1. **Write a failing test** that demonstrates the bug BEFORE touching source code
157
+ 2. **Verify the test fails** for the expected reason
158
+ 3. **Apply the fix** minimal and targeted
159
+ 4. **Verify the test passes** + full suite passes
399
160
 
400
- ## Root Causes Identified
401
-
402
- | Bug | Root Cause | Prevention |
403
- |-----|-----------|------------|
404
- | [bug] | [cause] | [how to prevent] |
405
- ```
161
+ This is MANDATORY for CRITICAL bugs, RECOMMENDED for HIGH, and does NOT apply to LOW/MEDIUM pattern fixes. If the bug cannot be tested (race condition, visual-only), document why and use VR-BROWSER or VR-VISUAL as the evidence equivalent. Report `TEST_FIRST_GATE: PASS` or `TEST_FIRST_GATE: SKIPPED — [reason]`.
406
162
 
407
163
  ---
408
164
 
409
- ## AUTO-LEARNING PROTOCOL (MANDATORY after every fix)
410
-
411
- After EVERY bug fix:
165
+ ## QUALITY SCORING (silent, automatic)
412
166
 
413
- ### Step 1: Record the Pattern
414
- Update `.claude/session-state/CURRENT.md` with:
415
- - What was wrong (the incorrect pattern)
416
- - What fixed it (the correct pattern)
417
- - File(s) affected
167
+ After completing the debug session, self-score and append one JSONL line to `.claude/metrics/command-scores.jsonl`:
418
168
 
419
- ### Step 2: Add to Pattern Scanner (if grep-able)
420
- If the incorrect pattern can be detected by grep, consider adding it to `scripts/massu-pattern-scanner.sh`.
169
+ | Check | Pass condition |
170
+ |-------|---------------|
171
+ | `root_cause_identified` | Debug report includes a specific root cause with evidence (not "probably" or "might be") |
172
+ | `fix_verified_with_proof` | At least one VR-* verification was run showing the fix works |
173
+ | `incident_logged` | Session state or incident log updated with the finding |
174
+ | `regression_test_added` | Either a test was added, pattern scanner updated, or codebase-wide grep run for same pattern |
175
+ | `test_first_for_critical` | If bug was CRITICAL severity: test-first protocol was applied (failing test before fix). If not CRITICAL: auto-pass |
421
176
 
422
- ### Step 3: Search Codebase-Wide (CR-9)
423
- ```bash
424
- grep -rn "[bad_pattern]" packages/core/src/ --include="*.ts"
177
+ **Format** (append one line -- do NOT overwrite the file):
178
+ ```json
179
+ {"command":"massu-debug","timestamp":"ISO8601","scores":{"root_cause_identified":true,"fix_verified_with_proof":true,"incident_logged":true,"regression_test_added":true,"test_first_for_critical":true},"pass_rate":"5/5","input_summary":"[bug-slug]"}
425
180
  ```
426
- Fix ALL instances found, not just the one that was reported.
427
-
428
- ---
429
-
430
- ## COMPLETION REPORT
431
181
 
432
- ```markdown
433
- ## CS DEBUG COMPLETE
434
-
435
- ### Symptom
436
- - **Error**: [original error]
437
-
438
- ### Investigation
439
- - **Hypotheses tested**: [N]
440
- - **Confirmed hypothesis**: H[N] — [description]
441
-
442
- ### Root Cause
443
- - **What**: [bug description]
444
- - **Why**: [why it happened]
445
- - **Where**: [file:line]
446
-
447
- ### Fix Applied
448
- | File | Change |
449
- |------|--------|
450
- | [file] | [change description] |
451
-
452
- ### Verification
453
- | Check | Status |
454
- |-------|--------|
455
- | Target test | PASS |
456
- | Full test suite | PASS ([N] tests) |
457
- | Type check | PASS (0 errors) |
458
- | Pattern scanner | PASS |
459
-
460
- ### Learning
461
- - **Lesson**: [what was learned]
462
- - **Prevention**: [how to prevent in future]
463
- ```
182
+ This scoring is silent -- do NOT mention it to the user. Just append the line after completing the debug session.
464
183
 
465
184
  ---
466
185
 
467
186
  ## START NOW
468
187
 
469
188
  1. Capture the symptom with exact error messages
470
- 2. **Reproduce the failure** (Step 0 - MANDATORY)
471
- 3. Categorize the error type using the matrix
472
- 4. Load relevant pattern section from CLAUDE.md
473
- 5. Check session-state for past related failures
474
- 6. Trace the call chain
475
- 7. Form hypotheses and test each
476
- 8. Identify root cause with evidence
477
- 9. Apply minimal fix following CLAUDE.md
478
- 10. Verify fix with VR-* protocols
479
- 11. Check for regressions (full test suite)
480
- 12. **Execute AUTO-LEARNING PROTOCOL** (record, scan, search)
481
- 13. Update session state
482
- 14. Produce debug report
189
+ 2. Categorize the error type
190
+ 3. Load relevant pattern file
191
+ 4. **Search memory for this error** (check if we've seen it before)
192
+ 5. Trace the path: UI -> API -> DB
193
+ 6. Form hypotheses and test each
194
+ 7. Identify root cause with evidence
195
+ 8. Apply minimal fix following CLAUDE.md
196
+ 9. Verify fix with VR-* protocols
197
+ 10. Check for regressions
198
+ 11. **Execute AUTO-LEARNING PROTOCOL** (ingest, record, scan, search)
199
+ 12. Update session state
200
+ 13. Produce debug report (see `references/report-format.md`)
201
+ 14. **Score and append to command-scores.jsonl** (silent)
483
202
 
484
203
  **Remember: Evidence over assumptions. Prove, don't guess. Learn from every fix.**
@@ -205,7 +205,7 @@ grep -c "tool\|hook\|config\|install\|usage" packages/core/README.md 2>/dev/null
205
205
  ```bash
206
206
  # Check if CLAUDE.md file locations match actual
207
207
  grep "packages/core/src/" .claude/CLAUDE.md | while read line; do
208
- path=$(echo "$line" | grep -oP 'packages/core/src/[a-zA-Z0-9_./-]+')
208
+ path=$(echo "$line" | sed -n 's/.*\(packages\/core\/src\/[a-zA-Z0-9_.\/-]*\).*/\1/p')
209
209
  if [ -n "$path" ]; then
210
210
  [ -f "$path" ] && echo "OK: $path" || echo "MISSING: $path"
211
211
  fi