Playbook Authoring Guide

<!-- /hpc-resolution-path/docs/PLAYBOOK_AUTHORING.md --> # Playbook Authoring Guide

cp data/playbooks/_playbook-template.json data/playbooks/my-incident.json

Files beginning with _ are ignored by the runtime loader.

• id: stable kebab-case identifier
• title: public scenario title
• shortTitle: compact UI label
• description: what the incident means operationally
• category: compatibility layer used by the live fault tunnel
• primaryDomain: the one technology domain that owns the guide in the public library and classifier
• diagnosticArea: the domain-specific area shown in that domain’s library
• verticals: related technology domains for context; the first entry must equal primaryDomain
• keywords: matching terms for the local classifier
• defaultSeverity: low, medium, high, or critical
• topology: environment context
• entryStepId: first deterministic gate
• phases: visible execution path
• steps: evidence gates
• resolutions: approved outcomes

Recommended metadata:

• signalSources
• toolFamilies
• teamRoute
• faultBoundaries
• operatingNotes
• relatedScenarioIds
• version
• lastReviewed

Every guide belongs to exactly one public technology-domain library. This prevents an HPC guide from appearing in AI Platform, a cloud guide from appearing in Network, or a storage guide from inflating unrelated counts.

Example:

{
  "primaryDomain": "network",
  "diagnosticArea": "routing-control",
  "verticals": ["network", "cloud", "datacenter"]
}

primaryDomain controls where the guide appears and which classifier may select it. verticals only documents related environments inside the guide. It does not copy the guide into those libraries.

Valid diagnostic areas are defined in lib/domain-taxonomy.ts. Run npm run validate:playbooks after changing either field.

A good scenario normally includes:

1. 01Scope and blast radius
2. 02Physical, environmental, or topology observation
3. 03Management-plane or service evidence
4. 04Read-only CLI evidence
5. 05Decision gate
6. 06Resolution, containment, or escalation

Do not force every incident through the same layers. A scheduler problem may start with scheduler state; a power hazard may stop before CLI work.

Each command needs:

• Stable ID
• Human-readable label
• Exact command
• Purpose
• Expected signals
• Access level
• Safety classification
• Optional stopIf

Prefer commands that work broadly or detect available tooling safely.

Never put secrets, real hostnames, customer paths, or destructive commands in the public catalog.

Every option must contain exactly one of:

• nextStepId
• resolutionId

Always include an ambiguous-evidence branch when real signals can conflict.

A resolution should contain:

• Diagnosis supported by the selected path
• Fault domain
• Conservative confidence
• Owner route
• Next action
• Safety gate
• Evidence required
• Escalation packet
• Return-to-service validation

Do not claim a root cause when the evidence only narrows a boundary.

npm run validate:playbooks
npm run test

A team can keep a private playbook entirely inside its local project copy:

cp data/playbooks/_playbook-template.json \
  data/playbooks/internal-scenario.json

Edit the JSON, validate it, and restart:

npm run validate:playbooks
npm run typecheck
npm run test
npm run dev

No public repository, contributor account, database, server, authentication provider, external AI key, or production connection is required.

When the public repository is available:

1. 01Fork the repository.
2. 02Create a focused branch.
3. 03Add or update one sanitized JSON playbook.
4. 04Include tests or documentation when behavior changes.
5. 05Run the complete validation suite.
6. 06Open a pull request using the repository template.

See CONTRIBUTING.md.

A playbook may be authored or reviewed by technical account managers, solutions engineers, resident engineers, field or site engineers, Linux and platform engineers, cloud operators, AI infrastructure specialists, network or fabric specialists, storage teams, facilities teams, scheduler and runtime teams, and workload owners.

A strong playbook usually benefits from more than one perspective: the subject-matter specialist validates the technical evidence, while the incident or account owner validates routing, communication, safety, and escalation quality.