tvproductions/gzkit / .agents/skills/gz-complexity-guide
gz-complexity-guide
VerifiedUse when the operator asks for an authoring-time complexity hint or a complexity guide preview before commit.
gz-complexity-guide
Run gz complexity guide, the authoring-time hint 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 and
reports only the functions in the advise band of
.gzkit/rules/complexity-thresholds.json, the band below warn, so a refactor
decision lands while the code is being written. It never blocks: it exits 0
whatever it finds, and exits 1 only on a user error such as a missing path.
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.
This skill ends at the hints. It does not refactor.
When to Use
The guide is the first-stop authoring surface for complexity hints:
- Authoring-time review — preview hints for a file or directory while editing it.
- Before a commit — catch functions growing toward
warn.
A function already at warn or block produces no hint here; use
gz-complexity-advisor for it.
uv run gz complexity guide src/gzkit/commands/validate_cmd.py
uv run gz complexity guide src/gzkit/ --json
A path is required unless --server is given. --server starts a
JSON-over-stdio server for editors (Content-Length framing; initialize,
analyze with a file_path, shutdown), whose envelope is
src/gzkit/schemas/authoring_guide_protocol.json.
Output Contract
Declared form: in-line hint prose (default human-readable). Each hint is a
block headed ── <file>:<start>-<end> ── with four lines:
- Archetype — the refactor archetype name
- Band —
approaching, orapproaching_warnin the upper half of the advise band - Guidance — the doctrinal-frame headline
- Move — the recommended-move excerpt
The line range is the diagnosed function's full span. No archetype rule in
data/advisor_archetype_rules.json covers the advise band, so every hint's
archetype is unclassified, and its guidance and move are the metric's general
ones.
Machine-readable mode: --json emits an array of AuthoringHint objects
with metric, precedence_band, crossing_value, archetype,
doctrinal_frame_headline, recommended_move, file_path, start_line and
end_line.
Trigger-Time vs. Authoring-Time
| Surface | Skill | Bands reported | Blocks? |
|---|---|---|---|
| Authoring-time hints | gz-complexity-guide (this skill) | advise | Never |
| Trigger-time diagnosis | gz-complexity-advisor | advise, warn, block | Exits 3 on block |
Both are run by hand in this repository; the advisor's auto-chain pre-commit hook is not installed.
Related
- Sister skill:
.gzkit/skills/gz-complexity-advisor/SKILL.md(ADR-0.0.29) - Manpage:
docs/user/manpages/complexity-guide.md - Runbook:
docs/user/runbook.md§ Governance Doctrine Surfaces - Parent ADR:
docs/design/adr/foundation/ADR-0.0.30-complexity-authoring-guidance/ - Threshold table:
.gzkit/rules/complexity-thresholds.json(ADR-0.0.28)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |