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 Agent with model="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:

1. 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.
2. 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.
3. 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):

1. 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.
2. Agent drafts metric-aggregate prose per canonical metric (median, p75, p90, p95, p99 with inter-project variance commentary).
3. Operator adds the Practitioner-eye observation per metric. The agent never fabricates this block — it is the OEE seam.
4. 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).
5. Agent proposes classifier rule-table updates against the new percentiles; operator audits.
6. 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 by gz agent sync control-surfaces
• Output Contract invariant: .gzkit/rules/tool-skill-runbook-alignment.md Invariant 3 — destination verb's default form must honor this skill's Output Contract section