What is vibe-debugging-journal for?

A persistent, categorized log of resolved bugs capturing symptom, root cause, difficulty, fix, and prevention to surface patterns.

Should I log trivial bugs?

Only log non-trivial bugs that took more than 10 minutes or were hard to reproduce; trivial bugs do not require a journal entry.

Where do I store and link entries?

Store in docs/debugging-journal.md or DEBUGGING.md; use cross-reference by linking related entries.

vibe-debugging-journal

npx machina-cli add skill ash1794/vibe-engineering/debugging-journal --openclaw

Files (1)

SKILL.md

1.7 KB

vibe-debugging-journal

Bugs come in patterns. Recording them prevents re-investigation.

When to Use This Skill

After resolving a non-trivial bug (took >10 minutes to find)
After finding a bug that was hard to reproduce
After debugging something where the root cause was surprising
When you notice a bug pattern repeating

When NOT to Use This Skill

Trivial bugs (typos, missing imports)
Bugs with immediately obvious causes
Build/configuration issues (not really bugs)

Steps

Categorize the bug:
- Concurrency (race conditions, deadlocks, ordering)
- State Management (stale state, missing updates, cache invalidation)
- Type/Validation (type errors, missing validation, edge cases)
- Integration (API mismatch, version incompatibility, protocol errors)
- Environment (platform-specific, config, deployment)
- UI/Rendering (layout, hooks, lifecycle)
Record in structured format:

### [Category]: [Short description]
**Date**: [date]
**Symptom**: [What was observed]
**Root Cause**: [The actual problem]
**Why Hard to Find**: [What made debugging difficult]
**Fix**: [What was changed]
**Prevention**: [How to prevent recurrence]
**Files**: [affected files]

Save to persistent storage:
- Project: docs/debugging-journal.md or DEBUGGING.md
- Memory: Claude auto-memory or MCP
Cross-reference — If this relates to an existing journal entry, link them

Output Format

Present the entry for user confirmation, then save. Keep entries concise (5-10 lines each).

Source

git clone https://github.com/ash1794/vibe-engineering/blob/master/skills/debugging-journal/SKILL.mdView on GitHub

Overview

Record resolved bugs with symptom, root cause, difficulty, fix, and prevention, in a persistent journal. Entries are categorized by bug patterns (Concurrency, State Management, Type/Validation, Integration, Environment, UI/Rendering) to surface recurring issues. This structured log supports faster debugging and cross-reference across the project.

How This Skill Works

After resolving a non-trivial bug, categorize it using the predefined categories, then record a structured block with Date, Symptom, Root Cause, Why Hard to Find, Fix, Prevention, and Files. Save the entry to a persistent location such as docs/debugging-journal.md or DEBUGGING.md, and optionally link it to related entries for cross-reference.

When to Use It

After resolving a non-trivial bug (took >10 minutes to find).
After discovering a bug that was hard to reproduce.
After debugging something where the root cause was surprising.
When you notice a bug pattern repeating.
When documenting a debugging session for knowledge sharing.

Quick Start

Step 1: Categorize the bug into one of the defined categories.
Step 2: Record a structured entry with all fields (Date, Symptom, Root Cause, Why Hard to Find, Fix, Prevention, Files).
Step 3: Save to docs/debugging-journal.md or DEBUGGING.md and link related entries.

Best Practices

Categorize the bug into one of the six categories to surface patterns.
Record every field: Date, Symptom, Root Cause, Why Hard to Find, Fix, Prevention, Files.
Keep entries concise (about 5-10 lines) and use clear language.
Cross-reference with related entries to build a connected knowledge base.
Save to a persistent location and enable memory features for quick recall.

Example Use Cases

Concurrency: Race condition in order processing; Date: 2024-11-12; Symptom: duplicates under load; Root Cause: missing synchronization; Why Hard: timing-sensitive; Fix: added mutex; Prevention: add unit tests; Files: src/orderQueue.ts
State Management: Stale cache in user session; Date: 2024-11-15; Symptom: UI shows old profile; Root Cause: cache not invalidated; Why Hard: edge cases; Fix: invalidate on update; Prevention: cache invalidation hooks; Files: cache/sessionCache.js
Type/Validation: Missing email validation; Date: 2024-11-20; Symptom: invalid email accepted; Root Cause: lax validation; Why Hard: regex edge cases; Fix: tighten validator; Prevention: unit tests for edge cases; Files: validators/email.js
Integration: API version drift; Date: 2024-12-02; Symptom: 500 on /v2/order; Root Cause: contract drift; Why Hard: multiple services; Fix: align client to v2; Prevention: contract tests; Files: services/orderClient.js
Environment: Deployment config drift in staging; Date: 2024-12-10; Symptom: feature flags missing; Root Cause: wrong env var; Why Hard: config drift; Fix: fix deployment script; Prevention: config validation; Files: deploy/staging/config.yml

Frequently Asked Questions

Add this skill to your agents