# Plan: OBPI-0.0.23-01 — Author `agent-failure-modes.md`

**OBPI:** OBPI-0.0.23-01-author-failure-modes-rule
**Parent ADR:** ADR-0.0.23-agent-failure-mode-taxonomy (kind: foundation, lane: heavy)
**OBPI Lane:** Lite (rule authoring; foundation-kind brief-level Gate 5 still applies)
**Plan-mode posture:** plan-before-exploration disclosure below; no source edits made before this plan was written.

## Destination-in-mind disclosure (Step 6a)

Before writing this plan I had already read the parent ADR (Decision items 1–5,
Evidence checklist, Q&A note that the taxonomy is sourced from Opus 4.7 system
card § 2.3.6 and corroborated by GPT-5.5 system card § 9.2). The conclusion I
had formed: a single new file `.gzkit/rules/agent-failure-modes.md` carrying
six H2 sections (one per pattern), each with a one-sentence definition, an
external citation with section anchor, and a pointer to a gzkit invariant.
Frontmatter `paths:` scoped to `AGENTS.md`, `.gzkit/rules/**`,
`docs/governance/**`. A "When to invoke this vocabulary" section with worked
examples after the six patterns. Body-level `<!-- rule-version: 0.1.0 -->`
marker plus visible block quote per `.claude/rules/skill-surface-sync.md`.

## Rejected alternatives

1. **Inline taxonomy in AGENTS.md.** Rejected by the ADR § Alternatives
   Considered #1 (bloats always-loaded surface). Re-confirmed by reading
   AGENTS.md size and load posture.
2. **Single H2 with a six-row table.** Rejected: the rule needs per-pattern
   citation + backstop pointer, which a table compresses unreadably and
   makes the cross-link target ambiguous when an external doc says "see
   `agent-failure-modes.md` § Fabrication."
3. **Author both rule + scorecard entry in this OBPI.** Rejected: scorecard
   entry is OBPI-02's scope per the ADR Checklist. Mixing would violate the
   1:1 brief-checklist sync mandate.
4. **Reuse an existing rule's frontmatter `paths:` exactly.** Rejected: the
   doctrine of this rule applies wherever rule/doctrine authoring happens
   (`AGENTS.md`, `.gzkit/rules/**`, `docs/governance/**`), narrower than
   `**/*` (governance-core) and broader than a single subtree.

## Files

| Path | Mode | Note |
|------|------|------|
| `.gzkit/rules/agent-failure-modes.md` | create | New canonical rule file (within Allowed Paths). |

No other files are touched in this OBPI. Vendor mirrors (`.claude/rules/`,
`.github/instructions/`) are explicitly out of scope per Denied Paths and are
regenerated by OBPI-03's `gz agent sync control-surfaces`.

## Steps

1. **Author the rule body** at `.gzkit/rules/agent-failure-modes.md` with this
   structure:
   - Frontmatter:
     - `id: agent-failure-modes`
     - `paths: ["AGENTS.md", ".gzkit/rules/**", "docs/governance/**"]`
     - `description: Six-pattern agent-failure-mode taxonomy (Opus 4.7 § 2.3.6 / GPT-5.5 § 9.2)`
   - Body-level `<!-- rule-version: 0.1.0 -->` immediately after the
     frontmatter, plus the visible `> **Rule version:** \`0.1.0\`` block
     quote with a one-sentence rationale (per
     `.claude/rules/skill-surface-sync.md`).
   - H1: `# Agent Failure-Mode Taxonomy (gzkit)`
   - Short opening paragraph naming the source (Opus 4.7 system card
     § 2.3.6, corroborated by GPT-5.5 system card § 9.2) and what the
     vocabulary is for (shared review/audit naming).
   - Six H2 sections in this exact order:
     1. `## Safeguard circumvention`
     2. `## Reckless action`
     3. `## Fabrication`
     4. `## Skipped cheap verification`
     5. `## Correction fails`
     6. `## Dishonest when caught`
   - Each H2 carries:
     - **Definition:** one sentence.
     - **External citation:** Opus 4.7 § 2.3.6 anchor (and GPT-5.5 § 9.2
       where corroborating).
     - **Backstop:** pointer to the gzkit invariant — one of
       `AGENTS.md` § DO IT RIGHT 6a / 6c / 6g / 6h, ARB receipts
       (`AGENTS.md` § Attestation), `validate --commit-trailers`,
       T1/T2/T3 invariants from `docs/governance/trust-doctrine.md`.
     - **Worked example:** a gzkit history reference where one exists
       (e.g. GHI #261 for `Dishonest when caught` reporting-pathway drift,
       GHI #263 for `Skipped cheap verification` runtime-surface
       pattern-match, GHI #290 for `Fabrication` of human-attestation
       receipts). Where no gzkit example exists yet, omit rather than
       fabricate.
   - H2 `## When to invoke this vocabulary` with two or three worked
     examples of reviewer/audit phrasing (e.g. *"this PR is `Skipped
     cheap verification` shape — it pattern-matched a flag from training
     memory without verifying the runtime surface"*).
   - H2 `## Loading posture` naming the rule as advisory (no mechanical
     enforcement in this OBPI; promotion to mechanical lands under
     follow-up GHIs #308–#312 per the parent ADR).
   - H2 `## Related` with cross-links to AGENTS.md, ARB middleware doc,
     trust doctrine, and (advisory placeholder) the future scorecard
     entry that OBPI-02 will land at
     `docs/governance/advisory-rules-audit.md`.

2. **Pattern-by-pattern citation lookup.** For each of the six patterns,
   confirm the section anchor in Opus 4.7 § 2.3.6 / GPT-5.5 § 9.2 from the
   parent ADR's Q&A Transcript / Evidence sections; cite verbatim where the
   ADR has the wording, otherwise quote the ADR's authoritative paraphrase.
   Do not fabricate citations.

3. **Citation-discipline self-check** before writing. Per
   `.claude/rules/tool-skill-runbook-alignment.md` Invariant 6h (verbatim
   quoting), every citation in the rule body must be traceable to the
   parent ADR or to a primary system-card source the ADR already references.

4. **Operator PII scrub.** No personal email, no real attestor identities
   in any worked example.

5. **Save and lint.** Run `uv run gz lint` and `uv run gz validate --documents`.

## Verification

```bash
test -f .gzkit/rules/agent-failure-modes.md
uv run gz lint
uv run gz validate --documents
```

Mapped to brief Acceptance Criteria:

- **REQ-0.0.23-01-01** (six patterns, prescribed order) — verified by reading
  the file's H2 outline.
- **REQ-0.0.23-01-02** (each pattern carries definition, citation, backstop) —
  verified by per-section read; worked example optional.
- **REQ-0.0.23-01-03** (frontmatter `paths:` glob scopes correctly) —
  verified by parsing the frontmatter and confirming the three globs are
  present.

`gz validate --documents` provides the Gate 2 mechanical floor; the brief's
verification block is reproduced verbatim above.

## Notes

- **Lane discrepancy with parent ADR is by design.** ADR is heavy because
  OBPI-04 introduces `gz issue file` (CLI verb). OBPI-01 itself is
  rule-authoring only — Lite is correct. Foundation-kind brief-level Gate 5
  attestation still applies (TTY + `ATTEST`).
- **Sibling-OBPI scope-collision warnings (advisory).** `gz plan audit`
  flagged contention on `.gzkit/rules/agent-failure-modes.md` and the
  ADR-0.0.23 package directory with five sibling OBPIs (ADR-0.16.0-02,
  ADR-0.0.9-06, ADR-0.0.10-01/03/04). All five are not in flight (no
  active locks per `gz state`); the OBPI-0.0.23-01 lock claim in pipeline
  Stage 1 already serializes these. No structural action needed beyond
  honoring the pipeline lock.
- **No vendor-mirror touch.** `.claude/rules/agent-failure-modes.md` and
  `.github/instructions/agent-failure-modes.md` are regenerated by
  OBPI-03's `gz agent sync control-surfaces` invocation. Touching them
  here would violate the brief Denied Paths.
- **No tests added.** The rule is content, not code; `gz validate
  --documents` is the mechanical floor. Promotion to a mechanical
  validator (and the corresponding tests) is the scope of follow-up
  GHIs #308–#312 per the ADR Decision text.
