gz-complexity-advisor

name: gz-complexity-advisor description: Preview complexity advisor diagnosis, understand auto-chain context, or check intrinsic complexity attestation guidance. Use when the operator says "preview complexity advisor", "complexity diagnosis", "advisor recommendation", "what does the advisor say", or "intrinsic complexity attestation". category: code-quality lifecycle_state: active owner: gzkit-governance last_reviewed: 2026-05-22 metadata: skill-version: "0.1.1" govzero-framework-version: "v6" govzero_layer: "Layer 3 - File Sync" gz_command: complexity advise model: opus

Operator-runnable skill wrapping the gz complexity advise CLI verb (ADR-0.0.29, OBPI-0.0.29-03). The advisor is the trigger-time doctrinal-frame 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). Every diagnosis cites the active distilled-characteristics document and the canonical ThresholdTable, carries a proof field linking to responsible AST nodes / line ranges, and respects the two-path intrinsic-complexity attestation.

When to Use

Three operator moments trigger this skill — any one fires the advisor:

Ad-hoc preview-before-fail — the operator wants to preview advisor diagnosis on a file before xenon-as-gate would fail it at commit time.
Auto-chain context — the operator wants to understand what happened when xenon-as-gate failed and the advisor auto-fired.
Intrinsic-complexity attestation guidance — the operator wants to know when to use @intrinsic_complexity (decorator) vs --attest-intrinsic (commit-time flag) for irreducibly complex functions.

Operator Moments

Ad-hoc preview-before-fail

The operator invokes the advisor directly to preview diagnosis before commit. This is the OEE-aligned preview-before-fail moment: the developer sees the full diagnosis (archetype, authority, proof range, recommended move) without waiting for xenon-as-gate to trip.

gz complexity advise src/gzkit/commands/validate.py
gz complexity advise src/gzkit/ --json

Default output is structured prose with a per-diagnosis block. The --json flag emits the canonical AdvisorDiagnosis Pydantic serialization for machine consumption.

Auto-chain context

When xenon-as-gate exits non-zero at pre-commit time, the auto-chain hook (OBPI-0.0.29-05) fires gz complexity advise --auto-chain automatically. The --auto-chain flag signals that the invocation is trigger-fired (not operator-initiated), producing a condensed presentation default suited to the commit-time moment rather than the verbose preview the ad-hoc path emits.

The auto-chain pathway preserves the existing SKIP-bypass guard wiring from the complexity-reduction-xenon chore — modules previously marked with a SKIP annotation continue to bypass both xenon-as-gate and the advisor.

Intrinsic-complexity attestation

For functions whose complexity is irreducibly algorithmic (e.g. CC=24 in a query optimizer's join-cost calculator), two attestation paths exist:

@intrinsic_complexity(reason=..., attestor=...) — decorator applied to the function definition. The advisor honors this at diagnosis time and skips the function. Use for known-irreducible functions whose complexity will not change.
--attest-intrinsic — commit-time flag passed to gz complexity advise. Records the attestation to .gzkit/ledger.jsonl via canonical event emission with Gate 5 follow-up persistence. Use for newly-discovered irreducible complexity where amending the source with a decorator is premature.

Both paths land at brief-level Gate 5; neither produces a silent escape hatch. The decorator path pre-attests (skips at diagnosis time); the commit-time path post-attests (records and schedules review).

Timeout and Failure Handling

The advisor's pre-commit hook (OBPI-0.0.29-09) wraps the invocation in a configurable timeout (default 30s). On timeout the hook fails open: the commit proceeds and a warning is logged to .gzkit/insights/advisor-failures.jsonl for later operator review. The fail-open is deliberate — blocking commits on advisor failure is worse than letting them through with a logged warning.

Output Contract

Declared form: structured prose (default human-readable).

Each diagnosis block in the default output contains:

Metric — the measured value and the metric name (e.g. radon_cc=14)
Crossing band — which threshold band was crossed (warn or block)
Archetype — the canonical refactor archetype (e.g. Long Parameter List, Arrowhead, Switch-on-Type)
Doctrinal frame — the authority citation (Fowler / Martin / Page-Jones / Constantine) with chapter/page anchor
Proof range — file path + line range + AST node descriptor linking to the responsible code
Recommended move — the refactoring operation the authority prescribes

Machine-readable mode: --json emits the canonical AdvisorDiagnosis Pydantic serialization as a JSON array. Each element is a frozen Pydantic model with fields: metric, value, band, archetype, doctrinal_frame, proof, recommended_move.

Commands

# Ad-hoc preview (verbose structured prose)
gz complexity advise <path>

# Machine-readable output
gz complexity advise <path> --json

# Auto-chain mode (condensed, trigger-fired)
gz complexity advise <path> --auto-chain

# Intrinsic attestation at commit time
gz complexity advise <path> --attest-intrinsic

Manpage: docs/user/manpages/gz-complexity-advise.md
Runbook: docs/user/runbook.md § Complexity doctrine surfaces
Parent ADR: docs/design/adr/foundation/ADR-0.0.29-complexity-advisor/
Threshold table: .gzkit/rules/complexity-thresholds.json (ADR-0.0.28)
Distilled characteristics: data/exemplar_corpus.json + distillation output (ADR-0.0.27 OBPI-04)
Complexity distill skill: .gzkit/skills/gz-complexity-distill/SKILL.md

gz-complexity-advisor