@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.
- package/README.md +40 -0
- package/agents/massu-architecture-reviewer.md +104 -0
- package/agents/massu-blast-radius-analyzer.md +84 -0
- package/agents/massu-competitive-scorer.md +126 -0
- package/agents/massu-help-sync.md +73 -0
- package/agents/massu-migration-writer.md +94 -0
- package/agents/massu-output-scorer.md +87 -0
- package/agents/massu-pattern-reviewer.md +84 -0
- package/agents/massu-plan-auditor.md +170 -0
- package/agents/massu-schema-sync-verifier.md +70 -0
- package/agents/massu-security-reviewer.md +98 -0
- package/agents/massu-ux-reviewer.md +106 -0
- package/commands/_shared-preamble.md +53 -23
- package/commands/_shared-references/auto-learning-protocol.md +71 -0
- package/commands/_shared-references/blast-radius-protocol.md +76 -0
- package/commands/_shared-references/security-pre-screen.md +64 -0
- package/commands/_shared-references/test-first-protocol.md +87 -0
- package/commands/_shared-references/verification-table.md +52 -0
- package/commands/massu-article-review.md +343 -0
- package/commands/massu-autoresearch/references/eval-runner.md +84 -0
- package/commands/massu-autoresearch/references/safety-rails.md +125 -0
- package/commands/massu-autoresearch/references/scoring-protocol.md +151 -0
- package/commands/massu-autoresearch.md +258 -0
- package/commands/massu-batch.md +44 -12
- package/commands/massu-bearings.md +42 -8
- package/commands/massu-checkpoint.md +588 -0
- package/commands/massu-ci-fix.md +2 -2
- package/commands/massu-command-health.md +132 -0
- package/commands/massu-command-improve.md +232 -0
- package/commands/massu-commit.md +205 -44
- package/commands/massu-create-plan.md +239 -57
- package/commands/massu-data/references/common-queries.md +79 -0
- package/commands/massu-data/references/table-guide.md +50 -0
- package/commands/massu-data.md +66 -0
- package/commands/massu-dead-code.md +29 -34
- package/commands/massu-debug/references/auto-learning.md +61 -0
- package/commands/massu-debug/references/codegraph-tracing.md +80 -0
- package/commands/massu-debug/references/common-shortcuts.md +98 -0
- package/commands/massu-debug/references/investigation-phases.md +294 -0
- package/commands/massu-debug/references/report-format.md +107 -0
- package/commands/massu-debug.md +105 -386
- package/commands/massu-docs.md +1 -1
- package/commands/massu-full-audit.md +61 -0
- package/commands/massu-gap-enhancement-analyzer.md +276 -16
- package/commands/massu-golden-path/references/approval-points.md +216 -0
- package/commands/massu-golden-path/references/competitive-mode.md +273 -0
- package/commands/massu-golden-path/references/error-handling.md +121 -0
- package/commands/massu-golden-path/references/phase-0-requirements.md +53 -0
- package/commands/massu-golden-path/references/phase-1-plan-creation.md +168 -0
- package/commands/massu-golden-path/references/phase-2-implementation.md +397 -0
- package/commands/massu-golden-path/references/phase-2.5-gap-analyzer.md +156 -0
- package/commands/massu-golden-path/references/phase-3-simplify.md +40 -0
- package/commands/massu-golden-path/references/phase-4-commit.md +94 -0
- package/commands/massu-golden-path/references/phase-5-push.md +116 -0
- package/commands/massu-golden-path/references/phase-5.5-production-verify.md +170 -0
- package/commands/massu-golden-path/references/phase-6-completion.md +113 -0
- package/commands/massu-golden-path/references/qa-evaluator-spec.md +137 -0
- package/commands/massu-golden-path/references/sprint-contract-protocol.md +117 -0
- package/commands/massu-golden-path/references/vr-visual-calibration.md +73 -0
- package/commands/massu-golden-path.md +114 -848
- package/commands/massu-guide.md +72 -69
- package/commands/massu-hooks.md +27 -12
- package/commands/massu-hotfix.md +221 -144
- package/commands/massu-incident.md +49 -20
- package/commands/massu-infra-audit.md +187 -0
- package/commands/massu-learning-audit.md +211 -0
- package/commands/massu-loop/references/auto-learning.md +49 -0
- package/commands/massu-loop/references/checkpoint-audit.md +40 -0
- package/commands/massu-loop/references/guardrails.md +17 -0
- package/commands/massu-loop/references/iteration-structure.md +115 -0
- package/commands/massu-loop/references/loop-controller.md +188 -0
- package/commands/massu-loop/references/plan-extraction.md +78 -0
- package/commands/massu-loop/references/vr-plan-spec.md +140 -0
- package/commands/massu-loop-playwright.md +9 -9
- package/commands/massu-loop.md +115 -670
- package/commands/massu-new-pattern.md +423 -0
- package/commands/massu-perf.md +422 -0
- package/commands/massu-plan-audit.md +1 -1
- package/commands/massu-plan.md +389 -122
- package/commands/massu-production-verify.md +433 -0
- package/commands/massu-push.md +62 -378
- package/commands/massu-recap.md +29 -3
- package/commands/massu-rollback.md +613 -0
- package/commands/massu-scaffold-hook.md +2 -4
- package/commands/massu-scaffold-page.md +2 -3
- package/commands/massu-scaffold-router.md +1 -2
- package/commands/massu-security.md +619 -0
- package/commands/massu-simplify.md +115 -85
- package/commands/massu-squirrels.md +2 -2
- package/commands/massu-tdd.md +38 -22
- package/commands/massu-test.md +3 -3
- package/commands/massu-type-mismatch-audit.md +469 -0
- package/commands/massu-ui-audit.md +587 -0
- package/commands/massu-verify-playwright.md +287 -32
- package/commands/massu-verify.md +150 -46
- package/dist/cli.js +146 -95
- package/package.json +6 -2
- package/patterns/build-patterns.md +302 -0
- package/patterns/component-patterns.md +246 -0
- package/patterns/display-patterns.md +185 -0
- package/patterns/form-patterns.md +890 -0
- package/patterns/integration-testing-checklist.md +445 -0
- package/patterns/security-patterns.md +219 -0
- package/patterns/testing-patterns.md +569 -0
- package/patterns/tool-routing.md +81 -0
- package/patterns/ui-patterns.md +371 -0
- package/protocols/plan-implementation.md +267 -0
- package/protocols/recovery.md +225 -0
- package/protocols/verification.md +404 -0
- package/reference/command-taxonomy.md +178 -0
- package/reference/cr-rules-reference.md +76 -0
- package/reference/hook-execution-order.md +148 -0
- package/reference/lessons-learned.md +175 -0
- package/reference/patterns-quickref.md +208 -0
- package/reference/standards.md +135 -0
- package/reference/subagents-reference.md +17 -0
- package/reference/vr-verification-reference.md +867 -0
- 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
|
+
```
|
package/commands/massu-debug.md
CHANGED
|
@@ -1,31 +1,44 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: massu-debug
|
|
3
|
-
description:
|
|
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.
|
|
8
|
+
> **Shared rules apply.** Read `.claude/commands/_shared-preamble.md` before proceeding.
|
|
9
9
|
|
|
10
|
-
|
|
10
|
+
> **Related Playbooks**: See `.claude/playbooks/debug-production-500.md`
|
|
11
11
|
|
|
12
|
-
|
|
12
|
+
# Massu Debug: Systematic Debugging Protocol
|
|
13
13
|
|
|
14
|
-
|
|
14
|
+
## Objective
|
|
15
15
|
|
|
16
|
-
|
|
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
|
-
- **
|
|
23
|
-
- **
|
|
24
|
-
- **
|
|
25
|
-
- **
|
|
26
|
-
- **
|
|
27
|
-
- **
|
|
28
|
-
|
|
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
|
|
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
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
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
|
-
##
|
|
86
|
+
## MANDATORY DATABASE VERIFICATION (For Database-Related Bugs)
|
|
141
87
|
|
|
142
|
-
###
|
|
88
|
+
### VR-SCHEMA-PRE: Verify Schema BEFORE Assuming Bug Cause
|
|
143
89
|
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
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
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
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
|
-
###
|
|
103
|
+
### VR-DATA: Verify Config Data for "No Data" Bugs
|
|
161
104
|
|
|
162
|
-
```
|
|
163
|
-
|
|
164
|
-
|
|
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
|
-
|
|
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
|
-
##
|
|
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
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
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
|
-
##
|
|
125
|
+
## INVESTIGATION PHASES
|
|
210
126
|
|
|
211
|
-
|
|
127
|
+
Read `references/investigation-phases.md` for full detail on all 8 phases:
|
|
212
128
|
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
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
|
-
##
|
|
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
|
-
##
|
|
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
|
-
|
|
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
|
-
##
|
|
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
|
-
|
|
154
|
+
For CRITICAL-severity bug fixes, apply the test-first protocol from `_shared-references/test-first-protocol.md`:
|
|
395
155
|
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
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
|
-
|
|
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
|
-
##
|
|
410
|
-
|
|
411
|
-
After EVERY bug fix:
|
|
165
|
+
## QUALITY SCORING (silent, automatic)
|
|
412
166
|
|
|
413
|
-
|
|
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
|
-
|
|
420
|
-
|
|
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
|
-
|
|
423
|
-
```
|
|
424
|
-
|
|
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
|
-
|
|
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.
|
|
471
|
-
3.
|
|
472
|
-
4.
|
|
473
|
-
5.
|
|
474
|
-
6.
|
|
475
|
-
7.
|
|
476
|
-
8.
|
|
477
|
-
9.
|
|
478
|
-
10.
|
|
479
|
-
11.
|
|
480
|
-
12.
|
|
481
|
-
13.
|
|
482
|
-
14.
|
|
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.**
|
package/commands/massu-docs.md
CHANGED
|
@@ -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" |
|
|
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
|