skill-knowledge-management

name	skill-knowledge-management
description	Design docs, RFC (Request for Comments) process, ADR (Architecture Decision Records), code comments (WHY not WHAT), documentation structure, knowledge discovery and search, cross-team communication. Use when documenting decisions, writing design docs, or improving knowledge sharing.
version	1.0.0

Skill: Knowledge Management

Design docs live in git. Decisions are documented. Knowledge is discoverable.

RFC (Request for Comments)

Before designing (gather feedback early):

## RFC: [Title]

### Problem
[What problem are we solving?]

### Proposed Solution
[How does this solve it?]

### Alternatives
[Other approaches and why we rejected them]

### Trade-offs
[What do we gain/lose?]

### Timeline
[When will this ship?]

Design Doc

Before implementing (detailed specification):

## Design Doc: [Title]

### Problem Statement
[Why are we building this?]

### Goals & Non-Goals
[What we're doing, what we're not]

### Proposed Design
[Architecture, data flow, components]

### Alternatives Considered
[Why we chose this approach]

### Trade-offs
[Maintainability vs. speed, etc.]

### Implementation Plan
[Phases, dependencies]

### Testing Strategy
[How will we verify this works?]

### Risks & Mitigation
[What could go wrong?]

ADR (Architecture Decision Record)

After deciding (commit to git as history):

## ADR-0001: Microservices vs. Monolith

### Context
[Why are we deciding?]

### Decision
[What are we choosing?]

### Consequences
[What changes?]

### Alternatives Considered
[Other options]

Code Comments

DO: Explain WHY

# ✓ Explain the decision
# Retry only on transient errors (connection refused, timeout)
# Don't retry on permanent errors (auth, not found)
if isinstance(error, TransientError):
    retry()

DON'T: Explain WHAT (names say that)

# ✗ Redundant, names already say this
# Set retry count to 3
retry_count = 3

# ✓ Explain why 3
# Balances latency (most transient errors recover quickly)
# with reliability (rare cascading failures)
retry_count = 3

---

Status: Ready for knowledge work
Best for: Design docs, RFCs, ADRs, documentation