tvproductions/gzkit / .agents/skills/gz-complexity-distill
gz-complexity-distill
VerifiedUse when the operator says "run distillation" or "refresh complexity corpus", or a distillation pass is due.
gz-complexity-distill
Operator-runnable skill that produces a dated distilled-characteristics document by measuring the gzkit exemplar corpus and joint-authoring the output with the operator. The skill is the canonical operator surface for the four-ADR complexity-doctrine cluster's distillation cadence (ADR-0.0.27 → ADR-0.0.28 → ADR-0.0.29 → ADR-0.0.30).
Self-Escalation (opus-tier). The dialogue with the operator stays in the main session: a subagent cannot ask the operator a question or hear the answer, and what the operator adds is this skill's primary input. When the session model is below opus-tier, you may spawn an
Agentwithmodel="opus"for a bounded drafting or QC track that needs no operator input — pass the operator's words verbatim and the relevant context (ADR IDs, OBPI IDs, prior decisions), and treat what it returns as a draft you verify, not as the operator-facing result.
When to Use
Three triggers, any of which makes a distillation pass due:
- Annual calendar (default). Re-distillation runs once per year. Rationale from ADR-0.0.27 § Decision Cadence: the Python ecosystem evolves on roughly annual cycles; semi-annual is over-eager, biennial risks doctrine staleness.
- Drift signal — advisor verdict-frequency drift > 25% from the baseline of the last distillation. Minimum re-distillation interval of six months to prevent thrashing. The drift comparison is against the distilled-characteristics baseline, not the raw measurement distributions.
- Operator judgment. The operator may also trigger ad-hoc when a ground-breaking project emerges that warrants corpus amendment.
The cadence is itself amendable per OBPI-0.0.27-01's protocol; this skill mechanizes the cadence the parent ADR codifies.
A pass is OBPI work the operator initiates (operator ruling 2026-10-11). A
trigger says a pass is due; it does not start one. ADR-0.0.27 is terminal and
the foundation kind is closed to new authoring, so a recurring pass is proposed
as a Feature Checklist item of a feature ADR and runs through
gz-obpi-pipeline once the operator initiates it (AGENTS.md § OBPI
Acceptance Protocol). This skill is the method inside that OBPI, and the Gate 5
named below is that OBPI's completion attestation, recorded with
gz obpi complete.
Corpus
The corpus list, per-project path filters, pinned commit SHAs, and
rationale for inclusion are the single source of truth at
data/exemplar_corpus.json. This skill does not duplicate that content —
it cites the file by path and lets the destination CLI verb load the
canonical model (gzkit.models.exemplar.load_corpus).
The corpus is operator-curated against the auditable selection
methodology codified at .gzkit/rules/complexity-doctrine.md. Per-project
path filters declare which paths enter the measurement set and which are
excluded with rationale (strategically-complex modules — Django ORM
query compiler, mypy unification core — are correctly excluded).
Methodology
Distillation is an agent-drafted, operator-attested ceremony, not a black-box pipeline. The seam is canonical to gzkit's Operator Economy of Effort doctrine: the agent produces the substantive draft against observed evidence; the operator audits, adds the practitioner-eye observation per metric, and attests at Gate 5.
The six-step joint authoring sequence (binding, from ADR-0.0.27 § Decision):
- Agent runs the measurement pipeline against the pinned-SHA corpus and
loads the resulting baseline artifact at
docs/governance/complexity/baselines/{YYYY-MM-DD}/baseline.json. - Agent drafts metric-aggregate prose per canonical metric (median, p75, p90, p95, p99 with inter-project variance commentary).
- Operator adds the Practitioner-eye observation per metric. The agent never fabricates this block — it is the OEE seam.
- Together, agent + operator author the per-metric triple: numeric boundary (percentile-of-corpus + absolute-number-at-that-percentile), qualitative band (comfortable craft / investigate / refactor), doctrinal frame (Fowler / Martin / Page-Jones / Constantine).
- Agent proposes classifier rule-table updates against the new percentiles; operator audits.
- Agent narrates the diff against the prior distillation (no-op on first run) — any boundary that moved > 10% gets explicit operator narration.
The output document conforms to the OBPI-0.0.27-04 brief shape: a
dated distilled-characteristics document at
docs/governance/complexity/distilled-characteristics-{YYYY-MM-DD}.md
with frontmatter (corpus_revision, baseline_artifact_path,
distillation_date, prior_distillation_path), a per-metric section for
each canonical metric, a "Diff against prior distillation" section, and a
"Citation form" section quoting the citation contract. Previous
distillations are never overwritten — every run produces a new dated
document.
Output Contract
The destination CLI verb writes a new dated distilled-characteristics
document under docs/governance/complexity/. Form on stdout: a
human-readable progress summary naming the corpus revision under
measurement, the baseline artifact path produced, the destination
document path written, and the count of per-metric sections rendered.
Exit 0 on a clean run; exit 3 (policy breach) when the run would
overwrite an existing same-date document (REQ-0.0.27-04-05 no-overwrite
guard); exit 1 on user/config error; exit 2 on system/IO error.
The destination document conforms to OBPI-04's contract: frontmatter,
per-metric triples, cold-start or diff section, citation form. Downstream
foundation ADRs (0.0.28 / 0.0.29 / 0.0.30) cite the document — not the
raw distributions and not the corpus directly — by (file path, section anchor, corpus_revision) tuple.
Workflow
The operator runs:
uv run gz complexity distill --corpus data/exemplar_corpus.json
The verb composes the OBPI-0.0.27-03 measurement pipeline with the
OBPI-0.0.27-04 distillation render and writes a dated
distilled-characteristics-{YYYY-MM-DD}.md under
docs/governance/complexity/. Operator follow-up at Gate 5 fills the
per-metric Practitioner-eye observation placeholders the verb
leaves intact (REQ-0.0.27-04-10 — the OEE seam, the agent never
fabricates that block).
Common invocations (full options + exit codes in the
complexity-distill manpage):
uv run gz complexity distill # default run against canonical corpus
uv run gz complexity distill --no-prior # cold-start (skip prior auto-detect)
uv run gz complexity distill --allow-dated-sibling # write -1 sibling on collision
The verb closed the OBPI-0.0.27-06 waiver path tracked by GHI #400.
References
- Parent ADR: ADR-0.0.27 — Exemplar Corpus Doctrine
(
docs/design/adr/foundation/ADR-0.0.27-exemplar-corpus-doctrine/) - Brief: OBPI-0.0.27-06-distill-skill
- Producer brief: OBPI-0.0.27-04-distillation-pass — defines the output document shape this skill is bound to produce
- Engine:
src/gzkit/complexity/distillation.py— the distillation rendering surface (frozen Pydantic models + render functions) - Corpus:
data/exemplar_corpus.json— the pinned-SHA corpus - Doctrine rule:
.gzkit/rules/complexity-doctrine.md— selection methodology, cadence, citation contract - Vendor mirror sync:
.gzkit/rules/skill-surface-sync.md— edit this canonical file; the vendor mirrors (roster:.gzkit.json§vendors) are emitted bygz agent sync control-surfaces - Output Contract invariant:
.gzkit/rules/tool-skill-runbook-alignment.mdInvariant 3 — destination verb's default form must honor this skill's Output Contract section
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 |