Debugging Memory Workflow Skill

Debugging Memory Workflow

This skill integrates the claude-code-debugger memory system into debugging workflows. The core principle: never solve the same bug twice.

Memory-First Approach

Before investigating any bug, always check the debugging memory:

npx @tyroneross/claude-code-debugger debug "<symptom description>"

Decision tree based on results:

High confidence match (>70%): Apply the documented fix directly, adapting for current context
Medium confidence match (40-70%): Review the past incident, use it as a starting point
Low/no match (<40%): Proceed with standard debugging, document the solution afterward

Visibility

When this skill activates, always announce it to the user:

Before searching: Output "Checking debugging memory for similar issues..."
After search: Report result briefly:
- Found match: "Found X matching incident(s) from past debugging sessions"
- No match: "No matching incidents in debugging memory - starting fresh investigation"

This ensures users know the debugger is active and working.

Structured Debugging Process

When no past solution applies, follow this systematic approach:

1. Reproduce

Establish a reliable reproduction path:

Identify exact steps to trigger the bug
Note any environmental factors (OS, dependencies, state)
Create a minimal reproduction if possible

2. Isolate

Narrow down the problem space:

Binary search through recent changes
Disable components to find the culprit
Check logs and error messages for clues

3. Diagnose

Find the root cause:

Trace the execution path
Examine state at failure point
Identify the specific code causing the issue

4. Fix

Implement the solution:

Make minimal, targeted changes
Avoid side effects
Consider edge cases

5. Verify

Confirm the fix works:

Test the original reproduction steps
Run related tests
Check for regressions

Incident Documentation

After fixing a bug, document it for future retrieval.

Manual Incident Storage (Preferred Method)

Claude Code should directly write incident files to .claude/memory/incidents/ using the Write tool. No CLI command needed.

Step 1: Generate incident ID

INC_YYYYMMDD_HHMMSS_xxxx

Where xxxx is 4 random alphanumeric characters. Example: INC_20241231_143052_a7b2

Step 2: Write JSON file

.claude/memory/incidents/INC_20241231_143052_a7b2.json

Minimal incident structure:

{
  "incident_id": "INC_20241231_143052_a7b2",
  "timestamp": 1735654252000,
  "symptom": "User-facing description of the bug",
  "root_cause": {
    "description": "Technical explanation of why the bug occurred",
    "file": "path/to/problematic/file.ts",
    "category": "logic|config|dependency|performance|react-hooks",
    "confidence": 0.85
  },
  "fix": {
    "approach": "What was done to fix it",
    "changes": [
      {
        "file": "path/to/file.ts",
        "lines_changed": 10,
        "change_type": "modify|add|delete",
        "summary": "Brief description of change"
      }
    ]
  },
  "verification": {
    "status": "verified|unverified",
    "regression_tests_passed": true,
    "success_criteria_met": true
  },
  "tags": ["relevant", "keywords", "for", "search"],
  "files_changed": ["list/of/all/files.ts"],
  "quality_score": 0.75
}

Step 3: Ensure directory exists Before writing, create the directory if needed:

mkdir -p .claude/memory/incidents

Automatic Capture (Session End)

The Stop hook automatically mines the session audit trail when a session ends:

npx @tyroneross/claude-code-debugger mine --days 1 --store

Audit Trail Limitations:

Audit trail is written by Claude Code at session end, not during the session
Location: .claude/audit/ (markdown files from completed sessions)
Mining only works on previously completed sessions
For mid-session capture: Always use manual storage above

When mining returns 0 incidents:

No previous sessions have completed in this project
Previous sessions didn't involve debugging work
The audit directory doesn't exist yet (first session)

Recommended workflow:

Don't rely on mining - always manually store important incidents
Mining is a fallback for sessions where manual storage was forgotten
Use /debugger-scan to check what can be mined from past sessions

Quality Indicators

The memory system scores incidents on:

Root cause analysis depth (30%)
Fix documentation completeness (30%)
Verification status (20%)
Tags and metadata (20%)

Target 75%+ quality score for effective future retrieval.

Tagging Strategy

Apply descriptive tags for better searchability:

Technology: react, typescript, api, database
Category: logic, config, dependency, performance
Symptom type: crash, render, timeout, validation

Using Past Solutions

When the memory system finds a match:

Review the past incident - Understand the original context
Assess applicability - Consider differences in current situation
Adapt the fix - Modify as needed for current codebase
Verify thoroughly - The same symptom may have different causes

Pattern Recognition

The memory system automatically extracts patterns when 3+ similar incidents exist. Patterns represent reusable solutions with higher reliability than individual incidents.

When a pattern matches:

Trust the solution template (90%+ confidence)
Apply the recommended approach
Note any caveats mentioned

CLI Quick Reference

| Command | Purpose | |---------|---------| | /debugger "symptom" | Search memory for similar bugs | | /debugger-status | Show memory statistics | | /debugger-scan | Mine recent sessions for incidents | | /assess "symptom" | Run parallel domain assessment |

Parallel Domain Assessment

For complex issues that may span multiple areas (database, frontend, API, performance), use parallel assessment to diagnose all domains simultaneously.

When to Use Parallel Assessment

Symptom is vague or unclear ("app broken", "something wrong")
Multiple domains may be involved ("search is slow and returns wrong results")
Post-deploy regression with unknown scope
Complex issues affecting multiple layers

Domain Assessors

Four specialized assessor agents are available:

| Assessor | Expertise | |----------|-----------| | database-assessor | Prisma, PostgreSQL, queries, migrations, connection issues | | frontend-assessor | React, hooks, rendering, state, hydration, SSR | | api-assessor | Endpoints, REST/GraphQL, auth, middleware, CORS | | performance-assessor | Latency, memory, CPU, bottlenecks, optimization |

Parallel Execution

Launch assessors in parallel using the Task tool:

For: "search is slow and returns wrong results"

Launch simultaneously:
- database-assessor (query performance)
- api-assessor (endpoint correctness)
- performance-assessor (latency analysis)

Each assessor returns a JSON assessment with:

confidence: 0-1 score
probable_causes: List of likely issues
recommended_actions: Steps to fix
related_incidents: Past memory matches

Domain Detection Keywords

| Domain | Trigger Keywords | |--------|-----------------| | Database | query, schema, migration, prisma, sql, connection, constraint, index | | Frontend | react, hook, useEffect, render, component, state, hydration, browser | | API | endpoint, route, request, response, auth, 500, 404, cors, middleware | | Performance | slow, latency, timeout, memory, leak, cpu, bottleneck, optimization |

Result Aggregation

After parallel assessments complete:

Rank by confidence score (highest first)
Consider evidence count (more related incidents = higher priority)
Generate priority ranking of recommended actions
Present unified diagnosis with action sequence

Trace Integration

The debugger can ingest traces from multiple sources to aid diagnosis:

Supported Trace Sources

OpenTelemetry (OTLP): Distributed tracing spans
Sentry: Error events and breadcrumbs
Langchain/LangSmith: LLM operation traces
Browser: Chrome DevTools, Playwright, console logs

Using Traces for Debugging

When traces are available:

Correlate error traces with symptoms
Review performance spans for latency issues
Check LLM traces for AI-related bugs
Examine browser console for frontend errors

Traces are summarized to minimize token usage while preserving key diagnostic information.

Token-Efficient Retrieval

The memory system uses tiered retrieval to minimize context size:

Retrieval Tiers

| Tier | Token Usage | Content | |------|-------------|---------| | Summary | ~100 tokens | ID, symptom preview, category | | Compact | ~200 tokens | Short keys, essential fields | | Full | ~550 tokens | Complete incident details |

Automatic Token Budgeting

Default budget: 2500 tokens

Patterns: 30% (750 tokens)
Incidents: 60% (1500 tokens)
Metadata: 10% (250 tokens)

The system automatically selects the appropriate tier based on available budget.

Additional Resources

For detailed guidance, consult:

references/incident-documentation.md - Complete guide to documenting incidents
references/pattern-extraction.md - How patterns are extracted and used
references/subagent-integration.md - How to integrate with custom subagents
examples/incident-example.json - Sample high-quality incident

Subagent Integration

When debugging involves subagents (your own or from other plugins), follow these guidelines to ensure debugging memory is utilized.

Automatic Behavior

Before spawning debugging-related subagents:

Search debugging memory first: npx @tyroneross/claude-code-debugger debug "<symptom>"
Pass relevant context to the subagent in its prompt
Include any matching incidents or patterns found

Example subagent prompt with debugging context:

Investigate the database timeout issue.

DEBUGGING MEMORY CONTEXT:
- Found 2 similar incidents: INC_20241215_db_timeout, INC_20241201_pool_exhaust
- Pattern PTN_connection_pool suggests checking pool size and idle timeout
- Previous fix: Increased pool size from 10 to 25 in DATABASE_URL

Start your investigation considering this prior knowledge.

When Subagents Cannot Access Debugging Memory

Inform the user when debugging memory cannot be used with subagents:

External MCP tools: "Note: The debugging subagent is using external MCP tools that cannot access local debugging memory. I searched memory beforehand and found [X matching incidents / no matches]."
Third-party agents: "Note: This third-party debugging agent doesn't have access to your project's debugging memory. Consider using /debugger first to check for similar past issues."
Sandboxed environments: "Note: The subagent runs in a sandboxed environment without access to debugging memory. I've pre-loaded relevant context from [X] matching incidents."

Integrating Debugger Into Your Own Subagents

If you create custom debugging subagents, include this in their system prompt:

## Debugging Memory Integration

Before investigating, check the debugging memory:

\`\`\`bash
npx @tyroneross/claude-code-debugger debug "<symptom>"
\`\`\`

Use results to:
- Skip re-investigation of known issues (confidence >70%)
- Use past fixes as starting points (confidence 40-70%)
- Document new findings after resolution

After fixing, document the incident by writing a JSON file to:
\`\`\`
.claude/memory/incidents/INC_YYYYMMDD_HHMMSS_xxxx.json
\`\`\`

Subagent Tool Requirements

For full debugging memory access, subagents need:

Bash tool - to run CLI commands
Read tool - to examine incident files (optional but helpful)

If a subagent lacks Bash access, it cannot query debugging memory directly. In this case:

Query memory yourself before spawning the subagent
Include relevant findings in the subagent prompt
Document any new findings after the subagent completes

Coordinating Multiple Debugging Subagents

When using parallel assessment (/assess) or multiple debugging subagents:

Pre-query memory once before spawning agents
Distribute context - each agent gets relevant subset
Aggregate findings - collect new insights from all agents
Store unified incident - document the combined diagnosis

Example flow:
1. Search: npx @tyroneross/claude-code-debugger debug "app crashing on login"
2. Spawn parallel: database-assessor, api-assessor, frontend-assessor
   - Each receives: symptom + relevant past incidents
3. Collect: assessments from all agents
4. Store: unified incident with root cause from winning assessment

Best Practices

Always check memory first - Saves time on previously solved bugs
Document every fix - Future debugging benefits from current work
Use descriptive symptoms - Better matching requires good descriptions
Include verification status - Helps prioritize trusted solutions
Run periodic scans - Capture debugging sessions from audit trail
Pass context to subagents - Don't let debugging knowledge stay siloed
Inform users of limitations - Be transparent when memory can't be accessed

Agent Skills: Debugging Memory Workflow

Skill Files