Kb

Create or update a Developer Knowledge Base entry for a bug fix, production incident, or non-obvious technical issue.

You are a senior engineer documenting a fix so the team never hits this problem again. Follow the 5 Whys methodology to find root cause, not just symptoms.

Input

$ARGUMENTS can be:

• Empty — analyze the current conversation for bugs/fixes discussed and create an entry
• update KB-NNNN — update an existing entry by ID
• list — show the current KB index
• A description of the issue to document

Output

A markdown file in docs/knowledge-base/ (or the project's KB directory) following the template below.

KB Entry Template

# KB-NNNN: [Short descriptive title]

**Date:** YYYY-MM-DD
**Severity:** Critical | High | Medium | Low
**Services affected:** [list of services/components]
**Discovered by:** [how it was found — user report, monitoring, code review, deploy failure]

## Symptoms

What the user/developer observed. Be specific — include error messages, HTTP status codes, log snippets.

## Root Cause (5 Whys)

1. **Why** did [symptom] happen? → Because [direct cause]
2. **Why** did [direct cause] happen? → Because [deeper cause]
3. **Why** did [deeper cause] happen? → Because [systemic cause]
4. **Why** did [systemic cause] happen? → Because [process/design gap]
5. **Why** did [process/design gap] exist? → Because [root cause]

**Root cause:** [one-sentence summary of the true root cause]

## Fix Applied

What was changed and why. Include:
- Files modified (with paths)
- The specific code/config change
- Commit hash (if available)

## Prevention

How to prevent this class of bug from recurring:
- [ ] Automated test added? (describe what it tests)
- [ ] Monitoring/alerting added? (describe the alert)
- [ ] Documentation updated? (link to docs)
- [ ] Code review checklist item? (what to look for)
- [ ] Architecture change needed? (describe if applicable)

## Related

- Links to PRs, issues, or other KB entries
- Similar patterns in other parts of the codebase

Rules

1. ID Assignment: Find the highest existing KB-NNNN in the knowledge base directory and increment by 1
2. Title: Should describe the problem, not the fix. "Dashboard crashes on empty org" not "Add null check to dashboard"
3. 5 Whys: Go deep. If you can't get to 5 whys, the root cause is probably surface-level
4. Prevention: At least one prevention item must be actionable (not just "be more careful")
5. Index: After creating the entry, update the index file (README.md or INDEX.md) in the KB directory
6. Don't document: Simple typos, dependency bumps, or issues already documented in an existing entry

When to Prompt for KB Entry

After completing a bug fix, ask: "This looks like it warrants a KB entry. Want me to add one?"

Trigger conditions:

• Root cause was non-obvious or required multi-step investigation
• Fix touches auth, messaging, multi-tenancy, or infrastructure
• The same class of bug could recur in other parts of the codebase
• A prevention action exists beyond the immediate fix

Skip for: typos, cosmetic fixes, dependency bumps, feature development (unless it uncovered a latent bug).

$ARGUMENTS

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: vrajasekaran
• Source: vrajasekaran/claude-skills
• License: MIT

Install and usage instructions live in the source repository linked above.