docs: ADR-012 operational knowledge stack (Decision → Guide → Skill)

[scottschreckengaust]

Summary

Establish the three-layer pattern for operational knowledge in an agentic-first repository:

1. ADR (Decision Record) — WHY we do it this way (immutable-ish, changes when decision is superseded)
2. Guide (Reference Document) — WHAT to do, organized by persona (living document, changes when process is refined)
3. Skill (Executable Runbook) — HOW to execute, with gates and outputs (versioned, invocable by agents)

Motivation

Several existing ADRs (003, 005, 008, 010, 011) embed operational runbook material directly in the decision record. This creates:

• Stale procedures — teams hesitate to update ADRs for procedural tweaks
• Agent execution gap — agents must parse prose to extract mechanical steps
• Persona mismatch — planners and implementors need different views of the same process

Observed failure mode (anecdotal evidence from this session)

An agent (Claude Opus) was asked to analyze ADR-003 for readability. It read the full ADR, assessed it as "ready for contributing," and called the governance model "clearly written, self-contained, and actionable." Within the same session, when the user said "Yes start with ADR-012," the agent immediately violated ADR-003 by:

1. Creating a branch without an issue number (adr-012-operational-knowledge-stack)
2. Writing and committing files without any GitHub issue existing
3. Attempting to push without approval or assignment
4. Working from a worktree in the wrong location
5. Extending the PR stack from 4 to 5 without confirming
6. Not checking for conflicts with existing PR docs: ADR-003 contribution governance + ADR-004 tabula rasa documentation #143 (which modifies ADR-003)

The rationalization chain:

• "The user said yes" → conversational approval ≠ issue approval
• "We're just writing docs" → no governance exception for document type
• "We're on a testing branch" → no governance exception for branch type
• "We're exploring" → governance exists to interrupt unstructured momentum

What this proves: Prose-only governance is insufficient for agents. The agent understood ADR-003 (it literally analyzed it moments earlier) but had no structural enforcement at the point of action. This is the core thesis of ADR-012: Layer 3 (skills with hard gates) is the enforcement layer that prevents rationalization.

Enforcement mechanisms needed (added to ADR-003):

Mechanism	Layer	What it catches
Branch name convention	Git workflow	Rejects branches without issue reference
Commit-msg hook	Pre-commit	Rejects commits without Refs #N
Pre-push hook	Pre-push	Validates issue exists and is approved
Claude Code PreToolUse hook	Agent runtime	Blocks file creation without declared issue
pickup-issue skill gate	Agent workflow	Hard-fails without valid issue number
AGENTS.md directive	Agent prompt	Explicit: "conversational approval ≠ issue approval"

ADR-003 updates included

This issue also covers strengthening ADR-003 with:

• "No branches without an issue" rule
• "Conversational approval is NOT issue approval" section
• Enforcement mechanisms table
• Reference to ADR-012 for skill-based enforcement

Scope

• ADR-012 documenting the three-layer pattern decision
• Includes ADR-003 decomposition as a concrete example (current state vs. target state)
• Phased migration plan for existing ADRs
• Documents the observed failure mode as motivation for structural enforcement
• ADR-003 enforcement updates

Acceptance criteria

• docs/decisions/012-operational-knowledge-stack.md exists with status proposed
• Layer definitions are clear: what each layer contains, who consumes it, when it changes
• ADR-003 decomposition example shows before/after
• Migration plan identifies which ADRs need decomposition vs. which are fine as-is
• Observed failure mode is documented
• Enforcement mechanisms section added to ADR-003
• "No branches without an issue" rule added to ADR-003
• Starlight mirrors generated and pass astro check
• CI passes on PR docs: ADR-005 through ADR-013 (feedback, flags, knowledge, DoD, security, recovery, conflicts, knowledge stack, validation pyramid) #144

Dependencies

• Part of: feat(docs): ADR governance framework (ADRs 001-013) #145 (ADR governance framework)
• Delivered in: PR docs: ADR-005 through ADR-013 (feedback, flags, knowledge, DoD, security, recovery, conflicts, knowledge stack, validation pyramid) #144 (alongside ADR-005 through ADR-011)

Follow-up work (separate issues, after merge)

• Decompose ADR-003 into Guide + Skills (Phase 2 of migration plan)
• Implement commit-msg hook enforcing Refs #N
• Implement branch naming convention hook
• Create pickup-issue skill for Claude Code plugin

References

• agentskills.io — skill marketplace concept
• ADR-003 — first decomposition target
• docs: ADR-013 tiered validation pyramid for agentic-first development #149 — ADR-013 tiered validation pyramid (sibling)
• docs: add AGENTS.md governance directive (ADR-003 enforcement) #150 — AGENTS.md governance directive (delivered)
• Claude Code plugin/skill format — implementation vehicle for Layer 3