tvproductions/gzkit / .agents/skills/gz-adr-create
gz-adr-create
VerifiedUse to create and book an ADR with its OBPI briefs under five-gate compliance.
gz-adr-create
Purpose
Self-Escalation (opus-tier). The dialogue with the operator stays in the main session: a subagent cannot ask the operator a question or hear the answer, and what the operator adds is this skill's primary input. When the session model is below opus-tier, you may spawn an
Agentwithmodel="opus"for a bounded drafting or QC track that needs no operator input — pass the operator's words verbatim and the relevant context (ADR IDs, OBPI IDs, prior decisions), and treat what it returns as a draft you verify, not as the operator-facing result.
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
| Thought | Reality |
|---|---|
| "The intent is already clear from the discussion, skip the interview" | Uninterviewed ADRs produce vague intent that drifts during implementation. The interview forces structured articulation. |
| "I'll create the ADR first and backfill the interview answers" | Interview answers shape the ADR content. Backfilling reverses the causality. |
| "This is a small change, it doesn't need a full ADR ceremony" | Small changes that skip the ceremony produce ADRs with missing sections that block downstream gates. |
| "OBPIs can be created later, after the ADR is reviewed" | Co-creation is mandatory. Deferred OBPIs create orphaned checklist items and scope ambiguity. |
| "The user already explained what they want, I can fill in the interview myself" | The interview captures what the human adds that the agent couldn't generate. Agent-fabricated answers miss risk instincts and cross-project connections. |
| "I'll skip the design forcing functions -- the pro-forma questions cover the essentials" | The forcing functions stress-test the decision. Pro-forma questions document it. Both are required. |
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
Work order (operator ruling, verbatim canon)
- Work feature ADRs in ascending semver order: the lowest version with unlanded OBPIs is in flight. Do not work, author, or recommend a higher feature ADR ahead of it. The campaign selects work but cannot override that order. If campaign sequencing conflicts, semver governs; surface the conflict to the operator rather than silently resolving it. “One feature at a time” does not authorize swapping the order. An ADR in flight may be revised to take more OBPIs. The revision updates the document (an Intent amendment, a Decision item, a checklist item and the scorecard baseline) and the briefs table in the same change. A Validated ADR is not revised: scope missed from one enters the in-flight ADR as a repair assignment that cites the obligation it repairs. An item off the ADR's theme is labelled as such in the Intent amendment. The (m)ADR is a stopgap: a release-increment bucket, meant to be thematically cohesive. Its successor is a feature bundle between an enhancement proposal and a feature specification. Names are chosen later. This replaces the exception of 2026-09-29 (GHI #871), by which a correction to a Validated ADR took the next unallocated feature semver and could be worked ahead of the in-flight ADR; that route is retired (operator rulings 2026-10-04: 'the new loosening law here is we need to be able to revise an adr to allow for more obpis - the document and briefs table gets updated'; 'A, in-flight only'; the wording and the retirement, each 'A').
Carried verbatim from root
AGENTS.md§ Operator Doctrine on 2026-09-17 (GHI #921), and into this skill on 2026-09-24 (GHI #1091, sweep finding S06): the ruling governs authoring and recommending, not only working. The corpus.gzkit/corpus/AGENTS.md.jsonlkeeps the ruling's history.
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
- Books: an
adr_createdledger event on authoring — for non-pool kinds only.gz interview adrandgz plan create --kind {foundation,feature}append it throughregister_adr_in_ledger(src/gzkit/commands/plan.py), which registers the ADR's existence, not its completion; the ledger IS touched.--kind poolbooks nothing — the pool branch returns before the register call, and the dry-run preview suppresses the ledger line to match. Pool entries reach Layer 2 throughuv run gz register-adrs, which reconciles ADR packages that exist in canon but are missing from ledger state.
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.
Inputs
adr_id: ExampleADR-0.36.0(feature) orADR-pool.<slug>(pool).title: Exampleagent-skills-foundation.brief_count: Number of OBPI briefs to create — one per Feature Checklist item.
Assets
- ADR Template:
src/gzkit/templates/adr.md(canonical in-repo shape; the gold standard recent foundation ADRs use). - OBPI Brief Template:
src/gzkit/templates/obpi.md(canonical;.gzkit/skills/gz-obpi-specify/assets/OBPI_BRIEF-template.mdis the authoring guide)
Outputs
- ADR markdown file under
docs/design/adr/<kind-dir>/ADR-{id}-{slug}/— the scaffolder picks the directory (foundation/,pre-release/,pool/). - OBPIs folder:
obpis/inside the ADR folder (canonical). - Not at authoring:
ADR-CLOSEOUT-FORM.mdis written later bygz closeout(src/gzkit/commands/closeout_form.py). - The ADR status index
docs/governance/GovZero/adr-status.md— a Layer-3 derived view regenerated bygz register-adrs, never hand-edited (seeAGENTS.md§ Governance doctrine surfaces). - 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:
-
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.
--kindis not deducible — it is a substantive design question (see Tier 1), always asked, never guessed. -
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.
-
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.
-
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.
-
Record via
--from(feature / release-carrying ADRs). For a non-pool ADR, after the conversation write answers to a JSON file and scaffold + record deterministically:
uv run gz interview adr --from <answers-file>.json
Pool ADRs take a different path — gz interview adr does NOT record them.
gz interview adr --from scaffolds non-pool ADRs only: it fails closed on a
pool id (ADR-pool.<slug>), which does not match the canonical
ADR-<semver>-<slug> form, and its error redirects to gz plan create. For a
pool ADR, write the same-shape answers as a hand-authored JSON artifact kept
alongside the ADR, and scaffold the stub with:
uv run gz plan create <slug> --kind pool --lane <lite|heavy>
then populate the generated ## Intent / ## Decision / ## Alternatives Considered / ## Notes sections from those answers.
- 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). For a pool ADR it is the only record of the Step-0 interview: no tool validates its shape today (tracked at GHI #718), so authoring it faithfully is the operator's discipline, not a gate's.
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 seedocs/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. Seedocs/user/concepts/foundation-feature-invariance-test.mdfor worked examples and anti-patterns.gz plan createandgz adr promoterequire--kindwith 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
In gzkit itself foundation is CLOSED to new authoring (AGENTS.md § Gate Covenant; roster data/foundation_grandfather.json; gz validate --taxonomy enforces it), so the choice here is feature or pool. Adopter repositories scaffold open.
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.
-
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.
-
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.
-
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.
-
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.
-
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.
-
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.
-
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
- Read the canonical template at
src/gzkit/templates/adr.md(the in-repo shape recent foundation ADRs use). - Verify GovZero compliance: ADR ID follows 0.y.z format; status uses canonical lifecycle states.
- Scaffold through the CLI, not by hand. Step 0's
gz interview adr --from(non-pool) orgz plan create --kind poolwrites the ADR folder and file from the template. - Populate every section the scaffold left as a placeholder (§ Template Sections).
obpis/is created when the briefs are scaffolded (step 8).- Do not author
ADR-CLOSEOUT-FORM.md—gz closeoutwrites it. - Confirm the ADR is in the ledger (Mandatory): the non-pool scaffolders book
adr_createdthemselves (§ Trust Model); a pool ADR, or any ADR file that reached disk another way, is booked byuv run gz register-adrs ADR-X.Y.Z. Run it wheneveruv run gz adr reportdoes not show the ADR. It also regenerates the Layer-3 status indexdocs/governance/GovZero/adr-status.mdfrom on-disk frontmatter. Never hand-edit that index — it is a derived view (AGENTS.md§ Governance doctrine surfaces). Skipping this step is the canonical failure that produces "ADR exists on disk but is not registered in ledger" warnings. - 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 Nfor each item to scaffold, then author each brief semantically from the ADR. Do NOT pass--authoron 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 --allto emitobpi_createdledger events for the newly authored briefs - Verify:
ls obpis/ | wc -lmatches 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
- Post-Authoring QC (Mandatory before proposal/defense; N/A for pool ADRs):
Invoke
gz-adr-evaluate ADR-X.Y.Zto run the ADR and its OBPIs through the evaluation framework. Pool ADRs are exempt —gz adr evaluateresolves an ADR package, which a pool ADR (flat stub file, no OBPIs yet) does not have; the CLI errors if invoked on one. The evaluate gate fires at promotion (gz adr promotebuilds the package), not at pool authoring.- 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-teamfor adversarial review - Record the judged output as
EVALUATION_SUBSTANCE.mdin the ADR directory —EVALUATION_SCORECARD.mdis machine-owned and regenerated bygz adr evaluate(GHI #769)
- Validate:
uv run gz test
uv run mkdocs build --strict
Template Sections (Required)
The ## headings of src/gzkit/templates/adr.md are the authority — populate every one. Illustratively, at 2026-09-19: Persona, Intent, Decision, Consequences (Positive / Negative), Fidelity Assertions, Decomposition Scorecard, Checklist, Q&A Transcript, Evidence, Alternatives Considered, Forcing Functions (the seven, plus Downstream Decisions Forced), Attestation Block.
Failure Modes
- ADR created without using the canonical template.
- ADR references files that don't exist.
- ADR exists on disk but is not booked in the ledger (step 7).
Acceptance Rules
- ADR uses the canonical template structure.
- No duplicate ADR IDs.
uv run gz adr reportshows the ADR, anddocs/governance/GovZero/adr-status.mdwas regenerated, not edited.- Markdown lint stays clean for
docs/.
Related Skills
gz-adr-evaluate: Post-authoring QC evaluation before proposal/defensegz-obpi-specify: Create and author OBPI briefs from ADR decompositiongz-adr-closeout-ceremony: Execute closeout ceremonygz-adr-audit: Verify ADR evidence (includes evidence checks and coverage discovery)gz-adr-sync: Sync ADR index/status from ADR files (includes registration)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |