tvproductions/gzkit / .agents/skills/gz-complexity-advisor
gz-complexity-advisor
VerifiedUse when the operator says "preview complexity advisor", "complexity diagnosis" or "intrinsic complexity attestation".
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 5.2 KB |
SKILL.md
View on GitHub---
name: gz-complexity-advisor
description: Use when the operator says "preview complexity advisor", "complexity diagnosis" or "intrinsic complexity attestation".
category: code-quality
lifecycle_state: active
owner: gzkit-governance
last_reviewed: 2026-10-22
metadata:
skill-version: "0.2.6"
govzero-framework-version: "v6"
govzero_layer: "Layer 3 - File Sync"
gz_command: complexity advise
model: opus
---
# gz-complexity-advisor
Run `gz complexity advise`, the trigger-time surface of the complexity-doctrine
cluster (ADR-0.0.27 corpus, 0.0.28 thresholds, 0.0.29 advisor, 0.0.30
authoring guidance). It measures per-function `lizard_ccn` (Lizard's
cyclomatic score) in a file or directory, and for every function that crosses an `advise`, `warn` or `block`
band of `.gzkit/rules/complexity-thresholds.json` it emits a diagnosis:
archetype, doctrinal frame, proof ranges and recommended move. It exits 3 when
any crossing is in the `block` band and 0 otherwise. A function whose body sits on its `def` line is not measured (Lizard skips it); the verb names it on stderr as `not measured:` rather than inventing a score.
The table's `lizard_ccn` bands are stricter than the C/C/C ceiling the
pre-commit hook enforces (`gz validate --complexity-ceiling`) (`.gzkit/rules/pythonic.md` § Size Limits & Refactoring), so a tree
that commits cleanly can still exit 3 here.
This skill ends at the diagnosis. It does not refactor, and it does not
attest on the operator's behalf.
## When to Use
1. **Ad-hoc preview-before-fail** — see the diagnosis for a file before the
ceiling gate refuses a commit.
2. **After a ceiling failure** — the auto-chain hook is not installed in this
repository, so run the advisor by hand on the files the gate named.
3. **Irreducible complexity** — the operator wants to record that a
function's complexity is intrinsic.
## Ad-hoc preview
```bash
uv run gz complexity advise src/gzkit/commands/validate_cmd.py
uv run gz complexity advise src/gzkit/ --json
```
## Output Contract
**Declared form:** structured prose (default human-readable). Each diagnosis
prints `Metric | Band | Value | Archetype`, then `Authority`, `Citation`,
`Excerpt`, `Recommended`, and `File` with the line range and node kind,
followed by the function's source. `--auto-chain` selects the condensed
commit-time presentation instead.
**Machine-readable mode:** `--json` emits an array of `AdvisorDiagnosis`
objects with `metric`, `crossing_band`, `crossing_value`, `archetype`,
`doctrinal_frame`, `proof`, `recommended_move` and `intrinsic_attestation`.
When no archetype rule in `data/advisor_archetype_rules.json` matches a
crossing, the archetype is `unclassified`: the doctrinal frame and move are the
metric's general ones, not an archetype's. No rule covers the `advise` band, so
every advise-band crossing is `unclassified`.
## Auto-chain hook
`.pre-commit-config.yaml` runs the plain ceiling gate (`complexity-ceiling`). The composite hook
`complexity-advisor-auto-chain` (OBPI-0.0.29-05) is installed only by
`uv run python -m gzkit.hooks.install_complexity_advisor`. Once installed, it
runs the ceiling gate and, on failure, diagnoses the staged Python files in its own
process, printing to stderr and failing the commit on a `block` crossing. It
wraps the advisor in a timeout, `.gzkit.json` § `advisor_timeout_seconds`
(30 seconds when unset) unless the hook is run with `--timeout`; on timeout
it lets the commit through and appends a record to
`.gzkit/insights/advisor-failures.jsonl`. Skip it for one commit with
`SKIP=complexity-advisor-auto-chain git commit`.
## Intrinsic-complexity attestation
Two paths exist. Either one makes `gz complexity advise` and the auto-chain
hook print `intrinsic complexity attested by '<attestor>' on <date>: <reason>`
for that function instead of a diagnosis, so it no longer fails the run.
- **`@intrinsic_complexity(reason=..., attestor=...)`** on the function, with
both arguments as non-empty string literals: the advisor reads the
declaration from the parsed source, never importing the file. Use it for
known-irreducible functions whose complexity will not change.
- **`--attest-intrinsic`** takes `<file_path>:<qualname>` as the path, plus
`--reason` and `--attestor` (a handle, never a real name; an omitted
`--attestor` takes `.gzkit.json` § `authorship.attestor_handle`). It refuses
a function that crosses no band and refuses without an interactive terminal.
The operator types `ATTEST` to confirm, and it appends an
`intrinsic-complexity-attestation` event to the ledger, whose shape
`gz validate --intrinsic-attestation` checks. Later advisor runs honour it,
matched on the resolved file path and qualname.
The operator runs `--attest-intrinsic` themselves; the agent drafts the reason.
```bash
uv run gz complexity advise src/gzkit/commands/adr_audit.py:_collect_obpi_findings --attest-intrinsic \
--reason "<why this complexity is intrinsic>" --attestor g0
```
## Related
- Manpage: `docs/user/manpages/complexity-advise.md`
- Runbook: `docs/user/runbook.md` § Governance Doctrine Surfaces
- Sister skill: `gz-complexity-guide` (authoring-time hints)
- Parent ADR: `docs/design/adr/foundation/ADR-0.0.29-complexity-advisor/`
- Threshold table: `.gzkit/rules/complexity-thresholds.json` (ADR-0.0.28)
- Distillation: `gz-complexity-distill`
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |