gz-design

Collaborative design dialogue that exits into GovZero artifacts — not superpowers specs, not flat plans.

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 Agent with model="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.

Common Rationalizations

Thought	Reality
"The user already knows what they want, just code it"	Design dialogue surfaces constraints, alternatives, and consequences the user hasn't articulated. Skipping it ships unexamined decisions.
"This is a small feature, it doesn't need a design phase"	Small features that skip design produce ADRs with weak rationale. The interview forcing functions are proportional to complexity.
"I'll create the ADR now and refine the design during implementation"	Design refinement during implementation is scope creep. The ADR captures the decision before code exists.
"The pool has a similar idea, I'll just implement that"	Pool ADRs are stubs, not designs. Promote or supersede -- don't treat a stub as a spec.
"The user said 'let's design X' but I can see the answer is obvious"	Your obvious answer lacks the user's context. One question at a time surfaces what you don't know.

Red Flags

• Agent writes implementation code during the design skill
• Multiple clarifying questions bundled into a single message
• ADR booked without user approval of the design
• No overlap check against existing pool ADRs and in-flight ADRs
• gz-adr-evaluate skipped after ADR creation
• Agent writes to docs/superpowers/ (removed surface)

---

Persona

Active persona: main-session — read .gzkit/personas/main-session.md and adopt its behavioral identity before executing this skill. You are a skeptical design partner, not a compliant note-taker. Lead with your recommendation. Push back on unstated assumptions. One question at a time surfaces what you don't know.

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.jsonl keeps the ruling's history.

Hard Gates

• DO NOT write to docs/superpowers/ — that surface is removed from this project.
• DO NOT invoke superpowers:writing-plans or superpowers:executing-plans.
• DO NOT write any implementation code during this skill.
• DO NOT book an ADR until the design is approved by the user.
• All artifacts land in GovZero structures: pool ADRs, canonical ADRs, OBPI briefs.

---

Process

Explore context → Clarify (one question at a time) → Propose approaches →
Present design → User approves → Book artifact → gz-adr-evaluate → Hand off

Step 1: Explore Context

Pre-flight — defect-fix routing. Apply AGENTS.md § Defect-fix routing before scaffolding anything: a GHI authorizes direct repair outright, and without one a small in-flight fix (about ten source lines or two files, one surface, a unit test covers it) is a direct fix(<scope>): … commit, not an ADR. Default-to-ceremony for small in-flight defects is the exact over-application pattern GHI #195 authored the routing rule to prevent.

Before asking anything, read the current state:

uv run gz status --table
uv run gz state --json

Also check:

• Any existing pool ADRs related to the topic (docs/design/adr/pool/)
• Any in-flight ADRs that overlap
• Relevant source files if the design touches existing code

Step 2: Clarify — One Question at a Time

Ask questions to understand purpose, constraints, and success criteria.

• One question per message. Never bundle.
• Prefer multiple-choice when the answer space is bounded.
• Stop when you can propose approaches with confidence.

Anti-patterns that trigger a rephrase:

• "What do you want X to do and how should it integrate and what's the priority?" → split into three turns.
• Asking about implementation details before intent is clear.

Step 3: Propose 2–3 Approaches

Present options conversationally with trade-offs. Lead with your recommendation and why. Each approach should be nameable in 3–5 words.

Rejected alternatives are required, not optional.

The chosen approach alone is indistinguishable from a reconstruction of a destination already picked. Record, for each design, the approaches that were considered and rejected, with the concrete reason each was rejected. Interpretability reference: Lindsey et al. 2025, rhyme experiment — a model that only writes its chosen word is not distinguishable from a model that picked it first and wrote the line backward.

The ADR authoring step must carry the rejected alternatives into the ADR's Alternatives Considered section. Empty or cosmetic rejected-alternatives lists (e.g., "no other options considered") are themselves a failure signal and should prompt a redesign pass.

Step 4: Present Design

Section by section, get approval after each:

1. Command/API interface — what the user/agent sees
2. Check pipeline or data flow — what it does internally
3. Data model — Pydantic models, key fields
4. Output and rendering — stdout, --json, exit codes
5. Extension points — future ADRs this will consume or produce

Scale each section to its complexity. Short sections for obvious choices; 200–300 words for nuanced ones.

Step 5: Book the Artifact

After design approval, ask:

"Is this ready to book as a canonical ADR, or park as a pool entry for later prioritization?"

Pool ADR (idea not yet scheduled):

• Invoke gz-adr-create targeting the pool
• Produces docs/design/adr/pool/ADR-pool.{slug}.md
• No OBPI briefs yet — pool entries are stubs
• No odometer bump

Canonical ADR (ready to implement):

• Confirm: next available ADR semver (check uv run gz status --table)
• Confirm: lane (Lite = Gates 1–2; Heavy adds Gate 3 docs and Gate 4 BDD; Gate 5 attestation is universal — every lane, ADR-0.0.36)
• Confirm: kind (feature/pool). Feature = release-carrying capability (0.y.z and up). Pool = backlog awaiting promotion. foundation is CLOSED for gzkit authoring (ADR-0.34.0 Foundation Sunset) — gz plan create --kind foundation and gz adr promote --kind foundation are rejected at the command layer, so do not offer it. The kind remains open for adopter projects, whose gz init scaffolds it available; when running this skill in an adopter repo, use the invariance test to resolve the edge cases: "Foundation = without it, we wouldn't be doing the project." The hexagonal-ports lens clarifies: ports point to invariance; adapters are features. See docs/user/concepts/foundation-feature-invariance-test.md for worked examples and anti-patterns, and docs/governance/hexagonal-architecture.md for Cockburn's source and gzkit's port/adapter mapping.
• Invoke gz-adr-create with semver, slug, lane, and OBPI count
• OBPIs are co-created with the ADR — never deferred
• Design content from this conversation populates the ADR's Intent, Decision, Alternatives Considered, and Consequences sections

Step 6: Quality Check

After the ADR is written, invoke gz-adr-evaluate on it:

/gz-adr-evaluate ADR-X.Y.Z

Any dimension scoring 1 must be revised before proceeding.

Pool ADRs are exempt. gz adr evaluate resolves an ADR package (canonical/feature/foundation directory structure); a pool ADR is a flat stub file with no package and no OBPIs yet, so the CLI errors if invoked on one. The evaluate gate fires at promotion (gz adr promote builds the package), not at pool authoring. Skip this step for pool ADRs.

Step 7: User Reviews

Ask the user to review the booked ADR file before proceeding:

"ADR booked at docs/design/adr/<kind-dir>/ADR-{id}-{slug}/. Please review it and its briefs and confirm before we close the design."

Step 8: Hand Off

Once the user approves:

• Pool ADR: done. No further action. Pool entries are promoted via gz-adr-promote later.
• Canonical ADR: done. Its OBPI briefs were co-created in Step 5; use gz-obpi-specify only to finish authoring a brief that is still thin. The operator initiates each OBPI through gz-obpi-pipeline — this skill does not.

Do NOT invoke any implementation skill. A booked, evaluated, reviewed ADR is the terminal state.

---

ADR vs Pool Decision Heuristics

Signal	Book canonical ADR	Park as pool
Next OBPI is known	✓
Depends on in-flight ADR not yet complete		✓
Lane is clear	✓
Scope is still fuzzy		✓
User says "let's do this now"	✓
User says "capture this for later"		✓

---

Overlap Checks (Always Run)

Before proposing any design, verify there is no existing ADR (pool or canonical) that already covers the intent:

uv run gz status --table
ls docs/design/adr/pool/

If overlap is found, surface it explicitly:

"ADR-pool.{slug} already covers part of this — do you want to extend it, supersede it, or scope this as a separate concern?"

---

Key Principles

• One question at a time — never bundle clarifying questions
• Design lives in the ADR — not in separate spec files
• OBPI co-creation is mandatory for canonical ADRs — never deferred
• Pool entries are stubs — design detail goes in canonical ADRs, not pool files
• gz-adr-evaluate is not optional — it catches weak intent before implementation begins
• YAGNI — remove scope that isn't needed for the current decision