Menu
Preview authoring-time complexity hints before committing. Use when the operator says "authoring-time complexity hint", "complexity guide preview", "preview before commit", or "advise-band hints".
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Validate and stage a candidate rendition from the corpus via gz content compose. Use when the agent has made compression decisions (drop/combine/rewrite of compressible corpus entries toward the declared setpoint) and wants the tool to validate invariant-floor compliance, compute byte evidence, write the candidate artifact, and emit a ledger event.
Enter and exit the MX Maintenance Hangar — operator's interface to gz mx. Use when entering the hangar to perform governance repair, checking hangar status mid-session, or cleanly exiting when repair is complete. Operator operates the skill; the skill invokes gz mx; nobody shells out.
Create and resume session handoff documents for agent context preservation across engineering sessions.
Create and resume session handoff documents for agent context preservation across engineering sessions.
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".
Cross the airlock membrane — the entry/exit gate every unit of work passes through (ADR-0.33.0). Use to inspect a target's seam-map before touching it (`gz airlock in`), account for what a transit disturbed (`gz airlock out`), or make a governed ad-hoc reconnaissance entry with light repair at most (`gz permitted-entry`). Diagnostic-only for now — a staged posture, not the declared end state; never writes L1 canon.
| name | gz-complexity-guide |
| description | Preview authoring-time complexity hints before committing. Use when the operator says "authoring-time complexity hint", "complexity guide preview", "preview before commit", or "advise-band hints". |
| category | code-quality |
| lifecycle_state | active |
| owner | gzkit-governance |
| last_reviewed | "2026-07-25T00:00:00.000Z" |
| metadata | {"skill-version":"0.1.2","govzero-framework-version":"v6","govzero_layer":"Layer 3 - File Sync"} |
| gz_command | complexity guide |
| model | sonnet |
Operator-runnable skill wrapping the gz complexity guide CLI verb
(ADR-0.0.30, OBPI-0.0.30-01). The guide is the authoring-time hint surface
for the four-ADR complexity-doctrine cluster (ADR-0.0.27 corpus /
0.0.28 thresholds / 0.0.29 advisor / 0.0.30 authoring-guidance). Use this
skill before running gz complexity advise or attempting a commit — it
surfaces functions in the advise band while you are actively editing, so
refactor decisions land at design time rather than at gate time.
The guide is the first-stop authoring surface for complexity hints. Use it at two operator moments:
warn or block.If a function has already crossed into warn or block, use the trigger-time
advisor instead (see gz-complexity-advisor in § Related).
The primary operator moment: invoke the guide directly while editing to preview which functions are approaching the warn threshold. The guide never blocks — it surfaces hints for information only.
# Ad-hoc authoring-time review
gz complexity guide src/gzkit/commands/validate.py
gz complexity guide src/gzkit/ --json
Default output is in-line hint prose — one block per function in the advise
band. Each block names the archetype, the position within the advise band
(approaching or approaching_warn), the one-line doctrinal-frame headline,
and the recommended move. The --json flag emits the canonical AuthoringHint
Pydantic serialization for machine consumption.
Declared form: in-line hint prose (default human-readable).
Each hint block in the default output contains:
long_parameter_list)approaching or approaching_warn)Machine-readable mode: --json emits the canonical AuthoringHint
Pydantic serialization as a JSON array. Each element is a frozen Pydantic
model with fields: metric, precedence_band, crossing_value,
archetype, doctrinal_frame_headline, recommended_move, plus the
editor-navigation triple file_path, start_line, end_line.
| Surface | Skill | Trigger | Blocks? |
|---|---|---|---|
| Authoring-time hints | gz-complexity-guide (this skill) | Operator-invoked while editing | Never |
| Trigger-time diagnosis | gz-complexity-advisor | Xenon-as-gate at pre-commit | At block band |
Use the guide before commit for design-time decisions. Use the advisor
at commit time when xenon-as-gate fires or to preview a full structured
diagnosis with proof ranges and doctrinal frame citations. The two skills share
the AdvisorDiagnosis schema at the architecture level (the guide projects to
the lighter AuthoringHint shape via OBPI-0.0.30-03), but serve different
operator moments.
See .gzkit/skills/gz-complexity-advisor/SKILL.md for the trigger-time surface
(ADR-0.0.29).
.gzkit/skills/gz-complexity-advisor/SKILL.md (ADR-0.0.29)docs/user/manpages/complexity-guide.mddocs/user/runbook.md § Governance Doctrine Surfacesdocs/design/adr/foundation/ADR-0.0.30-complexity-authoring-guidance/.gzkit/rules/complexity-thresholds.json (ADR-0.0.28)