Knowledge Capture

Overview

Most engineering teams don’t fail from lack of code—they fail from loss of context.

Buzz Stack already emphasizes:

•AGENTS.md guidance
•deep /docs references
•repeatable workflows

This skill turns that into an explicit system: capture decisions, operational procedures, and anti-patterns in a way that stays searchable and up to date.

Outcomes you want:

•Future you can answer “why did we do this?” in < 2 minutes
•On-call can fix common incidents using a runbook
•Large refactors avoid repeating known mistakes
•New teammates can find authoritative docs quickly

Core Concepts

1) Architecture Decision Records (ADRs)

An ADR is a short document capturing a decision and its context.

Good ADRs have:

•a clear decision statement
•alternatives considered
•consequences/trade-offs
•status lifecycle (Proposed → Accepted → Superseded)

Minimal ADR structure:

markdown

# ADR-000X: Decision Title

## Status

Proposed | Accepted | Superseded

## Context

What problem are we solving? What constraints exist?

## Decision

What are we doing?

## Alternatives Considered

- Option A
- Option B

## Consequences

- Positive
- Negative

## Links

- PRs, docs, issues

2) Runbooks (Operational Procedures)

Runbooks should be:

•task-oriented (“do this, then that”)
•safe (explicit rollback)
•validated (tested occasionally)
•bounded (avoid huge essays)

Runbook skeleton:

markdown

# Runbook: <Incident / Operation>

## Symptoms

How to detect the issue.

## Impact

Who/what is affected.

## Immediate Actions

1. ...
2. ...

## Diagnosis

Commands, logs, dashboards.

## Resolution

Step-by-step fix.

## Rollback

How to undo safely.

## Prevention

What to improve.

3) Anti-Pattern Documentation

Anti-pattern docs prevent repeating painful failures.

A useful format:

•what we did
•why it failed
•what to do instead
•evidence (logs, PR links)

markdown

## Anti-pattern: <Name>

**What happened:**

**Why it failed:**

**Correct approach:**

**Real example:**

- Link to code or doc

4) Decision Analysis: Trade-Off Matrices and Risk Assessment

Decisions are rarely “right/wrong”; they’re tradeoffs.

A lightweight trade-off matrix:

text

Decision: Use Prisma vs raw SQL

Criteria            Prisma      Raw SQL
---------------------------------------
Time-to-ship         High        Medium
Type safety          High        Low/Medium
Performance control  Medium      High
Migration tooling    High        Low/Medium
Team familiarity     ?           ?

Risk assessment:

•probability (low/med/high)
•impact (low/med/high)
•mitigation

5) Living Documentation

Docs should be maintained like code:

•PR-reviewed
•linked from the codebase
•updated alongside changes

Patterns in Buzz Stack:

•/docs as a comprehensive knowledge base
•directory-level AGENTS.md for local conventions

6) Knowledge Organization: Taxonomy + Discoverability

If docs aren’t findable, they don’t exist.

Practical techniques:

•consistent naming (e.g., RUNBOOK-*, ADR-*)
•stable index docs (e.g., docs/README.md)
•cross-references at the bottom of each doc
•“owner” fields for accountability

Patterns (10+)

Pattern 1: ADR Template (MADR-inspired)

markdown

---
adr: 0007
title: Adopt Result<T,E> for service layer
status: Accepted
date: 2026-02-13
owners:
  - platform-team
---

# ADR-0007: Adopt Result<T,E> for service layer

## Context

We need consistent error handling across UI/service boundaries.

## Decision

Use a discriminated union Result type for expected failures.

## Alternatives

- Throw exceptions everywhere
- Return null/undefined

## Consequences

- Pros: explicit errors, easier UI mapping
- Cons: slightly more boilerplate

## Links

- docs/DESIGN_PATTERNS.md

Pattern 2: Decision Log for Small Choices

Not every decision deserves a full ADR. Use a decision log.

markdown

# Decision Log

- 2026-02-13: Use pnpm@9 (matches packageManager).
- 2026-02-14: Keep ESLint flat config at root.

Pattern 3: Runbook for Database Migration

markdown

# Runbook: Zero-Downtime Migration (Expand/Contract)

## Preconditions

- Staging tested
- Rollback plan approved

## Steps

1. Add nullable column
2. Deploy dual-write
3. Backfill in batches
4. Switch reads
5. Drop old column

## Rollback

- Revert app reads
- Leave expanded schema in place

Pattern 4: Incident Timeline Template

markdown

# Incident: <Title>

## Timeline (UTC)

- 10:02: Alert triggered
- 10:05: On-call acknowledged
- 10:12: Mitigation deployed

## Root Cause

## What Worked

## What Didn’t

## Action Items

- [ ] ...

Pattern 5: Postmortem With “Blameless” Format

markdown

# Postmortem: <Incident>

## Summary

## Customer Impact

## Root Cause

## Detection & Response

## Remediation

## Follow-ups

- Prevent recurrence
- Improve detection

Pattern 6: “Doc-Driven Refactor” Checklist

markdown

## Doc-Driven Refactor Checklist

- [ ] Capture current architecture (before)
- [ ] Identify invariants (what must not change)
- [ ] Define migration steps
- [ ] Add validation gates
- [ ] Update docs (after)

Pattern 7: Anti-Pattern Entries With ✅/❌ Examples

markdown

## Anti-pattern: Returning undefined for failure

❌ WRONG

- fetchUser(): User | undefined

✅ CORRECT

- fetchUser(): Result<User, NotFound | InvalidId>

Why

- forces handling
- preserves failure mode

Pattern 8: “Owner + Review Cadence” Metadata

markdown

---
owners:
  - platform
review:
  cadence: quarterly
  next: 2026-04-01
---

Pattern 9: Cross-Reference Footer

At the end of every major doc:

markdown

## See Also

- docs/ARCHITECTURE.md
- docs/DEPLOYMENT-DEVOPS.md
- docs/TROUBLESHOOTING.md

Pattern 10: Evidence Collection for Decisions

Capture:

•benchmarks
•error rates
•UX metrics
•logs/samples

markdown

## Evidence

- p95 latency: 820ms → 410ms
- error rate: 1.4% → 0.3%

Pattern 11: “FAQ-First” Troubleshooting

Troubleshooting docs should lead with common symptoms.

markdown

## Symptom: Build fails with ESLint flat config

### Cause

### Fix

### Prevention

Pattern 12: “System Map” Index Doc

Create a map of “where knowledge lives”.

markdown

# System Map

- Architecture: docs/ARCHITECTURE.md
- Patterns: docs/DESIGN_PATTERNS.md
- Ops: docs/DEPLOYMENT-DEVOPS.md
- Security: docs/SECURITY-VULNERABILITY.md

Anti-Patterns (5+)

Anti-pattern 1: Docs Without Owners

If no one owns a doc, it will drift.

Fix:

•add owners
•schedule review cadence

Anti-pattern 2: Runbooks Without Rollback

Runbooks that can’t roll back are dangerous.

Fix:

•explicit rollback step
•preconditions and safety checks

Anti-pattern 3: Giant “Everything Doc”

Huge docs become unsearchable and unmaintained.

Fix:

•split by task domain
•add index + cross-links

Anti-pattern 4: Decisions Captured Only in Chat

Fix:

•create ADR or decision log entry
•link PRs/issues

Anti-pattern 5: No Real Examples

Docs without examples aren’t actionable.

Fix:

•include code snippets and real file references

Real-World Buzz Stack Anchors

Buzz Stack already provides a strong base:

•AGENTS.md sets conventions and workflows
•/docs contains architecture, patterns, best practices, and troubleshooting guides
•scripts/session-audit.mjs suggests an audit workflow

Use these to bootstrap ADR/runbook placement:

•ADRs: docs/adr/ADR-0001-*.md (recommended)
•Runbooks: docs/runbooks/RUNBOOK-*.md (recommended)
•Decision log: docs/DECISIONS.md (recommended)

Cross-References

•
Skills:
- •project-management: ../project-management/SKILL.md
- •product-planning: ../product-planning/SKILL.md
- •content-strategy: ../content-strategy/SKILL.md
- •devops-deployment: ../devops-deployment/SKILL.md
•
Docs:
- •Self-improvement: ../../../docs/SELF-IMPROVEMENT.md
- •Team collaboration: ../../../docs/TEAM-COLLABORATION.md
- •Development: ../../../docs/DEVELOPMENT.md

Quick Checklist

•Is the decision captured (ADR or log)?
•Is there an owner and review cadence?
•Is there a runbook for risky operations?
•Are anti-patterns documented with ✅/❌ and evidence?
•Are docs searchable and cross-linked?

Appendix: ADR Status Lifecycle (Recommended)

Use a simple, explicit lifecycle so readers know whether a decision is current:

•Proposed: under discussion; do not implement broadly yet
•Accepted: approved and in effect
•Deprecated: still in use but should not be chosen for new work
•Superseded: replaced by a newer ADR (link it)
•Rejected: considered and explicitly not chosen (capture why)

Appendix: Tagging Conventions (Search Optimization)

Add consistent keywords near the top of docs to improve grep/search:

•tags: [migration, expand-contract, rollback]
•tags: [security, injection, prisma]
•tags: [performance, caching, swr]