gz-justify

Pre-execution reasoning walkthrough. Run it when scope is unclear, when an integration point is unresolved, when you are relying on a surface you have not read, or when a prior evaluation (gz-adr-evaluate) flagged structural weakness. The verb renders a grounded scaffold from anchor evidence; the skill instructs you to fill it honestly, not to invent.

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.

Purpose

Agents proceed on unstated assumptions instead of reading or asking more than they break any other behavioral rule (AGENTS.md § Operator Doctrine: a search is not a read; stop and ask the operator in case of uncertainty). The cost is confident-wrong-direction work — implementations that burn context and get discarded because an unstated assumption was wrong.

gz justify <anchor> closes the loop mechanically. It:

• Resolves an anchor (GHI, OBPI, or literal draft) and gathers five sources of evidence — matching rules, ledger events, recent commits, related anchors, and the regression taxonomy.
• Renders an 8-section scaffold whose first line is the YAML frontmatter delimiter ---, with each reasoning block pre-populated with the gathered evidence and a _[To be filled]_ prompt.
• Validates the filled walkthrough on the return trip via gz justify validate <file>.

This skill is the operator-facing ritual that turns the verb into discipline: it tells you when to invoke, how to fill, and what counts as fabrication.

Common Rationalizations

Each row pairs the rationalization with the honest rebuttal.

Rationalization	Rebuttal
"I already understand the brief — writing a walkthrough is busywork."	If you understood the brief you could fill all eight sections in under three minutes. Do so, and you have evidence. Skip, and you have a story.
"The anchor is obvious; I'll justify later."	Later means after a wrong-direction pass has already been committed. The walkthrough's value is pre-execution; post-hoc it is narrative.
"My previous anchor is similar enough."	Similar is not the same. Rerun justify on this anchor; let the evidence tell you what's different.
"I'll fill it in if the operator asks."	Then the walkthrough is theater for the operator, not evidence for you. Fill it for your own execution.

Red Flags

Stop if any of the following apply. Each is a defect, not a judgment call.

Red Flag	Why it's a defect
You are about to fabricate a filled reasoning block — invent a rule citation, synthesize a commit reference, paraphrase an anchor quote that isn't actually there.	Fabrication poisons the trust chain. The walkthrough becomes a reporting-pathway artifact (Lindsey et al. 2025) that is structurally separate from execution — exactly the failure mode docs/governance/arb-middleware.md § Why receipts, not narrative names. If the evidence isn't there, write _[No evidence in gathered sources]_ instead of inventing.
You are copy-pasting reasoning from a previous walkthrough and retargeting it to this anchor.	Cross-anchor reuse is the adjacent rationalization the CLI was built to prevent. If two anchors really do share reasoning, cite the first walkthrough's artifact path — don't restate the reasoning.
You are filling blocks before reading the anchor body the CLI embedded in Section 1.	Section 1 pre-populates anchor-body citations specifically so your reasoning can ground in them. Skipping the read step is the defining move of vibe coding (see AGENTS.md § DO IT RIGHT, items 2 (6b) and 5 (6e)).
You are declaring the walkthrough complete without running gz justify validate <file>.	The validator checks structural completeness (no unfilled ordinals). Skipping it means the artifact can silently ship with _[To be filled]_ still in the body.
You feel sure, but cannot point to a specific surface you read that supports the plan.	Subjective confidence without evidence is the rationalization the walkthrough exists to neutralize. Run the CLI anyway; if the walkthrough genuinely takes 90 seconds because the anchor is that clear, you've spent 90 seconds and have a cite-able artifact.

Persona

Active persona: main-session — craftsperson, governance-aware, whole-file-reasoning, direct. See .gzkit/personas/main-session.md. The walkthrough is whole-file-reasoning applied to a single change instance: you see the anchor and its evidence as one unit before you touch a line.

Trust Model

gz justify is Layer 1 — evidence gathering. The CLI does not make reasoning claims on your behalf; it assembles the grounding surface you need to make them. Filling the walkthrough is co-authorship between the CLI (evidence) and the agent (reasoning). The filled artifact becomes durable evidence consumable by downstream governance — plan-audit receipts, OBPI brief verification, ADR closeout walkthroughs.

The contract is one-way: the CLI promises byte-stable scaffolds (identical input produces identical output; see gzkit.justify.walkthrough.render_markdown). You promise that every filled block grounds in the evidence the CLI gathered.

Invocation

Default rendering (stdout):

uv run -m gzkit justify GHI-195
uv run -m gzkit justify OBPI-0.0.19-04-skill-and-upstream-integrations

Persist the scaffold (auto-path artifacts/justify/<slug>-<timestamp>.md):

uv run -m gzkit justify GHI-195 --save

Persist to an explicit path:

uv run -m gzkit justify OBPI-0.0.19-04 --output artifacts/justify/obpi-04-pre-exec.md

Literal draft (anchor not yet booked):

uv run -m gzkit justify --draft "consider extracting the parser into its own module" --draft-slug "extract-parser" --save

Validate a filled walkthrough on return:

uv run -m gzkit justify validate artifacts/justify/obpi-04-pre-exec.md
uv run -m gzkit justify validate artifacts/justify/obpi-04-pre-exec.md --json

The CLI rejects ADR anchors (ADR-X.Y.Z) by design — ADRs are governance packages, not change instances. Invoke on the tracking GHI or an OBPI under the ADR.

Answering an ADR evaluation is narrower (ADR-0.0.26 Decision 2, GHI #996). When gz validate --evaluation-justify-binding refuses an ADR, only a walkthrough whose own frontmatter names that ADR discharges it: an OBPI under the ADR (justify OBPI-X.Y.Z-NN --save), or — when the ADR has no OBPI yet — a draft slug of the ADR id with dots as dashes (justify --draft "<what the evaluation found>" --draft-slug adr-x-y-z --save). A tracking-GHI walkthrough does not, because the GHI's link to the ADR lives on GitHub (operator ruling 2026-09-14). The walkthrough must also be complete and generated after the evaluation; the filename carries no weight.

When to Use

Invoke gz justify at any of the following moments. The upstream skills surface these automatically so you don't have to remember.

• OBPI pipeline Stage 1→2, when the gz-obpi-pipeline skill's Justification Gate finds an ambiguous scope boundary, an unresolved integration point, or a surface the plan relies on that you have not read.
• After a gz-adr-evaluate run triggers the evaluation-justify binding — any dimension below threshold or enough red-team challenges fired. The gz-adr-evaluate skill appends a footer pointing to an OBPI under the ADR, or the ADR's draft slug when it has no OBPI.
• Before promoting a pool ADR into active work — run justify on the tracking GHI to surface hidden ambiguity before you commit the lane/kind.
• Mid-pipeline, when scope feels ambiguous — if you are about to guess at whether a change crosses brief boundaries (see AGENTS.md § Defect-fix routing), run justify on the in-flight OBPI and fill the scope boundary section before continuing.
• At your own discretion, when a task description contains hedging language ("probably", "should be able to", "I think") or when an operator request is ambiguous. The walkthrough is cheap; the wrong-direction pass is expensive.

Do not use it for governance ceremony steps that already have dedicated skills (plan-audit, OBPI completion, closeout). Those surfaces already produce receipts. gz justify is the pre-execution reasoning layer, not a substitute for any of them.

Procedure

1. Invoke the CLI on the anchor. Pick the most specific anchor available: an OBPI if one exists, otherwise the tracking GHI, otherwise --draft + --draft-slug. Use --save if you want the artifact persisted to artifacts/justify/, --output <path> if you want an explicit destination.
2. Read the rendered scaffold in full before touching a line. Section 1 contains anchor-body citations, section 7 contains ledger/rule/commit evidence. These are your grounding sources. If a section's evidence list is empty, note it — you may need to gather evidence yourself before filling that section honestly.
3. For each _[To be filled]_ block, use the Edit tool to replace the placeholder with grounded reasoning. Every filled block MUST cite evidence the CLI gathered or evidence you verified by reading the anchor body. If a section has no supporting evidence in the gathered sources and none available elsewhere, write _[No evidence in gathered sources]_ and move on — do not invent.
4. Preserve the 8-section structure. Do not add sections, rename headings, or collapse sections. The downstream validator parses by ordinal.
5. Save the artifact via --save or --output, or commit the edited file in place if you rendered to an explicit path.
6. Run the round-trip validator — uv run -m gzkit justify validate <file>. Exit 0 means every section is filled. Exit 1 lists unfilled ordinals; go back to step 3 for each.
7. Cite the artifact in downstream governance. Plan receipts, OBPI brief Key Proof sections, and ADR defense briefs all accept walkthrough paths as evidence. The artifact is the durable proof that the pre-execution reasoning happened.

The whole loop should take 3-10 minutes on a well-understood anchor and 15-30 minutes on an ambiguous one. If it takes less than 3 minutes, you probably rationalized through step 2 — re-read the scaffold before committing.

Acceptance Criteria

The skill's own completion contract — the state in which a walkthrough can be cited as evidence.

• The walkthrough artifact exists at a known path (either artifacts/justify/<slug>-<ts>.md or an explicit --output destination).
• uv run -m gzkit justify validate <file> exits 0 (every section is filled).
• No filled reasoning block contains fabricated citations or paraphrased-into-existence evidence. Empty-source sections are marked _[No evidence in gathered sources]_ rather than invented.
• The artifact path is cited in the consuming governance surface (plan receipt, OBPI brief Key Proof, ADR defense brief, etc.).

Related Skills

• gz-adr-evaluate — sources the triggered-evaluation footer that routes to uv run -m gzkit justify OBPI-<X.Y.Z>-<NN> --save, or the ADR's draft slug.
• gz-obpi-pipeline — Stage 1→2 Justification Gate routes here on an ambiguous scope boundary, an unresolved integration point, or an unread surface.
• gz-plan-audit — downstream consumer; filled walkthrough artifacts are acceptable evidence in plan receipts.
• gz-design — upstream; if the anchor is a draft concept, run gz-design first to book the artifact, then gz-justify on the booked identifier.

Authoring-time complexity hints (ADR-0.0.30-05)

When gz justify is invoked on an OBPI whose ## Allowed Paths section includes .py files, the rendering pipeline automatically invokes the OBPI-03 authoring engine (gzkit.complexity.authoring.engine.analyze) on each matching path. If advise-band crossings are found, a ### Authoring-time complexity hints sub-heading is injected into the scaffold, listing per-hint: metric, precedence band, archetype, doctrinal-frame headline, recommended-move headline, and file:line range.

When the heading appears: OBPI has .py allowed-paths AND the engine finds at least one advise-band crossing.

When the heading is absent: No .py allowed-paths, no crossings, or engine failure. All three cases produce silent absence — not an empty heading.

Fail-open: If the authoring engine raises (e.g., distilled-characteristics document missing at .gzkit/rules/complexity-thresholds.json), gz justify completes normally, the hints heading is omitted, and a structured warning is appended to .gzkit/insights/justify-failures.jsonl. The failure never blocks the walkthrough.

Closed forward reference: This integration closes the ADR-0.0.19 ↔ ADR-0.0.30 cross-reference. Operators no longer need to run gz justify and gz complexity guide separately and stitch the outputs together — the hints surface inline within the pre-execution reasoning scaffold.

Related ADRs

• ADR-0.0.19 — Pre-execution reasoning walkthrough. This skill is the operator-facing expression of that ADR's capability.
• ADR-0.0.30 — Complexity authoring guidance. OBPI-05 of this ADR adds the hints integration to this skill (additive only).