Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
From cmnpx claudepluginhub tody-agent/codymaster --plugin cmThis skill uses the workspace's default tool permissions.
Provides UI/UX resources: 50+ styles, color palettes, font pairings, guidelines, charts for web/mobile across React, Next.js, Vue, Svelte, Tailwind, React Native, Flutter. Aids planning, building, reviewing interfaces.
Fetches up-to-date documentation from Context7 for libraries and frameworks like React, Next.js, Prisma. Use for setup questions, API references, and code examples.
Implements distributed tracing with Jaeger/Tempo for microservices, including Kubernetes/Docker setup and OpenTelemetry instrumentation (Python/Flask). Use for debugging latency, dependencies, and request flows.
Random fixes waste time and create new bugs. Quick patches mask underlying issues.
Core principle: ALWAYS find root cause before attempting fixes. Symptom fixes are failure.
Violating the letter of this process is violating the spirit of debugging.
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
If you haven't completed Phase 1, you cannot propose fixes.
Use for ANY technical issue:
Use this ESPECIALLY when:
Don't skip when:
You MUST complete each phase before proceeding to the next.
BEFORE blaming code, ASK: "Could memory be causing this bug?"
SUSPECT — Identify relevant memories:
.cm/learnings.json filtered by that scopeINVESTIGATE — Did AI follow a memory when writing buggy code?
prevention pattern from any learning?decision that may be outdated?VERIFY — Is the suspect memory still correct?
HEAL (only if memory confirmed as cause):
status = "invalidated" — learning is proven wrongprevention with correct info, set status = "corrected".cm/meta-learnings.jsonIF memory caused the bug:
→ HEAL memory FIRST
→ THEN proceed to Phase 1 to fix code
→ The code fix will be correct because memory is now correct
IF memory did NOT cause the bug:
→ Proceed to Phase 1 normally
WHY PHASE 0.5? Fix memory first → code fix will be correct. Without fixing memory → bug will return next session (bug loop).
BEFORE attempting ANY fix:
Read Error Messages Carefully
Reproduce Consistently
Check Recent Changes
Gather Evidence in Multi-Component Systems
WHEN system has multiple components (CI → build → signing, API → service → database):
BEFORE proposing fixes, add diagnostic instrumentation:
For EACH component boundary:
- Log what data enters component
- Log what data exits component
- Verify environment/config propagation
- Check state at each layer
Run once to gather evidence showing WHERE it breaks
THEN analyze evidence to identify failing component
THEN investigate that specific component
Trace Data Flow
WHEN error is deep in call stack:
Find the pattern before fixing:
Find Working Examples
Compare Against References
Identify Differences
Understand Dependencies
Scientific method:
Form Single Hypothesis
Test Minimally
Verify Before Continuing
When You Don't Know
Fix the root cause, not the symptom:
Create Failing Test Case
cm-tdd skill for writing proper failing testsImplement Single Fix
Verify Fix
If Fix Doesn't Work
If 3+ Fixes Failed: Question Architecture
Pattern indicating architectural problem:
Discuss with your human partner before attempting more fixes
This is NOT a failed hypothesis - this is a wrong architecture.
After fixing any bug, ALWAYS write to .cm/CONTINUITY.md → "Mistakes & Learnings":
- What Failed: [exact error message or behavior]
- Why It Failed: [root cause from Phase 1]
- How to Prevent: [concrete pattern to avoid]
- Scope: [global | module:{name} | file:{path}]
Scope rules: Choose the SMALLEST scope that applies.
file:src/api/routes.tsmodule:authglobalAnti-duplicate: If a similar learning already exists in .cm/learnings.json,
reinforce it (reinforceCount++) instead of creating a new entry.
Token savings: Next time same error pattern appears, AI reads the learning (~50 tokens) instead of repeating full 4-phase debug cycle (~3,000 tokens). This is the #1 token saver in the entire kit.
If you catch yourself thinking:
ALL of these mean: STOP. Return to Phase 1.
When you see these user signals: STOP. Return to Phase 1.
| Excuse | Reality |
|---|---|
| "Issue is simple, don't need process" | Simple issues have root causes too. Process is fast for simple bugs. |
| "Emergency, no time for process" | Systematic debugging is FASTER than guess-and-check thrashing. |
| "Just try this first, then investigate" | First fix sets the pattern. Do it right from the start. |
| "I'll write test after confirming fix works" | Untested fixes don't stick. Test first proves it. |
| "Multiple fixes at once saves time" | Can't isolate what worked. Causes new bugs. |
| Phase | Key Activities | Success Criteria |
|---|---|---|
| 1. Root Cause | Read errors, reproduce, check changes, gather evidence | Understand WHAT and WHY |
| 2. Pattern | Find working examples, compare | Identify differences |
| 3. Hypothesis | Form theory, test minimally | Confirmed or new hypothesis |
| 4. Implementation | Create test, fix, verify | Bug resolved, tests pass |
If systematic investigation reveals issue is truly environmental, timing-dependent, or external:
But: 95% of "no root cause" cases are incomplete investigation.
Related skills: