Documentation/Jutsu/Runbooks
🎯

Runbooks

v1.2.0

Structured operational documentation and runbook patterns for human operators. Helps create clear, actionable runbooks for troubleshooting, incident response, and maintenance.

jutsuskillhookrunbooksoperationsdocumentationtroubleshootingincident-responsemaintenanceon-calloperational-procedures

Installation

Install han binary (required for hooks to work):

curl -fsSL https://han.guru/install.sh | bash

Then install this plugin:

han plugin install jutsu-runbooks

Overview

Structured operational documentation and runbook patterns for human operators. This plugin helps create clear, actionable runbooks for troubleshooting, incident response, and maintenance tasks.

Features

  • Runbook Structure - Templates and organization patterns for operational documentation
  • Troubleshooting Guides - Systematic debugging procedures and decision trees
  • Incident Response - Incident management, severity levels, and on-call playbooks
  • Quality Enforcement - Automated markdown linting for documentation consistency

Installation

han plugin install jutsu-runbooks

Or install via Claude Code:

/plugin install bushido@han/jutsu/jutsu-runbooks

What This Plugin Provides

Skills

  • runbook-structure - Creating structured operational runbooks with comprehensive templates, directory organization, and best practices for emergency response, routine maintenance, and knowledge transfer
  • troubleshooting-guides - Building effective troubleshooting procedures using the 5-step method (Observe, Hypothesize, Test, Fix, Verify) with decision trees and layered diagnostics
  • incident-response - Handling production incidents with severity classifications (SEV-1 through SEV-4), communication protocols, post-mortems, and on-call procedures

Validation Hooks

Automatically validates runbook documentation quality:

  • validate - Runs markdownlint-cli on all runbook markdown files to ensure documentation consistency

Use Cases

This plugin is ideal for:

  • Creating operational runbooks for production systems
  • Building troubleshooting guides for common issues
  • Documenting incident response procedures
  • Writing on-call playbooks and escalation guides
  • Maintaining structured operational knowledge

Runbook vs SOP

Runbooks (this plugin) are for human operators:

  • Step-by-step procedures for troubleshooting
  • Incident response protocols
  • On-call guides with decision trees
  • Maintenance checklists

SOPs (jutsu-sop) are for AI agents:

  • Workflow definitions for agent execution
  • Automated task sequences
  • Agent behavior specifications

Example Usage

Ask Claude to help create operational documentation:

Create a runbook for handling database connection failures in production

Write a troubleshooting guide for slow API responses with decision trees

Build an incident response template for our microservices architecture

Directory Structure

This plugin encourages organizing runbooks in a structured directory:

runbooks/
├── README.md                 # Index of all runbooks
├── services/
│   ├── api-gateway/
│   │   ├── high-latency.md
│   │   └── connection-errors.md
│   └── database/
│       └── slow-queries.md
├── infrastructure/
│   └── kubernetes/
│       └── pod-restart.md
└── on-call/
    ├── first-responder.md
    └── escalation-guide.md

Dependencies

  • bushido - Core quality principles (automatically installed)

Related Plugins

  • jutsu-sop - Standard operating procedures for AI agent workflows
  • jutsu-markdown - Markdown syntax and formatting skills

License

MIT

Skills

📖

runbooks-incident-response

Use when creating incident response procedures and on-call playbooks. Covers incident management, communication protocols, and post-mortem documentation.

📖

runbooks-structure

Use when creating structured operational runbooks for human operators. Covers runbook organization, documentation patterns, and best practices for clear operational procedures.

📖

runbooks-troubleshooting-guides

Use when creating troubleshooting guides and diagnostic procedures for operational issues. Covers problem diagnosis, root cause analysis, and systematic debugging.

Hooks

⚠

Token Usage Notice

Hooks run automatically during Claude Code sessions and their output is sent to the model for processing. This may increase token usage and associated costs. Consider disabling hooks you don't need via han-config.yml.

🛑

Stop

Runs when the main Claude Code agent has finished responding. Can verify task completion, check quality gates, or ensure documentation requirements are met before the session ends.

🛑

SubagentStop

Runs when a Claude Code subagent (Task tool call) has finished responding. Can validate subagent outputs, enforce quality standards, or trigger additional workflows after delegated tasks complete.