new-playbook-authoring

name

new-playbook-authoring

description

Use this skill when the task is to author a new Faultline playbook after a gap has already been explicitly justified. Trigger it only when triage-unmatched-log, collect-coverage-evidence, or a confirmed fixture regression has established that a new playbook is warranted and the nearest existing playbook cannot cover the case. Covers placement decision (bundled vs extra pack), required YAML field authoring, pattern discipline for match.any and match.none, fixture pairing, and the full make review / make test / make fixture-check validation sequence. Do not trigger it speculatively or as a first step — refinement should always be ruled out first.

New Playbook Authoring

This skill is for authoring a new Faultline playbook from an explicitly justified gap.

Use it when:

• triage-unmatched-log.md has determined a new playbook is warranted
• collect-coverage-evidence.md has classified a sample as "gap — new category" and that classification has survived triage
• a confirmed real-fixture regression reveals a root cause with no existing playbook analog

Do not use it for:

• speculative catalog expansion
• cases where the nearest playbook could be tightened instead (use playbook-refinement)
• general YAML or Go coding tasks

Read First

• SYSTEM.md
• docs/playbooks.md
• docs/fixture-corpus.md
• docs/ontology.md — required for ontology field values
• prompts/author-new-playbook.md
• The nearest related playbook under playbooks/bundled/

Workflow

1. Answer the pre-flight questions in the prompt before writing any YAML:
   • What is the root cause (one sentence)?
   • What is the nearest existing playbook by ID?
   • Does the proposed pattern overlap with that neighbor? Can match.none resolve it instead?
2. Decide placement: bundled playbooks/bundled/log/<category>/ for high-frequency cross-stack failures; extra pack for provider-specific or deep operational rules.
3. Author the YAML with all required fields: id, title, category, severity, base_score, tags, stage_hints, summary, diagnosis, fix, validation, match.any, match.none, workflow.likely_files, workflow.local_repro, workflow.verify Plus ontology fields (required for new playbooks): domain, class, mode — see docs/ontology.md for valid values.
4. Pair fixtures before validating:
   • if a staged fixture exists, promote it: faultline fixtures promote <id> --expected-playbook <new-id> --strict-top-1
   • if no staged fixture exists, use the fixture-generation skill to produce canonical, noisy, and near-miss variants under fixtures/minimal/
5. Run the playbook-linter skill. All critical criteria must PASS before proceeding.
   • If FAIL: resolve all critical issues and re-run the linter before continuing.
   • If the same critical criterion still fails after two fix attempts, re-triage the gap — the root cause may be too ambiguous for deterministic matching. Stop and report the blocking criterion.
6. Run the full validation sequence in order:

   make review
   make test
   make build
   make fixture-check
   

7. If make review reports a conflict, tighten patterns before continuing.

Guardrails

• Do not author without a justified gap decision from a prior workflow.
• Prefer refinement over addition; new playbooks must earn their place.
• Every match.any phrase must be grounded in at least one real log sample.
• Every match.none exclusion must be grounded in at least one real confusable case.
• Do not ship with placeholder workflow fields.
• Do not ship without ontology fields (domain, class, mode).
• Do not skip the playbook-linter skill before make review.
• Do not stop at a passing compile or a single fixture match; run all four validation commands.

Deliverable

Report:

• the new playbook YAML path and ID
• the fixtures used to defend it (canonical, noisy, near-miss paths and scores)
• the playbook-linter verdict and any issues resolved
• the nearest confusable neighbor and how the boundary is maintained
• the exact validation commands run and their results