AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

knowledge-ops

Use when writing, checking or cleaning up SOPs and runbooks. Generates them with sop_generator.py, checks 5W2H completeness and links with runbook_validator.py and ingests an existing knowledge base with kb_ingester.py.

Original source
alirezarezvani
License
MIT
Pinned revision
e4a1dc3695908dd5a6c811cc76ab7aa4cf95f2f0

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

This skill also requires local files or dependencies. Remote reading alone may not be enough.

Ask your assistant

Use Agentic Memory skills to read alirezarezvani--knowledge-ops at revision e4a1dc3695908dd5a6c811cc76ab7aa4cf95f2f0, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 6

assets/runbook_template.md

Runbook Template — fill out before running runbook_validator.py

Use this template to capture runbook steps before invoking the validator. Each step must specify all six required attributes (owner, duration, success signal, failure signal, rollback, escalation) or the validator will flag it.

Feed the JSON into:

python3 scripts/runbook_validator.py --input my-runbook.json
python3 scripts/runbook_validator.py --input my-runbook.md   # markdown also accepted

A runbook scoring < 60 is NOT-SAFE for production use. Aim for ≥ 80 (SAFE-TO-USE) before putting the runbook into rotation.


Runbook metadata

  • Runbook name: (e.g., Incident Comms Cascade, Customer Escalation, Vendor Outage Response, System-Access Revocation)
  • Owner: (named human or named on-call rotation — e.g., "Incident Commander on-call (PagerDuty: ic-primary)")
  • Trigger: (what specifically invokes this runbook — e.g., "PagerDuty Sev-1 incident triggered" or "Customer escalation flagged in Salesforce")
  • Expected total duration: (P50 + P90 wall-clock from trigger to completion)
  • Linked SOP: (if this runbook implements an SOP, link the canonical SOP page)

Step table

| # | Step title | Owner | Duration | Success signal (observable) | Failure signal (observable) | Rollback | Escalation | |---|------------|-------|----------|------------------------------|------------------------------|----------|------------| | 1 | e.g., Acknowledge alert in PagerDuty | Incident Commander on-call | 2 min | PagerDuty incident transitions to acknowledged | Incident remains in triggered state after 2 min | n/a — read-only | Engineering Manager on-call ([email protected]) | | 2 | e.g., Open incident Slack channel | IC on-call | 3 min | Slack channel #inc- created and linked from PagerDuty | Slack API returns 4xx | Archive channel if created in error | Eng Manager on-call | | 3 | e.g., Notify execs via paging tree | Comms Lead ([email protected]) | 5 min | SES API returns 200 for all exec recipients | SES API returns 5xx OR delivery=bounced | Send retraction email with subject prefix 'RETRACTION:' | VP Communications |


JSON skeleton

{
  "runbook_name": "Incident Comms Cascade",
  "steps": [
    {
      "title": "Acknowledge alert in PagerDuty",
      "owner": "Incident Commander on-call (PagerDuty: ic-primary)",
      "duration_str": "2 minutes",
      "duration_minutes": 2,
      "success_signal": "PagerDuty incident transitions to acknowledged",
      "failure_signal": "Incident remains in triggered state after 2 minutes",
      "rollback": "n/a — acknowledgement is non-mutating, read-only operation",
      "escalation": "Engineering Manager on-call ([email protected])"
    },
    {
      "title": "Open incident Slack channel",
      "owner": "Incident Commander on-call",
      "duration_str": "3 minutes",
      "duration_minutes": 3,
      "success_signal": "Slack channel #inc-<id> created and linked from PagerDuty incident",
      "failure_signal": "Slack returns 4xx or channel-create API times out",
      "rollback": "Archive channel if created in error (Slack admin tools)",
      "escalation": "Engineering Manager on-call ([email protected])"
    },
    {
      "title": "Notify execs via paging tree",
      "owner": "Communications Lead ([email protected])",
      "duration_str": "5 minutes",
      "duration_minutes": 5,
      "success_signal": "Exec recipient list shows 200 OK from SES API for all addresses",
      "failure_signal": "SES API returns 5xx OR delivery status = bounced for any recipient",
      "rollback": "Send retraction email to same list with subject prefix 'RETRACTION:'",
      "escalation": "VP Communications ([email protected])"
    }
  ]
}

Markdown form (alternative — runbook_validator.py heuristic parser)

If you prefer authoring in markdown directly, follow this exact structure (the parser keys off ## Step N: headings and bullet attributes):

# Runbook: Incident Comms Cascade

## Step 1: Acknowledge alert in PagerDuty

- **Owner:** Incident Commander on-call (PagerDuty: ic-primary)
- **Duration:** 2 minutes
- **Success:** PagerDuty incident transitions to acknowledged
- **Failure:** Incident remains in triggered state after 2 minutes
- **Rollback:** n/a — non-mutating, read-only
- **Escalation:** Engineering Manager on-call ([email protected])

## Step 2: Open incident Slack channel

- **Owner:** ...

Authoring discipline checklist

Before submitting the runbook to the validator:

  • [ ] Every step has a named owner, not "the team" or "ops" — required by SRE Workbook Ch. 8.
  • [ ] Every step has a concrete duration (number + unit). "Quick" is not a duration.
  • [ ] Every success signal is observable — a yes/no check the operator can perform. "HTTP 200 from /healthz", not "service is up".
  • [ ] Every failure signal is observable — what tells you the step did NOT work.
  • [ ] Every state-mutating step has a rollback path OR an explicit "cannot be rolled back — escalate to " line (AWS Well-Architected OPS04-BP02).
  • [ ] Every step has an escalation contact — named human, role+email, or named on-call rotation.
  • [ ] Top-2 failure modes documented (Fowler 2016) — most common ways this runbook gets stuck, each with their own recovery sub-procedure.
  • [ ] Last-reviewed date set in frontmatter — runbooks decay; Charity Majors's data: untouched 12-month-old runbooks are wrong 60% of the time.

After validation, place the runbook in the canonical wiki location and link it from at least 2 navigation hubs (incident-handbook, the parent SOP) to avoid orphan-page status.