The Debug Journal: Write While Debugging to Solve

You're debugging.

There's a bug.

You don't know what's wrong.

You try something.

Doesn't work.

You try something else.

Still doesn't work.

You're thrashing.

The fastest debuggers aren't the ones who know most.

They're the ones with the best process.

And that process starts with writing.

When you write down what you're trying, what you're seeing, and why you think it's happening, you solve the problem faster.

This guide covers building a debug journal practice.

---

Why Writing Makes Debugging Faster

Reason 1: Slows Assumptions

When you're panicked, you thrash.

Try thing. Fail. Try thing. Fail.

Writing forces you to slow down.

"What exactly am I seeing?"

"What am I assuming?"

Often, writing surfaces the wrong assumption.

Reason 2: Externalizes Thinking

Your brain has limited working memory.

You remember 3–4 things simultaneously.

Bug has 10 relevant pieces.

Your brain is overloaded.

Writing externalizes thinking.

Now you can reference it instead of holding it.

Reason 3: Reveals Blind Spots

You're stuck in a loop.

You write it down.

Reading your own words: "Wait, that doesn't make sense."

Writing surfaces contradictions.

Reason 4: Creates Pattern Recognition

You debug.

You write what you discovered.

Next bug in similar area?

You have context.

You solve it faster.

Reason 5: Builds Team Knowledge

Your bug is usually someone else's future bug.

Written journal → Sharable knowledge.

Team learns patterns without making mistakes themselves.

---

The Debug Journal Template

Use this template every time you hit a non-trivial bug:

Bug: [Short Description]

Date: [YYYY-MM-DD]

Time Spent: [Start time - end time]

Severity: [Critical / High / Medium / Low]

Initial Symptom

[What did you observe? Error message? Behavior?]

Suspected Cause (Initial)

[What did you think it was?]

Investigation (Attempts)

Attempt 1:

• Hypothesis: [What did you think?]
• Action: [What did you try?]
• Result: Failed because...
• Time: [5 min]

Attempt 2:

• Hypothesis: [What did you think?]
• Action: [What did you try?]
• Result: Failed because...
• Time: [10 min]

Attempt 3:

• Hypothesis: [What did you think?]
• Action: [What did you try?]
• Result: Success!
• Time: [15 min]

Root Cause

[What was actually wrong?]

Solution

[How did you fix it?]

[Code or command that fixed it]

Key Insight

[Why did this happen? What will prevent it next time?]

Related Issues

[Similar bugs or gotchas to watch for]

Total Time: [XX minutes]

---

Concrete Example

Bug: User sessions timing out unexpectedly

Date: 2025-02-15

Time Spent: 14:30 – 15:15 (45 minutes)

Severity: High

Initial Symptom

Users reporting they get logged out after 5–10 minutes of activity.

Error: "Session expired. Please login again."

Expected: 30-minute session timeout.

Suspected Cause (Initial)

Session TTL too short in Redis configuration.

Investigation

Attempt 1:

• Hypothesis: Redis TTL is 5 min instead of 30 min
• Action: Check Redis config
• Result: TTL was correctly set to 30 min in config
• Time: 3 min

Attempt 2:

• Hypothesis: Session refresh not working. Token not renewing.
• Action: Add logging to refresh endpoint
• Result: Refresh endpoint never being called
• Time: 8 min

Attempt 3:

• Hypothesis: Frontend not calling refresh endpoint
• Action: Check frontend code for refresh logic
• Result: Frontend was calling, but refresh token was expired
• Time: 12 min

Attempt 4:

• Hypothesis: Refresh token TTL too short
• Action: Check refresh token configuration
• Result: Refresh token TTL was 10 minutes (shorter than session!)
• Time: 5 min
• SUCCESS: Changed refresh token TTL to 1 hour

Root Cause

Refresh token TTL was set to 10 minutes, shorter than session timeout of 30 minutes.

When session tried to refresh, refresh token was already expired.

Result: User logged out even though session should have been valid.

Solution

Changed refresh token TTL from 10 minutes to 1 hour.

const REFRESH_TOKEN_TTL = 1 * 60 * 60; // 1 hour
const SESSION_TTL = 30 * 60; // 30 minutes

Deployed to production.

Key Insight

Refresh token TTL should ALWAYS be longer than session TTL.

Otherwise, session can't be renewed.

This is a pattern we need to document and test for.

Related Issues

• Similar pattern in password reset tokens
• Should add test: "Verify refresh token TTL > session TTL"

Total Time: 45 minutes

---

When to Write in Debug Journal

Definitely Journal:

• Non-trivial bugs (>5 min to solve)
• Production issues
• Bugs that repeat (same area, different trigger)
• Bugs that taught you something

Can Skip Journal:

• Trivial typo fixes (5 sec)
• Bugs you've solved before (reference old entry instead)
• Interruptions you'll immediately continue

Rule of thumb: If you spent 5+ minutes debugging, journal it.

---

How to Maintain Debug Journal

During Debugging:

• Keep journal entry open while debugging
• Add each attempt as you try it
• Timestamp entries
• Don't wait until you're done (memory fades)

Right After Bug Fix:

• Add root cause analysis
• Add key insight (lesson learned)
• Tag related issues
• Close entry

Weekly Review:

• Scan week's entries
• Any patterns?
• Common areas?
• Lessons for team?

Monthly:

• Review all entries
• Are there categories of bugs repeating?
• Do you need a new pattern to prevent them?

---

Tools for Debug Journal

Tool 1: Markdown File in Project

Setup:

docs/
├── debug-journal.md

Entry example:

# Debug Journal

Bug: Session timeout [2025-02-15]

... entry ...

Bug: Memory leak in event listeners [2025-02-14]

... entry ...

**Pros:** Simple, searchable, in version control

**Cons:** No special formatting

### Tool 2: Notion Database

**Properties:**

- Bug Title
- Date
- Severity
- Root Cause
- Solution
- Time Spent
- Tag (area of code)
- Related Bugs

**Workflow:**

1. Create new entry when you start debugging
2. Add attempts as you go
3. Complete entry when fixed
4. Search by tag for patterns

**Pros:** Beautiful, searchable, organized

**Cons:** Takes time to set up

### Tool 3: GitHub Issue (With Label)

**Setup:**

1. Create GitHub issue: "BUG: [Title]"
2. In issue description, add debug process
3. Label as "debug-journal"
4. Close when fixed

**Pros:** Integrated with code, visible to team

**Cons:** May be too formal for internal debugging

### Tool 4: Simple Slack Thread

**Setup:**

1. Create Slack thread in #dev-journal channel
2. Add attempts as replies
3. Summarize solution at end

**Pros:** Team can see it, can discuss

**Cons:** Not well-organized, easy to lose

---

Patterns That Emerge From Debug Journals

Pattern 1: Common Root Causes

After 20 entries, you'll see:

• "I always forget to clear cache after deployments"
• "Async operations trip me up consistently"
• "I misunderstand how this library works"

These are signals. Document them.

Pattern 2: Areas That Need Documentation

Certain parts of codebase generate lots of bugs.

Signal: Documentation is insufficient.

Write docs or refactor the code.

Pattern 3: Debugging Techniques That Work

You develop techniques through practice.

"Add logging here first."

"Always check the error logs before assumptions."

Document your best techniques.

---

Team-Level Benefits

Benefit 1: Onboarding

New engineer reviews debug journal entries.

Sees common gotchas.

"Oh, I need to clear cache after deployments."

Avoids first bug.

Benefit 2: Better Code Review

Reviewer reads debug journal.

Asks: "Should we add a test for this?"

Prevents future bugs.

Benefit 3: Shared Patterns

Team sees everyone's bugs.

Common patterns emerge.

Team decides: "Let's add a linter rule for this."

Benefit 4: Knowledge Base

Debug journal becomes searchable knowledge base.

"I had this error before. Let me search."

---

Realistic Practice

Week 1:

• Create debug journal system
• Add 3–5 entries from bugs you solve
• Get comfortable with template

Week 2–4:

• Journal every non-trivial bug
• Review entries weekly
• Notice patterns

Month 2:

• 20–30 entries
• Patterns visible
• Team starts asking "did we journal that?"

Month 3+:

• Refer back to entries constantly
• Solve similar bugs faster
• Teach new people from entries

---

Metrics That Matter

Metric 1: Time to Resolution

Track: How long does bug take to solve?

Compare pre-journaling vs. post-journaling.

Expected: 20–30% faster after building pattern knowledge.

Metric 2: Repeat Bugs

Track: How many times does same bug occur?

With journaling, reduces dramatically (reference old entry, solve instantly).

Metric 3: Journal Entries Referenced

Track: How often do you reference old entries?

• Low: <1/week (not building knowledge)
• Good: 3–5/week (building patterns)
• Excellent: 5+/week (strong knowledge base)

---

Conclusion

Writing while debugging makes you faster.

Debug Journal Template:

1. Symptom: What's broken?
2. Suspected Cause: What's your first guess?
3. Attempts: What did you try? What happened?
4. Root Cause: What was actually wrong?
5. Solution: How did you fix it?
6. Key Insight: What did you learn?

How to start:

1. Next non-trivial bug, create journal entry
2. Add attempts as you try them
3. When fixed, add root cause + insight
4. Review weekly for patterns
5. Reference entries for similar bugs

In 3 months:

• 30–50 debug entries
• Clear patterns of problem areas
• 20–30% faster debugging
• Knowledge base for team

For developer notes, see Developer Notes System. For productivity, check Developer Productivity Guide.