Skip to content

tvproductions/gzkit / .agents/skills/gz-complexity-guide

gz-complexity-guide

Verified

Use 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:

  1. Authoring-time review — preview hints for a file or directory while editing it.
  2. 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, or approaching_warn in 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

SurfaceSkillBands reportedBlocks?
Authoring-time hintsgz-complexity-guide (this skill)adviseNever
Trigger-time diagnosisgz-complexity-advisoradvise, warn, blockExits 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)
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 implementationStars: 319kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 319kUpdated Claude CodeCodexVerifiedInstall
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 fallbackStars: 319kUpdated Claude CodeCodexVerifiedInstall
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 alwaysStars: 319kUpdated Claude CodeCodexVerifiedInstall