borghei/Claude-Skills / engineering/runbook-generator
runbook-generator
VerifiedDrafts, validates and ages operational runbooks (deploy, incident, database, scaling, monitoring) with stack-specific commands, VERIFY steps and rollback. Use when bootstrapping ops docs, preparing on-call, or after an incident.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 7.2 KB |
| assets/flawed_runbook.md | markdown | 253 B |
| assets/sample_service.json | config | 650 B |
| references/quality-and-troubleshooting.md | markdown | 4.1 KB |
| references/runbook-templates.md | markdown | 8.3 KB |
| references/staleness-and-maintenance.md | markdown | 1.5 KB |
| scripts/runbook_scaffolder.pyexecutable | script | 15.9 KB |
| scripts/runbook_validator.pyexecutable | script | 14.4 KB |
| scripts/staleness_checker.pyexecutable | script | 13.3 KB |
scripts/staleness_checker.py
View on GitHub#!/usr/bin/env python3
"""Staleness Checker — Check runbook freshness against configurable thresholds.
Inspects runbook markdown files for their "Last verified" date and compares
it against configurable staleness thresholds. Also checks whether referenced
config files have been modified more recently than the runbook verification
date. Designed for CI integration to catch stale runbooks before they cause
incident response failures.
Usage:
python staleness_checker.py docs/runbooks/
python staleness_checker.py runbook.md --threshold 30
python staleness_checker.py docs/runbooks/ --repo-root /path/to/repo
python staleness_checker.py docs/runbooks/ --json
python staleness_checker.py docs/runbooks/ --config staleness.json
"""
import argparse
import json
import os
import re
import subprocess
import sys
import textwrap
from datetime import date, datetime, timedelta
from pathlib import Path
AS_OF = None # set by --as-of; None means today
DEFAULT_THRESHOLDS = {
"stale_days": 90,
"warning_days": 60,
"critical_days": 180,
}
CONFIG_FILE_PATTERN = re.compile(
r"git\s+log\s+.*?--\s+(\S+)|"
r"(?:config|file|path)[:=]\s*[`\"]?([a-zA-Z0-9_./-]+\.[a-zA-Z]+)[`\"]?"
)
LAST_VERIFIED_PATTERN = re.compile(
r"(?i)(?:\*\*)?last\s+verified(?:\*\*)?[:]\s*(\d{4}-\d{2}-\d{2})"
)
LAST_UPDATED_PATTERN = re.compile(
r"(?i)(?:\*\*)?(?:last\s+updated|updated|date)(?:\*\*)?[:]\s*(\d{4}-\d{2}-\d{2})"
)
def parse_date(date_str):
"""Parse a YYYY-MM-DD date string."""
try:
return datetime.strptime(date_str, "%Y-%m-%d").date()
except (ValueError, TypeError):
return None
def extract_verified_date(content):
"""Extract the 'Last verified' or 'Last updated' date from runbook content."""
match = LAST_VERIFIED_PATTERN.search(content)
if match:
return parse_date(match.group(1))
match = LAST_UPDATED_PATTERN.search(content)
if match:
return parse_date(match.group(1))
return None
def extract_referenced_configs(content):
"""Extract config file paths referenced in the runbook."""
configs = set()
for match in CONFIG_FILE_PATTERN.finditer(content):
path = match.group(1) or match.group(2)
if path:
path = path.strip("`\"'")
# Filter out obvious non-file-paths
if "." in path and not path.startswith("http") and len(path) < 200:
configs.add(path)
return sorted(configs)
def get_file_modified_date(filepath):
"""Get the last modification date of a file from the filesystem."""
try:
mtime = os.path.getmtime(filepath)
return datetime.fromtimestamp(mtime).date()
except (OSError, FileNotFoundError):
return None
def get_git_modified_date(filepath, repo_root=None):
"""Get the last modification date of a file from git history."""
try:
cwd = repo_root if repo_root else os.path.dirname(filepath) or "."
result = subprocess.run(
["git", "log", "-1", "--format=%ci", "--", filepath],
capture_output=True,
text=True,
cwd=cwd,
timeout=10,
)
if result.returncode == 0 and result.stdout.strip():
date_str = result.stdout.strip().split(" ")[0]
return parse_date(date_str)
except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
pass
return None
def classify_staleness(days_since, thresholds):
"""Classify the staleness level based on days since last verification."""
if days_since >= thresholds["critical_days"]:
return "critical"
if days_since >= thresholds["stale_days"]:
return "stale"
if days_since >= thresholds["warning_days"]:
return "warning"
return "fresh"
def check_config_drift(content, repo_root, verified_date):
"""Check if any referenced config files were modified after verification."""
drifted = []
configs = extract_referenced_configs(content)
for config_path in configs:
full_path = os.path.join(repo_root, config_path) if repo_root else config_path
mod_date = get_git_modified_date(config_path, repo_root)
if mod_date is None:
mod_date = get_file_modified_date(full_path)
if mod_date is None:
continue
if verified_date and mod_date > verified_date:
drifted.append({
"config_file": config_path,
"modified_date": mod_date.isoformat(),
"verified_date": verified_date.isoformat(),
"drift_days": (mod_date - verified_date).days,
})
return drifted
def check_runbook_staleness(filepath, thresholds, repo_root=None, today=None):
"""Check staleness of a single runbook file."""
if today is None:
today = AS_OF or date.today()
filepath = str(filepath)
result = {
"file": filepath,
"verified_date": None,
"days_since_verified": None,
"status": "unknown",
"config_drift": [],
"issues": [],
}
try:
with open(filepath, "r") as f:
content = f.read()
except FileNotFoundError:
result["status"] = "error"
result["issues"].append(f"File not found: {filepath}")
return result
if not content.strip():
result["status"] = "error"
result["issues"].append("Runbook file is empty")
return result
verified_date = extract_verified_date(content)
if verified_date is None:
result["status"] = "unknown"
result["issues"].append(
"No 'Last verified' or 'Last updated' date found. "
"Add '**Last verified:** YYYY-MM-DD' to the runbook header."
)
# Fall back to git modification date of the runbook itself
git_date = get_git_modified_date(filepath, repo_root)
fs_date = get_file_modified_date(filepath)
fallback = git_date or fs_date
if fallback:
verified_date = fallback
result["issues"].append(
f"Using file modification date as fallback: {fallback.isoformat()}"
)
if verified_date:
result["verified_date"] = verified_date.isoformat()
days = (today - verified_date).days
result["days_since_verified"] = days
result["status"] = classify_staleness(days, thresholds)
if result["status"] in ("stale", "critical"):
result["issues"].append(
f"Runbook was last verified {days} days ago ({verified_date.isoformat()}). "
f"Threshold: {thresholds['stale_days']} days."
)
# Check config drift
effective_root = repo_root or os.path.dirname(os.path.abspath(filepath))
drift = check_config_drift(content, effective_root, verified_date)
result["config_drift"] = drift
for d in drift:
result["issues"].append(
f"Config drift: {d['config_file']} was modified {d['drift_days']} days "
f"after the runbook was last verified (modified: {d['modified_date']}, "
f"verified: {d['verified_date']})"
)
if result["status"] == "fresh":
result["status"] = "drift"
return result
def load_config(config_path):
"""Load threshold configuration from a JSON file."""
try:
with open(config_path, "r") as f:
data = json.load(f)
thresholds = dict(DEFAULT_THRESHOLDS)
for key in DEFAULT_THRESHOLDS:
if key in data:
thresholds[key] = int(data[key])
return thresholds
except (json.JSONDecodeError, FileNotFoundError, ValueError) as e:
print(f"Error loading config: {e}", file=sys.stderr)
sys.exit(2)
def format_human_output(results, thresholds):
"""Format staleness results for human consumption."""
lines = []
lines.append(f"Staleness Checker Report — {(AS_OF or date.today()).isoformat()}")
lines.append(f"Thresholds: warning={thresholds['warning_days']}d, "
f"stale={thresholds['stale_days']}d, "
f"critical={thresholds['critical_days']}d")
lines.append("")
status_counts = {"fresh": 0, "warning": 0, "stale": 0, "critical": 0,
"drift": 0, "unknown": 0, "error": 0}
for result in results:
status = result["status"]
status_counts[status] = status_counts.get(status, 0) + 1
icon_map = {
"fresh": "OK ",
"warning": "WARN ",
"stale": "STALE",
"critical": "CRIT ",
"drift": "DRIFT",
"unknown": "?????",
"error": "ERROR",
}
icon = icon_map.get(status, "?????")
lines.append(f" [{icon}] {result['file']}")
if result["verified_date"]:
days = result["days_since_verified"]
lines.append(f" Last verified: {result['verified_date']} ({days} days ago)")
for issue in result["issues"]:
lines.append(f" - {issue}")
if result["config_drift"]:
lines.append(f" Config drift detected in {len(result['config_drift'])} file(s)")
lines.append("")
lines.append("=" * 60)
lines.append("SUMMARY")
lines.append(f" Files checked: {len(results)}")
for status, count in sorted(status_counts.items()):
if count > 0:
lines.append(f" {status.upper():>10}: {count}")
lines.append("=" * 60)
stale_count = status_counts["stale"] + status_counts["critical"]
if stale_count > 0:
lines.append(f"\n{stale_count} runbook(s) need review.")
elif status_counts["drift"] > 0:
lines.append(f"\n{status_counts['drift']} runbook(s) have config drift.")
else:
lines.append("\nAll runbooks are up to date.")
return "\n".join(lines)
def main():
parser = argparse.ArgumentParser(
description="Check runbook freshness against configurable staleness thresholds.",
formatter_class=argparse.RawDescriptionHelpFormatter,
epilog=textwrap.dedent("""\
Status levels:
fresh — verified within the warning threshold
warning — approaching staleness (default: 60+ days)
stale — exceeds staleness threshold (default: 90+ days)
critical — severely stale (default: 180+ days)
drift — referenced config files changed after verification
unknown — no verification date found in runbook
error — file not found or empty
Config file format (JSON):
{
"warning_days": 60,
"stale_days": 90,
"critical_days": 180
}
Exit codes:
0 = all runbooks fresh or warning-level
1 = one or more stale or critical runbooks
2 = input error
"""),
)
parser.add_argument("paths", nargs="*", help="Runbook files or directories to check")
parser.add_argument("--threshold", "-t", type=int, default=None,
help=f"Staleness threshold in days (default: {DEFAULT_THRESHOLDS['stale_days']})")
parser.add_argument("--warning", "-w", type=int, default=None,
help=f"Warning threshold in days (default: {DEFAULT_THRESHOLDS['warning_days']})")
parser.add_argument("--critical", type=int, default=None,
help=f"Critical threshold in days (default: {DEFAULT_THRESHOLDS['critical_days']})")
parser.add_argument("--config", "-c", help="Path to JSON config file with thresholds")
parser.add_argument("--repo-root", "-r", help="Repository root for resolving config file paths")
parser.add_argument("--json", action="store_true", help="Output results as JSON")
parser.add_argument("--as-of", help="Measure age from this date (YYYY-MM-DD) instead of today")
args = parser.parse_args()
global AS_OF
if args.as_of:
AS_OF = parse_date(args.as_of)
if AS_OF is None:
print(f"Error: --as-of must be YYYY-MM-DD, got {args.as_of!r}", file=sys.stderr)
sys.exit(2)
if not args.paths:
parser.print_help()
print("\nError: No paths specified.", file=sys.stderr)
sys.exit(2)
# Build thresholds
if args.config:
thresholds = load_config(args.config)
else:
thresholds = dict(DEFAULT_THRESHOLDS)
if args.threshold is not None:
thresholds["stale_days"] = args.threshold
if args.warning is not None:
thresholds["warning_days"] = args.warning
if args.critical is not None:
thresholds["critical_days"] = args.critical
# Collect files
files = []
for path_str in args.paths:
p = Path(path_str)
if p.is_dir():
files.extend(sorted(p.glob("**/*.md")))
elif p.is_file():
files.append(p)
else:
print(f"Error: Path not found — {path_str}", file=sys.stderr)
sys.exit(2)
if not files:
print("Error: No markdown files found.", file=sys.stderr)
sys.exit(2)
# Check each file
results = [
check_runbook_staleness(f, thresholds, repo_root=args.repo_root)
for f in files
]
# Output
if args.json:
print(json.dumps(results, indent=2))
else:
print(format_human_output(results, thresholds))
# Exit code
has_stale = any(r["status"] in ("stale", "critical") for r in results)
sys.exit(1 if has_stale else 0)
if __name__ == "__main__":
main()
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |