
han-documentation
Documentation skills for the Han suite: writing down what the team built and decided. Home of project-documentation, architectural-decision-record, and runbook. Depends on han-communication and han-core; bundled by the han meta-plugin.
- version
- 1.0.1
- GitHub stars
- 352
Install
/plugin install han-documentation@hanRun it inside Claude Code after adding the marketplace with /plugin marketplace add testdouble/han.
Contents
Discovered from sourceSkills 3
Create ADR
Operating Principles
- YAGNI applies to ADRs themselves. Apply the evidence-based YAGNI rule from ../../references/yagni-rule.md. An ADR is worth recording only when there is a concrete forcing function today — a real decision the team is actively making, an existing code path or architectural choice that will be locked in by this record, an applicable regulation, a customer commitment, or a documented incident that drove the choice. ADRs about decisions that don't have to be made yet, "for future flexibility", "best practice says we should pick X", or symmetry with other ADRs ("we have one for auth, so we should have one for billing") are YAGNI candidates and the ADR should not be written. When proposed, recommend deferral with the trigger that would justify writing the ADR (a real decision arising, a real incident, a real regulation taking effect). The user always wins; the rule's job is to make the cost of writing speculative architectural records visible — every ADR is a future-reader's load and a pattern future agents will treat as committed.
- The companion evidence rule applies to the ADR's supporting evidence. Apply the evidence rule from ../../references/evidence-rule.md to the citations that justify the ADR's decision and rejected alternatives. Name the trust class of each citation (codebase, web, provided); mark single-source web claims that drive the chosen option; and when no evidence at any tier supports a claimed trade-off, label it rather than presenting it as a weak preference.
- The readability rule shapes the ADR's prose. Source the standard by invoking
han-communication:readability-guidanceand apply it as you write the ADR. Hold its default audience frame: a capable reader who did not make this decision and lacks your context. The frame governs how each section reads, never whether a required technical fact appears.
Project Context
- CLAUDE.md: !
find . -maxdepth 1 -name "CLAUDE.md" -type f - project-discovery.md: !
find . -maxdepth 3 -name "project-discovery.md" -type f - personal config directory: !
bash "${CLAUDE_PLUGIN_ROOT}/scripts/han-config-dir.sh" 2>/dev/null || echo "$HOME/.claude" - project .han/config.md: !
cat .han/config.md 2>/dev/null || echo ""
As your first action, use the Read tool on .han/config.md inside the personal config directory path above. A read
that returns no file is no personal configuration: continue silently. When that file or the project .han/config.md
probe supplies content, apply it per config-rule.md, which governs precedence
between the two files, relative-path resolution, and what to do with a file that reads but cannot be used.
Step 1: Determine Mode
Determine which mode to operate in based on the user's request:
| Mode | When | Initial Status | Then |
|---|---|---|---|
| Creating new | Building an ADR from scratch for a new or recent decision | proposed | → Step 2 |
| Converting existing | User provides an existing document to convert into an ADR | accepted | → Step 2 |
| Updating existing | Modifying an existing ADR (status change, superseding, adding notes) | — | Read the existing ADR, → Step 3 |
Step 2: Discover Project Structure
-
Retrieve project config: Resolve project config: read CLAUDE.md's
## Project Discoverysection for docs and ADR directories; fall back to project-discovery.md; fall back to Glob defaults (docs/,docs/adr/). Continue without any keys that remain unfound. -
Determine the ADR directory: Use the ADR directory if found; otherwise use
{docs-dir}/adr/if a docs directory was found; otherwise usedocs/adr/. Runmkdir -pon the resolved directory to ensure it exists. -
Enumerate existing ADRs: Use Glob to find existing
.mdfiles in the ADR directory. -
Check existing ADR format: If existing ADRs were found, read one to understand the project's format. If it differs from template.md, ask the user whether to match the existing format or use this skill's template.
-
Discover the filename hierarchy taxonomy: ADRs are organized by a one- or two-level hierarchy encoded in the filename so related decisions sort together in a directory listing. Discover the taxonomy that applies to this project — never hardcode it.
- From existing filenames: If existing ADRs were enumerated, parse their filenames to extract the leading
hierarchy segments already in use (e.g.,
auth-session-storage.md→ top-levelauth;auth-tokens-rotation.md→ top-levelauth, second-leveltokens). Build a list of top-level prefixes and known second-level prefixes per top-level. - From project context: Read CLAUDE.md and project-discovery.md (paths from project context above) to identify
the project's languages, frameworks, runtimes, subsystems, and bounded contexts. Each is a candidate top-level
hierarchy (e.g.,
auth,billing,api,worker,postgres,terraform). - Carry forward to Step 4: the discovered top-level prefixes (existing + candidate) and any second-level prefixes already in use under each.
- From existing filenames: If existing ADRs were enumerated, parse their filenames to extract the leading
hierarchy segments already in use (e.g.,
Step 3: Gather Context
- From the arguments and conversation, determine:
- Topic/title — What is the ADR about?
- Decision — What was decided and why?
- Alternatives — What other options were considered?
- Forcing function — What concrete trigger requires this decision now? Per ../../references/yagni-rule.md, an ADR requires evidence that the decision must be made today: an active engineering choice, a code path locking in, a regulation taking effect, a customer commitment, a documented incident driving the choice. If no forcing function exists, recommend deferring the ADR rather than writing it; surface the recommendation to the user with the trigger that would justify revisiting.
- If any of these are unclear or missing, use
AskUserQuestionto clarify before writing. If the forcing function is the unclear one, surface that explicitly — "I don't see a current trigger forcing this decision; recommend deferring the ADR until {trigger}. Override?"
Explore the Codebase
Skip agent exploration if the user has already provided full context (converting or updating). When creating a new ADR
with sparse context, launch 1-2 han-core:codebase-explorer agents to discover evidence. Use 1 agent for narrow
decisions, 2 when the decision crosses multiple system areas. Explorer 1 focuses on code affected by the decision topic
(current patterns, entry points, core logic). Explorer 2 focuses on existing ADRs, coding standards, and project docs
(starting from the docs directory found in Step 2).
Compile Evidence
After agents complete (or if skipped), merge findings with user-provided context. Agent discovery items map to Context (current state of the codebase), Decision (why the chosen option fits), and Notes (key files table, cross-references). Merge duplicates and resolve conflicts between agents.
Dispatch Architectural Review
Skip this sub-step in update mode when only status is changing. Otherwise, launch review agents in parallel against the compiled evidence, the proposed decision, and the considered alternatives. Pass each agent the topic, the proposed decision, the alternatives, and the evidence compiled above.
-
Launch architect agent — use
han-core:software-architectwhen the decision is scoped to a single codebase or bounded context (module boundaries, class and interface design, abstraction points, refactoring paths). Usehan-core:system-architectwhen the decision crosses service or bounded-context seams (integration patterns, data ownership across services, failure-domain topology, context-map relationships). If uncertain, preferhan-core:system-architect. Prompt: "Review the proposed decision against the compiled evidence. For the chosen option, identify structural or topological risks that the ADR's Consequences section should name. For each rejected alternative, identify the strongest case for it that the ADR's Decision section needs to rebut or concede. Return findings keyed to the ADR's Decision, Decision Drivers, and Consequences sections." -
Launch han-core:risk-analyst agent — prompt: "Assess the risk of adopting the chosen option versus staying with the current approach or adopting each rejected alternative. Score each on likelihood, severity, blast radius, and reversibility. Return findings keyed to the ADR's Consequences section, and flag any dimension where a rejected alternative scores better than the chosen option — the ADR needs to explain why."
-
Launch han-core:junior-developer agent in artifact-review mode — prompt: "Read the proposed Context, Decision, Decision Drivers, and Considered Options as a generalist encountering this decision for the first time. Surface: unexplained jargon, assumptions baked into the Decision Drivers without evidence, alternatives dismissed without a reason a generalist would accept, and places where the ADR relies on context a future reader will not have. Return a short list of clarifying questions and must-answer gaps."
Merge the three agents' findings into the Decision, Decision Drivers, and Consequences sections before writing. Where an agent raises a must-answer gap that requires user judgment, surface it with a recommended resolution rather than resolving silently.
Step 4: Write the ADR
-
Convert source document (if converting): Read the source document and map sections to ADR sections using the mapping at conversion-mapping.md.
-
Copy the template from template.md
-
File name and location:
{top-level}[-{second-level}]-{kebab-case-title}.md— a one- or two-level hierarchy prefix followed by the decision's specific title. The hierarchy must come from the taxonomy discovered in Step 2.6, never invented or hardcoded.- Top-level (required): the highest-level grouping the decision belongs to (e.g.,
auth,billing,api,postgres). Reuse an existing top-level prefix from Step 2.6 when one fits; only introduce a new top-level when no existing prefix applies, and prefer one that matches a subsystem, bounded context, or technology already named in CLAUDE.md or project-discovery.md. - Second-level (optional): add only when the top-level has — or will plausibly grow — multiple ADRs that benefit
from a sub-grouping (e.g.,
auth-tokens-…,auth-sessions-…). Reuse an existing second-level prefix from Step 2.6 when one fits. Skip the second level when the ADR is the only one (or one of a few) under its top-level. - Kebab-case-title (required): the specific decision, kebab-cased, distinct from the hierarchy prefix.
- If the discovered taxonomy offers more than one reasonable placement, ask the user to choose before writing.
- Place the file in the directory from Step 2.
- Top-level (required): the highest-level grouping the decision belongs to (e.g.,
-
Fill in metadata: Status per Step 1 mode (
proposedfor new,acceptedfor converted; usedeprecatedorsupersededwhen updating). Date Created / Last Updated: current date and time. -
Fill each required section following the template's HTML comments for guidance. Readability: invoke
han-communication:readability-guidanceto surface the shared readability standard into your context, then write the prose in each section against it — lead with the main point, give each paragraph one idea carried by its first sentence, number sequential steps and bullet non-sequential items, and disclose detail in layers. Keep the template's prescribed section structure (Context, Decision Drivers, Considered Options, Decision, Consequences, Notes); the rule governs the prose within them, and its descriptive-heading rule applies to any sub-headings you add, not the prescribed section names. -
Notes section must include:
- Key files table — important files related to this decision:
File Purpose path/to/fileDescription - Cross-references — links to related ADRs (e.g.,
See also [Soft Deletes](./data-soft-deletes.md)) - Related docs — links to related docs outside the ADR directory
- Key files table — important files related to this decision:
-
If updating an existing ADR: Update Status, Last Updated, and add notes about what changed. If superseding, cross-reference the new ADR and set the old ADR's status to
superseded. -
Handle source document (conversions only): If the source document is fully subsumed, delete it and update references in CLAUDE.md, AGENTS.md, and other markdown files. If it retains useful content, add a link to the new ADR and remove migrated sections.
Step 5: Integration
- Add a
Seereference in the relevant section of any existing CLAUDE.md or AGENTS.md, following the pattern of existing ADR references. Place it near the feature or component the ADR describes. - Search for related documentation (other ADRs, coding standards, feature docs) and add cross-references in the new ADR's Notes section.
- Add back-references from related docs where they add value.
- If converting (Step 4), confirm all old references to the source document are updated.
Step 6: Verification
Read back the ADR file and confirm:
- All metadata fields are filled (no
{placeholder}values remain) and template structure from template.md was followed - All required sections (Context, Decision Drivers, Considered Options, Decision, Consequences, Notes) have substantive content, and Notes includes a key files table with paths verified by Glob
- Cross-references in the ADR point to documents that exist
- Agent configuration file references (CLAUDE.md/AGENTS.md) correctly point to the new ADR
- If converting: source document was handled (deleted or updated with link)
- Fix any issues found
Step 7: Readability Self-Check
Run the standardized readability self-check (the shared standard is in your context from
han-communication:readability-guidance) over the ADR's prose regions only — never inside code fences, diagram bodies,
or citation identifiers. This skill runs no rewrite pass, so this self-check is the fidelity guard on the output; the
fidelity criterion is not optional. Confirm each criterion and fix any failure before presenting:
Run the readability rule's standardized self-check, which is already in your context from the readability-guidance
invocation above. Correct every failure before presenting. Its fidelity criterion is not optional: the standard governs
how the content is said, and drops a required fact only when the reader asked for less and losing it would not change
what they do next.
The descriptive-heading criterion applies to sub-headings you added, not to the section names the ADR template prescribes.
Project Context
- CLAUDE.md exists: !
find . -maxdepth 1 -name "CLAUDE.md" -type f - project-discovery.md: !
find . -maxdepth 3 -name "project-discovery.md" -type f - personal config directory: !
bash "${CLAUDE_PLUGIN_ROOT}/scripts/han-config-dir.sh" 2>/dev/null || echo "$HOME/.claude" - project .han/config.md: !
cat .han/config.md 2>/dev/null || echo ""
As your first action, use the Read tool on .han/config.md inside the personal config directory path above. A read
that returns no file is no personal configuration: continue silently. When that file or the project .han/config.md
probe supplies content, apply it per config-rule.md, which governs precedence
between the two files, relative-path resolution, and what to do with a file that reads but cannot be used.
Project Documentation
Readability. As you write the documentation, source the standard by invoking
han-communication:readability-guidance and apply it. The output is a committed file, so the standard applies at
generation time. Hold a named audience above the default: a technically-literate reader who needs to understand the
feature's behavior before reading or modifying its code. Scope that frame per section so the technical specifics the
reader needs are not simplified away.
Step 1: Evaluate and Gather Context
Guard check: If the request is about an architectural decision, suggest architectural-decision-record instead.
If it's about a coding convention, suggest coding-standard instead. Proceed only after confirming this is project
documentation.
Docs directory: Resolve project config: read CLAUDE.md's ## Project Discovery section for docs directory and
language; fall back to project-discovery.md; fall back to Glob default (docs/). Use the found docs directory with Glob
to enumerate existing .md files. If no docs directory was found, create docs/. The found language informs code fence
language identifiers in Step 3.
Resolve target files: Derive the filename in kebab-case: docs/{feature-name}.md. Use Glob to check if the file
already exists (docs/{feature-name}*.md). If it exists, use AskUserQuestion to ask: update the existing document, or
create with a different name? If not, it will be created.
Topic context: Use the arguments and conversation context to understand the topic and scope. If unclear, use
AskUserQuestion to clarify.
Flag content audit need: Determine whether the Content Audit (Step 6) will be needed. It is needed when updating an existing doc, migrating content from CLAUDE.md, or restructuring content from any other source. It is not needed only when creating documentation for a feature with no prior documentation of any kind.
Step 2: Explore the Codebase
Launch 2-3 han-core:codebase-explorer agents in parallel with the feature name, scope, and any known file paths.
Include the docs directory from Step 1 so agents can discover existing documentation. Each agent should explore from a
different angle (e.g., entry points and core logic; data models and configuration; tests and existing docs).
After all agents complete, merge their findings into a unified discovery summary — a numbered list (D1, D2, D3, ...) that combines all items, deduplicates files found by multiple agents, and resolves any conflicting findings.
Step 3: Write the Documentation
Use the template at template.md as the structural guide. The template's HTML comments explain when to include each section and what to cover.
Readability. Invoke han-communication:readability-guidance to surface the shared readability standard into your
context, then draft into the template so the structure carries that standard: main point first, descriptive headings,
one idea per paragraph with the first sentence carrying it, numbered lists for steps and bullets for non-sequential
items, and progressive disclosure that reveals the core before the detail.
File location: docs/{feature-name}.md (in the directory determined in Step 1)
Writing rules:
Lead with behavior. These rules make the doc an overview first and a reference second:
- Lead with behavior. Write the Summary, How It Works, and Primary Flows in plain language before any reference section. Describe what the feature does and what happens when it runs, in functional terms. Name files and types only where it aids understanding.
- Summary is prose plus bullets. Open the Summary with a 2-4 sentence plain-language paragraph for a reader who has not seen the code, then the scannable bullets. The paragraph carries no code, type names, or paths.
- Primary Flows narrate the main paths. Cover the 1-3 flows that matter, not every branch. Name the actor or trigger, give numbered plain-language steps (what happens and why, not which function is called), state the outcome, and narrate the main failure path.
- Reference is supporting detail. Place schema, core types, constants, implementation notes, API bodies, and
component listings under the
## Technical Referenceregion, below the behavioral spine. Treat them as lookup material, not the document's main body.
Apply to every section:
- Absolute file paths from repo root (e.g.,
src/services/auth.ts, not./auth.ts). - Prefer pointers over long code. In Technical Reference, point to the file and function and include a short illustrative snippet only where the source is non-obvious. Do not reproduce long (10-30 line) source blocks; link to the source instead.
- Code fence language identifiers must match the project's actual languages (from Step 1).
- Document constants and magic numbers with their actual values in the Constants table.
- Skip CONDITIONAL sections from the template that don't apply. Don't include empty sections.
- One plain-language description in the title area summarizing what the feature does.
- Separate backend and frontend content. Use
### Backend/### Frontendsub-headings for cross-cutting features; skip sub-headings for single-layer features. - Diagrams are Mermaid, not ASCII. Render the Architecture diagram, any Primary Flow diagram, and the Component
Hierarchy as Mermaid in a
```mermaidfence —flowchartfor structure and trees,sequenceDiagramfor actor-to-system exchanges. Label nodes with parts a reader recognizes and label edges with what passes between them. Keep each diagram to the parts that matter; a reader should grasp the shape at a glance.
Updating existing documents: Read the entire existing document first and note all content sources (existing doc, content migrated from CLAUDE.md or other files, any other inputs). Preserve the existing structure; don't reorganize unless requested. Identify sections needing changes based on Step 2 exploration. Add new sections where the template suggests them. If the existing doc has no plain-language behavioral layer (no Summary, How It Works, or Primary Flows), add those sections at the top so the updated doc leads with behavior. Flag removals as provisional for the Content Audit (Step 6). Update code examples to match current source and update cross-references in both directions.
Metadata: Fill in Last Updated (current date/time).
Step 4: Update Agent Configuration Files
- Read the agent configuration file (
CLAUDE.md,AGENTS.md, or equivalent) to understand its existing structure and patterns - Add a reference following the existing pattern, e.g.:
- See [/docs/{feature-name}.md](/docs/{feature-name}.md) for {brief description}. - Place it in the section most relevant to the feature, following the file's existing organization
Step 5: Cross-Reference
- Grep the feature name across all documentation files found in the project
- Add cross-references in the new doc's Related Documentation section
- Add a reference back from related docs to the new doc where it adds value
- Ensure bidirectional linking — if doc A references doc B, doc B should reference doc A
Step 6: Content Audit
Check the flag set in Step 1. If the Content Audit is not needed, skip to Step 7.
Identify every source of pre-existing content that fed into this task (previous doc version, CLAUDE.md content replaced
with summary links, content migrated from other files). Re-read each source's original content from before your changes.
Launch a han-core:content-auditor agent with the path to the new/updated document and the list of all source content
(file paths and descriptions). The agent classifies each fact as Present, Correctly Removed, or Missing.
For each item classified as Missing, add the content back to the appropriate section, adapting wording to fit the new document's style while preserving factual content. Use the agent's suggested wording and placement as guidance.
Present the audit summary to the user: number of facts checked, number present, number correctly removed, and number missing (and restored).
Step 7: Information-Architecture Review
Dispatch an han-core:information-architect agent against the written/updated doc before final verification. Pass it
the document path, the docs directory root, and the intended audience (a developer or technically-literate stakeholder
who needs to understand the feature's behavior before reading its code, and who may later modify it).
Prompt: "Audit the feature doc at {doc_path} for findability, orientation, and comprehension. The intended audience is a
developer or technically-literate stakeholder who needs to understand the feature's behavior before reading its code,
and who may later modify it. Check: (1) Does a plain-language Summary and a How It Works and Primary Flows narration
appear before any code, schema, or type reference? If the behavioral content is missing or sits below the reference
detail, that is a finding. (2) Does the heading list let a scanning reader see where the functional overview ends and
the deep ## Technical Reference begins? (3) Is the Summary a short prose paragraph plus bullets, oriented at the right
audience, and does the title + one-sentence description match what a reader scanning {docs_directory} would expect to
find here? (4) Are Configuration and Error Handling scannable and placed ahead of the raw reference detail? (5) Does the
Related Documentation section lead the reader to the next useful artifact, or dead-end them? Return a list of structural
edits. Do not return an empty list unless the document leads with behavior and defers code reference."
Apply every actionable edit the agent returns. For findings that require a judgment only the author can make (scope, audience ambiguity), surface them to the user with a recommended resolution; do not silently resolve.
Step 8: Readability Rewrite
Dispatch the han-communication:readability-editor agent in a single Agent call to audit and rewrite the settled doc
against the readability standard, preserving every fact. Pass it the document path and the named audience: a
technically-literate reader who needs to understand the feature's behavior before reading or modifying its code; the
editor reads han-communication's own canonical rule, so pass no rule path. The agent rewrites prose regions only —
never inside code fences, diagram bodies (for example the body of a Mermaid chart), or rendered markup. Apply its
rewrite to the document.
Step 9: Readability Self-Check
Run the standardized readability self-check (the shared standard is in your context from
han-communication:readability-guidance) over the document's prose regions only — never inside code fences, diagram
bodies, or rendered markup. Confirm each criterion and fix any failure before finalizing:
Run the readability rule's standardized self-check, which is already in your context from the readability-guidance
invocation above. Correct every failure before presenting. Its fidelity criterion is not optional: the standard governs
how the content is said, and drops a required fact only when the reader asked for less and losing it would not change
what they do next.
The standard applies at generation time; a later manual edit of the committed file is not re-checked.
Step 10: Verification
- Documentation file: Follows template structure and leads with behavior (Summary, How It Works, Primary Flows
appear before the
## Technical Referenceregion), no{placeholder}values remain, absolute file paths, reference code is short snippets or file pointers rather than long source blocks, no empty CONDITIONAL sections, Mermaid diagrams are syntactically valid (open with```mermaid, declare a diagram type, and parse) - Agent config file: Reference correctly formatted, link path valid, placed in right section
- Cross-references: Links point to real files, related docs link back to new doc
- IA review applied: Step 7 edits were applied, or any skipped edits were surfaced to the user
Create or Update Runbook
Operating Principles
- YAGNI applies to runbooks themselves. Apply the evidence-based YAGNI rule from ../../references/yagni-rule.md. A runbook is worth writing only when the scenario is grounded in something real: an alert that has actually fired, a documented incident, a recurring task that exists, or a known failure mode on a service that receives production traffic. Runbooks for hypothetical alerts, "best practice says we should have one," or "we'll need this someday" are YAGNI candidates and the runbook should be deferred until the scenario actually occurs. The canonical anti-pattern from project history: Sentry runbooks for staging-only Sentry where data isn't reaching production — alerts that will never fire because no signal flows. The user always wins; the rule's job is to make the cost of speculative runbooks visible.
- The companion evidence rule applies to the runbook's supporting evidence. Apply the evidence rule from ../../references/evidence-rule.md to the citations that ground the scenario: name the trust class of each piece of evidence (alert history, incident report, on-call rotation pattern); cite the actual artifact (dashboard URL, ticket ID, log query) rather than paraphrased recollection; and surface single-source claims as such rather than presenting them as settled.
- One runbook per invocation. The skill produces a single runbook file. Multi-runbook batches conflate scope; rerun the skill per scenario.
- Imperative commands with expected output. The template requires every step to show the exact command and what success looks like. Prose paragraphs in place of commands are an authoring failure the skill prompts against.
- Staleness is the failure mode. The template requires owner, last-validated, last-edited, and a change-history entry so decay is visible rather than hidden. The skill does not enforce a review cadence — that is a team-level workflow concern — but the metadata fields make the cadence auditable.
- Readability standard. Source the standard by invoking
han-communication:readability-guidanceand apply it as you write the runbook. Hold its default audience frame: a capable reader who did not do this work and lacks the author's context — here, the operator following the runbook during an incident.
Project Context
- Git user: !
git config user.name || echo unset(!git config user.email || echo unset) - OS username: !
whoami - Today's date: !
date +%Y-%m-%d - CLAUDE.md: !
find . -maxdepth 1 -name "CLAUDE.md" -type f - project-discovery.md: !
find . -maxdepth 3 -name "project-discovery.md" -type f - personal config directory: !
bash "${CLAUDE_PLUGIN_ROOT}/scripts/han-config-dir.sh" 2>/dev/null || echo "$HOME/.claude" - project .han/config.md: !
cat .han/config.md 2>/dev/null || echo ""
As your first action, use the Read tool on .han/config.md inside the personal config directory path above. A read
that returns no file is no personal configuration: continue silently. When that file or the project .han/config.md
probe supplies content, apply it per config-rule.md, which governs precedence
between the two files, relative-path resolution, and what to do with a file that reads but cannot be used.
Step 1: Determine Mode
Determine which mode to operate in based on the user's request:
| Mode | When | Then |
|---|---|---|
| Creating new | Drafting a runbook for a scenario the project does not yet have one for | → Step 2 |
| Updating existing | Modifying an existing runbook (new step, validation date refresh, escalation change) | Read the existing runbook → Step 4 |
| Validating existing | User says they ran the procedure end-to-end and wants to refresh Last validated and add a change-history entry | Read the existing runbook → Step 4 (update mode, validation entry only) |
Step 2: Apply the YAGNI Preflight
Before discovering structure or gathering context, gate the work. Ask the user (or confirm from their request) which of the following describes the scenario:
- An alert that has actually fired — name the alert, link the firing incident or alert manager record.
- A documented incident or post-mortem — link it.
- A recurring scheduled task that the team performs (weekly index rebuild, monthly cert rotation, etc.) — name the cadence and where the schedule lives.
- A live failure mode on a service that receives production traffic, where the failure has occurred or is expected to occur with current measured pressure — name the service and the failure mode.
- Customer report or stakeholder commitment requiring this procedure to be documented now — link it.
If none of these applies, recommend deferring the runbook. Surface the recommendation to the user with the trigger that would justify revisiting:
"I don't see a current trigger forcing this runbook. Per the project's YAGNI rule, runbooks for alerts that have never fired are an anti-pattern. Recommend deferring until {trigger — first alert fires, first occurrence of the failure mode, first run of the recurring task, customer commitment lands}. Override and proceed anyway?"
The user always wins. If they override, record the override in the runbook's Origin field as
"override: written preventively at user request on {date} — {reason}" so future readers can see the runbook was
written without standard evidence.
If the scenario does pass the preflight, capture the evidence — the user will be asked again at Step 4 to drop the link
or reference into the runbook's Origin metadata field.
Step 3: Discover Project Structure
-
Resolve project config. Read CLAUDE.md's
## Project Discoverysection for documented runbook and docs directories. Fall back toproject-discovery.md. Fall back to Glob defaults (docs/runbooks/,runbooks/,docs/). Continue without any keys that remain unfound. -
Determine the runbooks directory. Use the runbooks directory if found; otherwise use
{docs-dir}/runbooks/if a docs directory was found; otherwise default todocs/runbooks/. Runmkdir -pon the resolved directory to ensure it exists. -
Enumerate existing runbooks. Use Glob to find existing
.mdfiles in the runbooks directory and any service subdirectories. Read filenames to detect whether the project organizes runbooks flat (docs/runbooks/{scenario}.md), per-service (docs/runbooks/{service}/{scenario}.md), or alert-keyed (docs/runbooks/alerts/{AlertName}.md). -
Resolve author information. If git user or email is empty or reads
unsetin the project context above, ask the user for their name and email. -
Check existing runbook format. If existing runbooks were found, read one to understand the project's format. If it differs from runbook-template.md, ask the user whether to match the existing format or use this skill's template. Default to matching the existing format when the project already has more than two runbooks — consistency is the larger value.
Step 4: Gather Context
From the arguments, conversation, and YAGNI preflight in Step 2, capture:
- Title — the symptom-first title per the template's title rule. Lead with the observable failure or operation, not
the system name. Good:
Postgres primary unreachable: connections time out. Bad:Database failover. - Severity — the org's severity scheme. If the alert uses a different name (P1/P2), record both.
- Triggers — the alert name (with link to alert definition or monitoring), the schedule, the upstream runbook, or "manual".
- Reversibility — yes, partial, no — wait it out, no — data loss possible. This sets the front-door signal so the engineer knows before they commit whether they can back out.
- Origin — the link or reference captured in Step 2. Required.
- Owner — team or person paged at 2am for this runbook's freshness.
- Prerequisites — access groups, VPN, kubectl context, CLI tools with minimum versions, on-call privileges. "None — workstation only" is a valid answer; blank is not.
- Symptoms — what the engineer sees that brings them to this runbook.
- The procedure — for each step, the exact command (or non-command action), what success looks like, and what to do if the output differs. Use imperative voice.
- Verification — how to confirm the original symptom is gone (separate from per-step expected output).
- Escalation — for each escalation step, the condition (time-box or specific failure), the recipient, and the channel (PagerDuty service, Slack room, phone).
- Rollback — how to undo the fix, or the explicit alternative if rollback is not possible.
If any of these are unclear, use AskUserQuestion to clarify before writing. Ask only for what is genuinely missing; do
not re-ask for values present in the user's request.
When the user gives you a recent incident, post-mortem, or alert as the scenario, read it to extract the symptoms, the procedure that worked, and the verification — do not re-derive these from the model's understanding.
Step 5: Write the Runbook
-
Copy the template from runbook-template.md.
-
File name and location. Place the file in the runbooks directory from Step 3.
- Slug: kebab-case, lead with the scenario or symptom, not the system name.
postgres-primary-unreachable.md, notfailover.md. - Per-service subdirectory: when the project already organizes runbooks per-service (detected in Step 3), place
the file under the matching service directory:
docs/runbooks/{service}/{scenario}.md. Reuse an existing service directory when one fits; only introduce a new service directory when no existing one applies. - Alert-keyed: when the project organizes by alert name (detected in Step 3), use the alert name as the file
name:
docs/runbooks/alerts/{AlertName}.md. - Flat default: when the project has no convention yet, place the file at
docs/runbooks/{slug}.md. - If the project has more than one reasonable placement, ask the user before writing.
- Slug: kebab-case, lead with the scenario or symptom, not the system name.
-
Fill the metadata block with Severity, Triggers, Reversible, Last validated (today's date and the validating party — if the procedure has not been run end-to-end, leave
Last validatedempty and note in change history that it has not yet been validated), Last edited (today's date), Owner, and Origin (from the YAGNI preflight in Step 2). -
Fill each required section following the template's HTML comments for guidance:
- Symptoms — what the engineer sees.
- Prerequisites — required access and tools. Write "None — workstation only" if nothing is required; do not leave blank.
- Resolve — numbered steps with exact commands and expected output. One logical action per step.
- Verify the fix landed — concrete checks that the original symptom is gone.
- Escalate — condition → recipient → channel.
- Rollback — steps to undo, or explicit "Not applicable — {reason and alternative}".
- Live links — operational surfaces used during the incident.
- Change history — start with the creation entry citing the Origin reference.
-
Fill applicable optional sections and delete the headings for any optional section that does not apply. The optional sections are: Likely cause, Not this — try instead, Background, Quick fix, If a step fails, If the problem comes back, What didn't work and why, Background and related. An empty heading reads as "this runbook is incomplete" — delete rather than leave blank.
-
Delete the author guidance comment block at the top of the template once the file is filled in.
-
Readability. Invoke
han-communication:readability-guidanceto surface the shared readability standard into your context, then as you write the prose regions apply it: lead each section with its main point, use descriptive headings, keep one idea per paragraph with the first sentence carrying it, number the procedure's steps and bullet non-sequential items, and reveal detail in layers. Do not duplicate the rule text. A runbook's procedures are already numbered steps, which aligns with the rule. -
If updating an existing runbook: edit the existing file in place. Append a new change-history entry on top with the date, your name, what changed and why, and the validation status. Update
Last editedto today; updateLast validatedonly if you actually ran the procedure end-to-end against production or a faithful staging environment.
Step 6: Integration
- If the project's CLAUDE.md or AGENTS.md has a section that lists runbooks (or that references operational documentation by name), add a one-line entry pointing to the new runbook. Follow the pattern of existing entries; do not invent a new convention.
- If the runbook closes a procedure documented in an incident report, post-mortem, or related ADR, add a cross-reference from that document back to the runbook.
- If the runbook's
Triggersfield names an alert that has a definition file in the repository (Prometheus rule, monitoring-as-code config), add a comment in the alert definition pointing to the runbook path.
Step 7: Verification
Read back the runbook file and confirm:
- All metadata fields are filled — no
{placeholder}values remain in Severity, Triggers, Reversible, Owner, Origin.Last validatedis either a real date with the validating party or explicitly noted as not yet validated in change history. - The Origin field contains a real link or reference per the YAGNI preflight. If the user overrode the preflight, the override is recorded explicitly.
- The Symptoms section is concrete (alert text, error message, log line, or user-visible behavior) rather than generic prose.
- Every step in Resolve has either an exact command with expected output, or a non-command action with the equivalent "what success looks like" signal.
- Verify the fix landed lists at least one concrete check that the original symptom is gone, distinct from per-step expected output.
- Escalate entries lead with a condition (when), then the recipient, then the channel.
- Rollback is either filled with steps or explicitly marked not applicable with an alternative.
- Optional sections that do not apply have been deleted entirely — no empty headings remain.
- The author guidance comment block at the top of the template has been removed.
- Change history has at least one entry — the creation entry citing Origin.
Fix any issues found before presenting the runbook to the user.
Step 8: Readability Self-Check
Run the standardized readability self-check (the shared standard is in your context from
han-communication:readability-guidance) over the runbook's prose regions only — never inside code fences, command
blocks, diagram bodies, or citation identifiers. This skill runs no rewrite pass, so this self-check is the fidelity
guard on the output; the fidelity criterion is not optional. Confirm each criterion and fix any failure before
presenting:
Run the readability rule's standardized self-check, which is already in your context from the readability-guidance
invocation above. Correct every failure before presenting. Its fidelity criterion is not optional: the standard governs
how the content is said, and drops a required fact only when the reader asked for less and losing it would not change
what they do next.
Sponsors
Details
- Marketplace
- testdouble/han
- Source
- han-documentation
- Category
- Community