tvproductions/gzkit / .agents/skills/gz-complexity-advisor
gz-complexity-advisor
VerifiedUse when the operator says "preview complexity advisor", "complexity diagnosis" or "intrinsic complexity attestation".
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
- Ad-hoc preview-before-fail — see the diagnosis for a file before the ceiling gate refuses a commit.
- 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.
- Irreducible complexity — the operator wants to record that a function's complexity is intrinsic.
Ad-hoc preview
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-intrinsictakes<file_path>:<qualname>as the path, plus--reasonand--attestor(a handle, never a real name; an omitted--attestortakes.gzkit.json§authorship.attestor_handle). It refuses a function that crosses no band and refuses without an interactive terminal. The operator typesATTESTto confirm, and it appends anintrinsic-complexity-attestationevent to the ledger, whose shapegz validate --intrinsic-attestationchecks. Later advisor runs honour it, matched on the resolved file path and qualname.
The operator runs --attest-intrinsic themselves; the agent drafts the reason.
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: 197k | 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 |