debug-session-documenter

name

debug-session-documenter

description

Prompt template for documenting debugging sessions after successfully fixing bugs. Use this to capture debugging methodology, hypothesis evolution, red herrings, breakthrough moments, and lessons learned for future agents. Trigger keywords - debug knowledge base, document debugging session, debugging methodology, post-mortem analysis, incident report debugging, debug report template, capture debugging process.

Debug Session Documenter

Purpose: Use this prompt AFTER an agent has successfully fixed a bug to capture their debugging methodology for future reference.

---

Copy-Paste Prompt for Agent

You just successfully debugged and fixed an issue. Please document your debugging
methodology in a structured report so that future agents (or humans) can learn from
your process and apply similar techniques when encountering similar symptoms.

Create a document in ./ai/generated_doc/ with filename: debug-report-{brief-bug-name}-{YYYY-MM-DD}.md

Include the following sections:

## 1. EXECUTIVE SUMMARY
- **Problem Statement**: What was broken? (user-facing symptoms, not root cause)
- **Root Cause**: What actually caused it? (1-2 sentences)
- **Solution**: What fixed it? (1-2 sentences)
- **Files Modified**: List with file_path:line_number references

## 2. SYMPTOM PROFILE
Document the observable symptoms that would help future agents recognize similar issues:
- What error messages appeared? (exact text)
- What behavior was unexpected?
- What worked vs what didn't work?
- What environmental conditions were present? (OS, versions, config)
- What user actions triggered it?

This section helps future agents match symptoms to your debugging strategy.

## 3. INITIAL HYPOTHESIS EVOLUTION
Show how your understanding evolved from first impression to final diagnosis:

### Hypothesis Timeline
| Time | Hypothesis | Why It Seemed Right | Evidence At The Time |
|------|-----------|---------------------|---------------------|
| T+0min | [First thought] | [Reasoning] | [What you saw] |
| T+Xmin | [Revised thought] | [New reasoning] | [New evidence] |
| T+Ymin | [Final correct understanding] | [Why this is the true cause] | [Definitive proof] |

### What Changed Your Mind?
Explain the pivotal moment or evidence that shifted you from wrong hypothesis to correct one.

## 4. DEBUGGING STRATEGY & METHODOLOGY
Document your systematic approach (so future agents can replicate it):

### Strategy Type
- [ ] Top-down (start from high-level symptoms, drill down)
- [ ] Bottom-up (start from low-level logs/code, build up)
- [ ] Binary search (divide and conquer)
- [ ] Comparative analysis (working vs broken)
- [ ] Time-travel debugging (git bisect, rollback)
- [ ] Other: [describe]

### Investigation Steps (Chronological)
For each major step, document:
1. **What you did**: [Action taken]
2. **Why you did it**: [Reasoning]
3. **What you learned**: [Finding]
4. **What you ruled out**: [What this eliminated]
5. **Next decision**: [Where to investigate next]

### Tools & Techniques Applied
List the debugging tools/techniques you used and why they were effective:
- **Tool/Technique**: [Name]
- **When Used**: [At what stage]
- **What It Revealed**: [Key insight gained]
- **Would You Use Again?**: [Yes/No and why]

## 5. DEBUG INSTRUMENTATION DETAILS
Document the temporary code you added to diagnose the issue:

### Instrumentation Locations
For each place you added debug code:

**Location**: `file_path:line_number`
**Purpose**: [What you were trying to observe]
**Implementation**:
```language
# Show the actual debug code you added
[paste debug prints, logs, assertions, etc.]

Key Insight Gained: [What this instrumentation revealed] When Added/Removed: [Timeline]

Reusable Debug Patterns

If you developed a debug technique that could be reused:

# Reusable debug pattern
[generalized version of your debug code]

When To Use: [Describe scenarios where this pattern helps]

6. THE FIX

Document the actual solution:

Code Changes

# BEFORE (buggy code)
[original code]

# AFTER (fixed code)
[corrected code]

Why This Fix Works

Explain the mechanism by which your fix addresses the root cause (not just "it works now").

Trade-offs & Alternatives Considered

• Alternative 1: [Description] - Rejected because [reason]
• Alternative 2: [Description] - Rejected because [reason]
• Chosen Solution: [Why this is optimal]

7. TESTING & VALIDATION STRATEGY

Document how you proved the fix works:

Reproduction Method

# Exact steps/commands to reproduce the original bug
[paste commands]

Validation Tests

Test Scenario	Purpose	Before Fix	After Fix
[Scenario]	[What it validates]	❌ [How it failed]	✅ [How it passes]

Regression Prevention

What tests/checks would catch this bug if it's reintroduced?

# Test code or validation steps
[if applicable]

8. RED HERRINGS & BREAKTHROUGH ANALYSIS

Document what led you astray and what got you back on track:

Red Herring #1: [Misleading Clue]

• What Seemed Wrong: [Description of false lead]
• Why It Seemed Plausible: [The logic that fooled you]
• Time Invested: [How long you pursued this]
• How You Ruled It Out: [The evidence/test that disproved it]
• Lesson: [What future agents should watch for]

The Breakthrough Moment

• When: [Relative time in debug session]
• What Happened: [The "aha!" realization]
• Why This Was Key: [What made this insight critical]
• What Enabled It: [What tool/technique/observation led to breakthrough]

9. METHODOLOGY LESSONS FOR FUTURE AGENTS

Extract transferable debugging wisdom:

What Worked Well (REPLICATE THIS)

1. Technique: [Name]
   • Why It Helped: [Explanation]
   • When To Use: [Applicable scenarios]
   • Example: [How you used it]

What Didn't Work (AVOID THIS)

1. Technique: [Name]
   • Why It Failed: [Explanation]
   • What To Do Instead: [Better approach]
   • Warning Signs: [How to recognize you're going down this path]

Pitfalls Specific To This Bug Pattern

1. Pitfall: [Specific mistake]
   • Why It's Tempting: [Why agents fall for this]
   • How To Avoid: [Concrete prevention strategy]
   • Detection: [How to know you're making this mistake]

Generalizable Patterns

If this bug represents a class of issues:

• Bug Pattern Name: [e.g., "Race condition in async initialization"]
• Symptom Signature: [How to recognize similar bugs]
• Root Cause Pattern: [Common underlying cause]
• Debug Strategy: [Approach that works for this pattern]
• Fix Pattern: [Common solution approach]

10. EFFICIENCY ANALYSIS

Reflect on your debugging efficiency:

Time Breakdown

• Total Debug Time: [Duration]
• Time To Reproduction: [Duration]
• Time On Wrong Hypotheses: [Duration]
• Time On Correct Path: [Duration]
• Time To Implement Fix: [Duration]
• Time To Validate: [Duration]

What Would You Do Differently?

• Skip Earlier: [What you'd skip knowing what you know now]
• Start With: [What you'd investigate first if you could redo it]
• Key Shortcut: [Fastest path to the answer in hindsight]

11. KNOWLEDGE BASE ENTRY

Create a searchable reference for future agents:

Symptom Keywords: [comma, separated, searchable, terms] Root Cause Type: [e.g., race condition, null pointer, logic error, config issue] Component Affected: [e.g., auth module, database layer, API endpoint] Debug Strategy That Worked: [Brief name of your approach] Time To Fix: [Duration from start to validated fix] Difficulty: [Low/Medium/High]

Quick Reference For Future Agents

"If you see [SYMPTOM X], and you've ruled out [COMMON FALSE LEAD], check [WHERE YOU FOUND THE BUG] by [HOW YOU DIAGNOSED IT]. The fix involves [SOLUTION TYPE]."

---

Template Metadata

• Your Agent ID: [paste your agent ID]
• Session ID: [if known]
• Date: [YYYY-MM-DD]
• Bug Severity: [Critical/High/Medium/Low]
• Time Investment: [Total debugging hours]

Remember: Focus on METHODOLOGY and PROCESS, not just the specific bug details. Future agents should be able to learn your debugging techniques and apply them to similar symptoms even if the exact bug is different.

---

## Usage Instructions

1. **When to use**: After an agent has successfully debugged and fixed an issue
2. **How to use**: Copy the prompt block above and send it to the agent
3. **Where output goes**: The agent will create a file in `./ai/generated_doc/`
4. **Benefits**:
   - Captures debugging methodology
   - Creates searchable symptom profiles
   - Documents red herrings for future avoidance
   - Builds institutional debugging knowledge