| 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-07-25T00:00:00.000Z" |
| metadata | {"skill-version":"0.1.2","govzero-framework-version":"v6","govzero_layer":"Layer 3 - File Sync"} |
| gz_command | complexity advise |
| model | opus |
gz-complexity-advisor
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 installed, the auto-chain hook (OBPI-0.0.29-05) fires
gz complexity advise --auto-chain automatically on a non-zero
xenon-as-gate exit at pre-commit time. It is not installed in this
repo — .pre-commit-config.yaml carries the plain xenon-complexity
hook, not the composite complexity-advisor-auto-chain id, so the
advisor must be invoked by hand after a xenon failure.
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, crossing_band, crossing_value, archetype,
doctrinal_frame, proof, recommended_move, intrinsic_attestation.
Commands
gz complexity advise <path>
gz complexity advise <path> --json
gz complexity advise <path> --auto-chain
gz complexity advise <file_path>:<qualname> --attest-intrinsic \
--reason "<why this complexity is intrinsic>" --attestor "<name>"
Related
- Manpage:
docs/user/manpages/complexity-advise.md
- Runbook:
docs/user/runbook.md § Governance 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
