Use this skill when writing, reviewing, or improving internal engineering documents - RFCs, design docs, post-mortems, runbooks, and knowledge base articles. Triggers on drafting a design proposal, writing an RFC, creating a post-mortem after an incident, building an operational runbook, organizing team knowledge, or improving existing documentation for clarity and completeness.
Use this skill when writing, reviewing, or improving internal engineering documents - RFCs, design docs, post-mortems, runbooks, and knowledge base articles. Triggers on drafting a design proposal, writing an RFC, creating a post-mortem after an incident, building an operational runbook, organizing team knowledge, or improving existing documentation for clarity and completeness.
When this skill is activated, always start your first response with the 🧢 emoji.
Internal Docs
Internal documentation is the connective tissue of engineering organizations. It
captures decisions (RFCs, design docs), preserves operational knowledge (runbooks),
extracts lessons from failure (post-mortems), and makes institutional knowledge
discoverable (knowledge management). This skill gives an agent the ability to draft,
review, and improve internal documents that are clear, actionable, and structured
for their specific audience - from a 2-page RFC to a detailed incident post-mortem.
When to use this skill
Trigger this skill when the user:
Wants to write or draft an RFC or design document
Needs to create a post-mortem or incident review document
Asks to build an operational runbook or playbook
Wants to organize or structure a team knowledge base
Needs to review an existing internal doc for completeness or clarity
Asks about documentation templates, formats, or best practices
Wants to write an ADR (Architecture Decision Record)
Needs to create onboarding documentation or team guides
Do NOT trigger this skill for:
Public-facing API documentation or developer docs (use api-design skill)
README files or open-source project documentation (use code-level docs conventions)
Key principles
Write for the reader, not the writer - Every document exists to transfer
knowledge to someone else. Identify who will read it (decision-makers, on-call
engineers, new hires) and structure for their needs, not your thought process.
Decisions over descriptions - The most valuable internal docs capture the
"why" behind choices. A design doc that only describes the solution without
explaining alternatives considered and tradeoffs made is incomplete.
Actionability is everything - A runbook that says "investigate the issue"
is worthless. A post-mortem without concrete action items is theater. Every
document should leave the reader knowing exactly what to do next.
Living documents decay - Docs that aren't maintained become dangerous.
Every document needs an owner and a review cadence, or it should be marked
with an explicit expiration date.
Structure enables skimming - Engineers don't read docs linearly. Use
headers, TL;DRs, tables, and callouts so readers can find what they need
in under 30 seconds.
Core concepts
Internal docs fall into four categories, each with a distinct lifecycle and audience:
Decision documents (RFCs, design docs, ADRs) propose a change, gather feedback,
and record the final decision. They flow through draft, review, approved/rejected
states. The audience is peers and stakeholders who need to evaluate the proposal.
See references/rfcs-and-design-docs.md.
Incident documents (post-mortems, incident reviews) are written after something
goes wrong. They reconstruct the timeline, identify root causes, and produce action
items. The audience is the broader engineering org learning from failure. Blamelessness
is non-negotiable. See references/post-mortems.md.
Operational documents (runbooks, playbooks, SOPs) provide step-by-step procedures
for recurring tasks or incident response. The audience is the on-call engineer at
3 AM who needs to fix something fast. See references/runbooks.md.
Knowledge documents (wikis, guides, onboarding docs, team pages) preserve
institutional knowledge. The audience varies but typically includes new team members
and cross-team collaborators. See references/knowledge-management.md.
Common tasks
Draft an RFC
An RFC proposes a significant technical change and invites structured feedback.
Use this template structure:
# RFC: <Title>**Author:**<name>**Status:** Draft | In Review | Approved | Rejected
**Created:**<date>**Last updated:**<date>**Reviewers:**<list>**Decision deadline:**<date>## TL;DR
<2-3 sentences: what you propose and why>
## Motivation<Whatproblemdoesthissolve? Whynow? Whathappensifwedonothing?>## Proposal<Thedetailedsolution.Includediagrams, datamodels, APIcontractsasneeded.>## Alternatives considered<Atleast2alternativeswithhonestpros/consforeach>## Tradeoffs and risks<Whatarewegivingup? Whatcouldgowrong? Howdowemitigate?>## Rollout plan<Howwillthisbeimplementedincrementally? Featureflags? Migration?>## Open questions<Unresolveditemsthatneedinputfromreviewers>
Always include at least two genuine alternatives. A single-option RFC signals
the decision was made before the review process started.
Write a post-mortem
Post-mortems extract organizational learning from incidents. Follow a blameless
approach - focus on systems and processes, never on individuals.
# Post-Mortem: <Incidenttitle>**Date of incident:**<date>**Severity:** SEV-1 | SEV-2 | SEV-3
**Author:**<name>**Status:** Draft | Review | Final
**Time to detect:**<duration>**Time to resolve:**<duration>## Summary
<3-4 sentences: what happened, who was affected, and the impact>
## Timeline
| Time (UTC) | Event |
|---|---|
| HH:MM | <whathappened> |
## Root cause<Thedeepest "why" -usethe5Whystechniquetogobeyondsymptoms>## Contributing factors<Otherconditionsthatmadetheincidentpossibleorworse>## What went well<Thingsthatworkedduringresponse-detection, communication, tooling>## What went poorly<Processorsystemgapsexposedbytheincident>## Action items
| Action | Owner | Priority | Due date | Status |
|---|---|---|---|---|
| <specificaction> | <name> | P0/P1/P2 | <date> | Open |
Every action item must be specific, assigned, and dated. "Improve monitoring"
is not an action item. "Add latency p99 alert on checkout service at 500ms
threshold" is.
Create a runbook
Runbooks provide step-by-step procedures for operational tasks. Write them for
the worst case: an engineer who has never seen this system, at 3 AM, under stress.
# Runbook: <Procedurename>**Owner:**<team>**Last verified:**<date>**Estimated time:**<duration>**Risk level:** Low | Medium | High
## When to use<Triggerconditions-whatalert, symptom, orrequestleadshere>## Prerequisites- [ ] Access to <system>- [ ] Permissions: <specificrolesorcredentialsneeded>## Steps### Step 1: <Action><ExactcommandorUIaction.Noambiguity.>```bash
kubectl get pods -n production -l app=checkout
Expected output:If this fails: <what to do - escalation path or alternative>
Step 2:
...
Rollback
Escalation
<Who to contact if the runbook doesn't resolve the issue>
> Test every runbook by having someone unfamiliar with the system follow it.
> If they get stuck, the runbook is incomplete.
### Write an Architecture Decision Record (ADR)
ADRs are lightweight, immutable records of a single architectural decision.
```markdown
# ADR-<NNN>: <Decision title>
**Status:** Proposed | Accepted | Deprecated | Superseded by ADR-<NNN>
**Date:** <date> **Deciders:** <names>
## Context
<What forces are at play? What constraint or opportunity triggered this decision?>
## Decision
<The change we are making. State it clearly in one paragraph.>
## Consequences
<What becomes easier? What becomes harder? What are the risks?>
ADRs are append-only. If a decision is reversed, write a new ADR that supersedes
the old one. Never edit a finalized ADR.
Review an existing document for quality
Walk through the doc checking these dimensions in order:
Audience - Is it clear who this is for? Does the depth match their expertise?
Structure - Can a reader find what they need by skimming headers?
Completeness - Are there gaps that will generate questions?
Actionability - Does the reader know what to do after reading?
Freshness - Is the information current? Are there stale references?
Conciseness - Can anything be cut without losing meaning?
Organize a knowledge base
Structure team knowledge around these four categories (adapted from Divio):
Category
Purpose
Example
Tutorials
Learning-oriented, step-by-step
"Setting up local dev environment"
How-to guides
Task-oriented, problem-solving
"How to deploy a canary release"
Reference
Information-oriented, accurate
"API rate limits by tier"
Explanation
Understanding-oriented, context
"Why we chose event sourcing"
Avoid dumping all docs into a flat wiki. Tag documents by category, team, and
system so they remain discoverable as the org scales.
Anti-patterns / common mistakes
Mistake
Why it's wrong
What to do instead
Wall of text
No headers, no TL;DR, no structure - nobody will read it
Add TL;DR upfront, use headers every 3-5 paragraphs, use tables for structured data
Blame in post-mortems
Naming individuals creates fear and suppresses honest reporting
Focus on system and process failures. "The deploy pipeline lacked a canary step" not "Bob deployed without checking"
Runbook with "use judgment"
On-call engineers under stress cannot exercise judgment on unfamiliar systems
Provide explicit decision trees with concrete thresholds
RFC without alternatives
Signals the decision is already made and review is theater
Always include 2+ genuine alternatives with honest tradeoffs
Stale documentation
Outdated docs are worse than no docs - they build false confidence
Set review dates, assign owners, archive aggressively
Copy-paste templates
Filling a template mechanically without adapting to context
Post-mortems and reviews that identify problems but assign no follow-up
Every identified gap must produce a specific, assigned, dated action item
Gotchas
RFCs without a decision deadline stay in "review" forever - An RFC without a deadline becomes a perpetual discussion that blocks implementation. Always set a concrete decision deadline (typically 1-2 weeks) in the frontmatter, and explicitly close the RFC as Approved or Rejected on that date even if not everyone has commented.
Post-mortems written more than a week after the incident lose critical detail - Memory degrades fast. Timelines reconstructed from memory a week later miss key decision points and often misattribute causality. The IC should assign a post-mortem owner and require a draft timeline within 24 hours of resolution, even if the full document takes 5 days.
ADRs edited retroactively destroy the historical record - An ADR is only valuable as a record of what was decided and why at a specific point in time. If you update an ADR to reflect a changed decision, future readers can't distinguish the original context from the revision. Write a new ADR that supersedes the old one; mark the old one "Superseded by ADR-NNN".
Runbooks with "check the dashboard" as a step fail at 3 AM - "Check the monitoring dashboard" is not a runbook step. A runbook step specifies which dashboard, which panel, what a normal reading looks like, and what to do if it's abnormal. Vague steps require context the on-call engineer won't have. Every step needs a specific action, an expected result, and a failure path.
Wiki pages without owners decay into organizational memory holes - A wiki page written once and never reviewed will be confidently wrong within 6-12 months for any actively developed system. Every page needs a named owner and a "Last verified" date. Unmaintained pages should be archived, not left as false ground truth.
References
For detailed content on specific document types, read the relevant file from
references/:
references/rfcs-and-design-docs.md - Deep guide on RFC lifecycle, review processes, and design doc patterns
references/runbooks.md - Runbook authoring patterns, testing procedures, and maintenance workflows
references/knowledge-management.md - Knowledge base organization, documentation culture, and tooling strategies
Only load a references file if the current task requires deep detail on that topic.
Companion check
On first activation of this skill in a conversation: check which companion skills are installed by running ls ~/.claude/skills/ ~/.agent/skills/ ~/.agents/skills/ .claude/skills/ .agent/skills/ .agents/skills/ 2>/dev/null. Compare the results against the recommended_skills field in this file's frontmatter. For any that are missing, mention them once and offer to install:
