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.3.1" govzero-framework-version: "v6" lifecycle_state: active owner: gzkit-governance last_reviewed: 2026-05-21 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

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 (foundation/feature). Foundation = app/system invariant (0.0.x versions only). Feature = release-carrying capability. Use the invariance test to resolve 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.

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

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