gz-design

name	gz-design
persona	main-session
description	Collaborative design dialogue that produces GovZero ADR artifacts. Use when exploring a new feature, capability, or architectural change before implementation — replaces superpowers brainstorming for this project. Triggers on "design X", "let's design", "brainstorm X", "I want to build X", "gz-design".
category	adr-lifecycle
metadata	{"skill-version":"1.4.0","govzero-framework-version":"v6"}
lifecycle_state	active
owner	gzkit-governance
last_reviewed	"2026-07-28T00:00:00.000Z"
model	opus

gz-design

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

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-design/SKILL.md for the full workflow. Relay the subagent's output to the operator.

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.

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. If this is an in-flight defect fix per AGENTS.md § Defect-fix routing thresholds (≤10 source lines, ≤2 source files, in-flight trigger, ≥3 recent fix(...) precedents in the 60-day window, unit-test coverage viable), route to a direct fix(<scope>): … (GHI #N) commit instead of scaffolding 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 Rationale or Consequences 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 only; Heavy = gates 1–5)
• 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, Rationale, 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/{series}/ADR-{id}-{slug}/. Please review it and confirm before we scope OBPIs."

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: invoke gz-obpi-specify to scope OBPIs, then gz-plan for the first OBPI.

Do NOT invoke any implementation skill. gz-obpi-specify and gz-plan are 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