gz-adr-create

name: gz-adr-create persona: main-session description: Create and book a GovZero ADR with its OBPI briefs. Enforces next-free-integer nominal allocation for foundation IDs and five-gate compliance. Portable skill for GovZero-compliant repositories. category: adr-lifecycle compatibility: Requires GovZero v6 framework; provides governance rules internally for portable use across repositories metadata: skill-version: "6.6.0" govzero-framework-version: "v6" version-consistency-rule: "Skill major version tracks GovZero major. Minor increments for governance rule changes. Patch increments for tooling/template improvements." govzero-compliance-areas: "charter (gates 1-5), lifecycle (state machine), linkage (ADR/OBPI/GHI), foundation-nominal-allocation (next-free-integer)" govzero_layer: "Layer 3 - File Sync" lifecycle_state: active owner: gzkit-governance last_reviewed: 2026-06-16 model: opus

gz-adr-create (v6.0.0)

Purpose

Self-Escalation (opus-tier). Spawn an Agent with model="opus" to execute this skill. Pass the operator's request verbatim, any relevant context (ADR IDs, OBPI IDs, design topic, prior decisions), and instruct the subagent to read .gzkit/skills/gz-adr-create/SKILL.md for the full workflow. Relay the subagent's output to the operator.

Create GovZero-compliant ADR files with proper SemVer versioning, OBPI briefs, and registry booking.

This skill enforces GovZero v6 compliance rules internally and is portable to any GovZero-compliant repository.

Common Rationalizations

Red Flags

• ADR file exists but no interview answers JSON file alongside it
• ADR marked Proposed with zero OBPI brief files in obpis/
• Interview questions bundled into a single message instead of one at a time
• ADR Feature Checklist has more items than there are OBPI briefs
• Agent creates ADR files before any conversation with the human

Persona

Active persona: main-session — read .gzkit/personas/main-session.md and adopt its behavioral identity before executing this skill. The interview is collaborative authoring, not interrogation. Draft first, ask second. Capture what the human adds that you could not have generated.

Trust Model

Layer 3 — File Sync: This tool creates files without verification.

• Reads: User input, templates, existing ADR registry
• Writes: ADR files, OBPI brief files, registry entries
• Does NOT verify: Evidence, test coverage, or criteria
• Does NOT touch: Ledger files

GovZero Compliance Rules

ADRs propel MINOR versions only -- each ADR increments the minor odometer (human gate required for version bumps).

See references/govzero-compliance-rules.md for the full versioning, lifecycle states, five gates, OBPI discipline, and co-creation rules.

Versioning Covenant

This skill maintains explicit alignment between skill version and GovZero version:

Format: {govzero_major}.{skill_minor}.{skill_patch}

• {govzero_major}: Tracks GovZero major version (e.g., v6 → 6)
• {skill_minor}: Increments when GovZero governance rules change
• {skill_patch}: Increments for tooling/template improvements, no governance changes

Examples:

• 6.0.0 — Initial GovZero v6 implementation
• 6.1.0 — GovZero v6 governance rules updated (charter/lifecycle/gates)
• 6.0.1 — Template or procedure fix, no governance change
• 7.0.0 — GovZero v7 released; major rewrite

Consistency rule: The skill version's major component MUST always match the GovZero version it enforces.

Inputs

• adr_id: Example ADR-0.0.7.
• title: Example agent-skills-foundation.
• series: Example adr-0.0.x.
• brief_count: Number of OBPI briefs to create (if requested).

Assets

• ADR Template: src/gzkit/templates/adr.md (canonical in-repo shape; the gold standard recent foundation ADRs use). The legacy assets/ADR_TEMPLATE_SEMVER.md is airlineops-flavored and superseded — do not use it.
• OBPI Brief Template: src/gzkit/templates/obpi.md (canonical; .gzkit/skills/gz-obpi-specify/assets/OBPI_BRIEF-template.md is the authoring guide)
• Closeout Form: Use pattern from existing ADR closeout forms

Outputs

• ADR markdown file under docs/design/adr/{series}/ADR-{id}-{slug}/.
• ADR closeout form: ADR-CLOSEOUT-FORM.md in the same folder.
• OBPIs folder: docs/design/adr/{series}/ADR-{id}-{slug}/obpis/ (canonical).
• The ADR status index docs/governance/GovZero/adr-status.md — a Layer-3 derived view regenerated by gz register-adrs, never hand-edited (see .claude/rules/governance-core.md § ADR status index regeneration).
• OBPI briefs under the obpis/ folder (when requested).

Procedure

Step 0: Interview (MANDATORY — NON-NEGOTIABLE)

No ADR may be authored without first completing a structured interview.

The interview captures problem, decision, alternatives, consequences, and scope before any template work, file creation, or registry updates.

Agent-Driven Interview (preferred)

The agent conducts the Q&A conversationally, then records answers deterministically:

1. Skip deducible fields. ID, title, lane, semver — if already known from context, state them and move on. Don't waste the human's time on mechanical fields the agent can fill. --kind is not deducible — it is a substantive design question (see Tier 1), always asked, never guessed.

2. For each substantive question, draft first, then ask. By the time an ADR is being created, there's usually conversation context — a design discussion, a defect, a discovered need. The agent reads the question, drafts an answer from what's already known, and presents it for the human's input, correction, or acceptance. This is collaborative authoring, not interrogation.

3. One question at a time. Never batch questions. The human's response to one question often reshapes the next answer. Each exchange is a design conversation, not a form fill.

4. Capture the human's additions. The best interview content comes from what the human adds that the agent couldn't have generated — broader patterns, risk instincts, connections to other work. These additions are the interview's primary value.

5. Record via --from. After the conversation, write answers to a JSON file and record deterministically:

uv run gz interview adr --from <answers-file>.json

6. Keep the answers file with the ADR. The JSON file is a permanent artifact — store it alongside the ADR document (in the ADR directory for promoted ADRs, in the pool directory for pool ADRs).

Human-Interactive Interview (terminal)

For humans working without an agent, the interactive mode still works:

uv run gz interview adr

Question Protocol

The deducible fields (id, title, semver, lane, parent) are mechanical — skip them or confirm from context. The interview's value comes from two tiers:

Tier 1 — ADR Pro-Forma (required, populate the template):

• What kind of ADR is this? — foundation (app/system invariant, always 0.0.x) / feature (release-carrying capability) / pool (noted, not committed). Heuristic: Does this decision shape what the app IS (identity/invariant)? → foundation. Does this decision ship a named capability to users? → feature. Is this decision noted but not committed? → pool. For deeper context see docs/user/concepts/adr-taxonomy.md. Invariance Test (Foundation/Feature Boundary): "Foundation = without it, we wouldn't be doing the project." Use the hexagonal-ports lens to resolve edge cases: ports point to invariance; adapters are features. See docs/user/concepts/foundation-feature-invariance-test.md for worked examples and anti-patterns. gz plan create and gz adr promote require --kind with no default — the operator must choose. Never pre-fill; never propose a default.
• What problem are we solving? — forces concrete articulation of the need
• What did we decide? — forces specificity beyond "we'll add a field"
• What alternatives were considered? — forces decision justification
• What are the positive consequences? — forces articulation of value
• What are the negative consequences? — forces honest risk assessment
• What are the checklist items? — forces decomposition into deliverables

Tier 2 — Design Forcing Functions (required, stress-test the decision):

These questions turn the interview from "document what you decided" into "stress-test the decision before committing." Each one works with the draft-first pattern — the agent proposes an answer, the human corrects.

1. Pre-Mortem (Gary Klein): "It is 18 months from now. This decision has failed spectacularly. Why?" — bypasses optimism bias. The agent drafts failure scenarios, the human adds the ones the agent can't see.

2. What Would Have to Be True (Roger Martin): "What would have to be true for this to be the right decision?" then "What would have to be true for Alternative B to have been better?" — the agent lists conditions, the human flags which are shaky. The shakiest condition is the biggest risk.

3. Constraint Archaeology: "Is this constraint real, inherited, or assumed? When was it last tested?" — forces examination of whether constraints are still load-bearing or just inherited convention nobody re-examined.

4. Assumption Surfacing: "Which assumptions here are implicit and undocumented? What if the opposite of your core assumption were true?" — different from constraints. Constraints are things we know are fixed. Assumptions are things we don't realize we're relying on.

5. The 2am Operator Question: "You are on-call at 2am and this is broken. What do you need that the design doesn't provide?" — forces the operational perspective that architecture documents chronically miss. Especially strong for Heavy lane ADRs.

6. Reversibility Assessment: "Is this a one-way door or a two-way door? If we need to reverse this in 12 months, what does that cost?" — affects lane assignment, ceremony level, and how much evidence is warranted.

7. Scope Minimization: "What's the smallest version of this that delivers value? If you had half the time, what would you cut?" — different from non-goals. Non-goals say what's out. Minimization says what's essential. The second question forces prioritization under pressure.

Closing question (always ask last):

"What subsequent decisions does this force? What ADRs will we need to write because of this one?"

Forward-looking — surfaces downstream commitments the decision creates.

Sources: Klein (pre-mortem), Martin (WWHTBT), Amazon (one-way/two-way doors), Kubernetes Production Readiness Review (operator perspective), SAST (assumption surfacing), Fairbanks (risk-driven architecture).

Why this is non-negotiable: Uninterviewed ADRs produce vague intent documents that drift during implementation. The interview forces structured articulation of the decision before any artifacts exist, preventing scope ambiguity at the source.

Prohibited patterns:

• Creating ADR files first, then "backfilling" interview answers
• Agent fabricating answers without asking the human
• Skipping the interview because "the intent is already clear"
• Running the interview after OBPI co-creation

1. Read the canonical template at src/gzkit/templates/adr.md (the in-repo shape recent foundation ADRs use; the legacy assets/ADR_TEMPLATE_SEMVER.md is superseded).
2. Verify GovZero compliance: ADR ID follows 0.y.z format; status uses canonical lifecycle states.
3. Create the ADR folder: docs/design/adr/{series}/ADR-{id}-{slug}/.
4. Create the ADR markdown file using the template structure (all sections required).
5. Create the OBPIs subfolder: obpis/.
6. Create ADR-CLOSEOUT-FORM.md following existing closeout form patterns.
7. Register the ADR in the ledger (Mandatory): Run uv run gz register-adrs ADR-X.Y.Z immediately after the ADR file exists on disk. Emits the adr_registered ledger event so gz adr report and downstream gates recognize the ADR, AND regenerates the Layer-3 status index docs/governance/GovZero/adr-status.md from on-disk frontmatter. Never hand-edit that index — it is a derived view (.claude/rules/governance-core.md § ADR status index regeneration). Required for every kind — foundation, feature, and pool — regardless of whether OBPIs are co-created in the same session. Skipping this step is the canonical failure that produces "ADR exists on disk but is not registered in ledger" warnings.
8. OBPI Co-Creation (Mandatory): Create one OBPI brief per checklist item.
   • Count checklist items in Feature Checklist
   • Preferred: Run uv run gz specify <slug> --parent ADR-X.Y.Z --item N for each item to scaffold, then author each brief semantically from the ADR. Do NOT pass --author on a fresh scaffold — it requires authored-ready content that does not yet exist and fails closed; author the body first, then validate.
   • Alternative: Create files manually in obpis/ with YAML frontmatter (id:, parent:, item:, lane:, status:)
   • Re-register after OBPIs exist: Run uv run gz register-adrs ADR-X.Y.Z --all to emit obpi_created ledger events for the newly authored briefs
   • Verify: ls obpis/ | wc -l matches checklist item count
   • Validate authored readiness: uv run gz obpi validate --adr ADR-X.Y.Z --authored
   • This is NOT optional — briefs are co-created with the ADR, never deferred
9. Post-Authoring QC (Mandatory before proposal/defense): Invoke gz-adr-evaluate ADR-X.Y.Z to run the ADR and its OBPIs through the evaluation framework.
   • Score the ADR on all 8 dimensions
   • Score each OBPI on all 5 dimensions
   • Any ADR dimension scoring 1 or any OBPI dimension scoring 1 must be revised before proceeding
   • The CLI scorer is a pattern-matching pre-screen, not a truth oracle. When it false-negatives on format/keywords (e.g. flags a missing "before/after" token or a bold-numbered vs markdown-numbered list), fix the genuine content weakness it points at — do NOT reword solely to feed the matcher the tokens it wants. Gaming the scorer's shape heuristics is the same theater this skill's ADRs exist to kill.
   • Optionally use gz-adr-evaluate ADR-X.Y.Z --red-team for adversarial review
   • Record the output as EVALUATION_SCORECARD.md in the ADR directory
10. Validate:

uv run -m unittest -q
uv run mkdocs build --strict

Template Sections (Required)

The ADR template includes these sections that must be populated:

• Tidy First Plan
• Feature Checklist — Appraisal of Completeness
• Intent
• Decision
• Interfaces
• Rationale
• Consequences
• Evidence (Four Gates)
• OBPI Acceptance Note
• Evidence Ledger (with subsections)
• Completion Checklist — Post-Ship Tidy
• OBPI Briefs table

Failure Modes

• ADR created without using the canonical template.
• ADR references files that don't exist.
• Registries drift (ADR exists but isn't indexed or has conflicting status).
• Governance copy not updated (out of sync with main status).

Acceptance Rules

• ADR uses the canonical template structure.
• No duplicate ADR IDs.
• Registries and ADR content agree on status and series.
• All three registry files are in sync.
• Markdown lint stays clean for docs/.

Related Skills

• gz-adr-evaluate: Post-authoring QC evaluation before proposal/defense
• gz-obpi-specify: Create and author OBPI briefs from ADR decomposition
• gz-adr-closeout-ceremony: Execute closeout ceremony
• gz-adr-audit: Verify ADR evidence (includes evidence checks and coverage discovery)
• gz-adr-sync: Sync ADR index/status from ADR files (includes registration)