/gz-complexity-distill¶
Run a complexity distillation pass against the exemplar corpus to refresh the distilled-characteristics doctrine. Invoke at the cadence triggers below (annual calendar, advisor verdict-frequency drift > 25% from baseline, or operator judgment for a ground-breaking project).
Purpose¶
/gz-complexity-distill is the operator-facing 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). Distillation produces a dated
distilled-characteristics document at
docs/governance/complexity/distilled-characteristics-{YYYY-MM-DD}.md,
authored jointly by the agent (metric-aggregate prose) and the operator
(practitioner-eye observation per metric) under foundation-kind brief-level
Gate 5 attestation per OBPI-0.0.27-04's contract.
When to Use¶
Three triggers, any of which fires a distillation pass:
- Annual calendar (default). Re-distillation runs once per year.
- Drift signal. Advisor verdict-frequency drift > 25% from the baseline of the last distillation, with a minimum 6-month re-distillation interval to prevent thrashing.
- Operator judgment. Ad-hoc invocation when a ground-breaking project emerges that warrants corpus amendment.
What to Expect¶
The skill reads its canonical execution contract from
.gzkit/skills/gz-complexity-distill/SKILL.md (mirrored into
.claude/skills/, .agents/skills/, and .github/skills/ by
gz agent sync control-surfaces). Follow the agent-facing instructions
in that file for the joint authoring sequence, the per-metric triple
shape, and the no-overwrite preservation discipline.
Invocation¶
The destination CLI verb is deferred under
GHI #400 per
OBPI-0.0.27-06 REQUIREMENT 9 waiver path. Until #400 lands, the
operator can invoke the underlying engine directly via
src/gzkit/complexity/distillation.py (render_document,
render_diff_section, render_metric_triple, _DOCTRINAL_FRAMES),
following OBPI-0.0.27-04's evidence as the worked-example reference.
Output Contract¶
The destination 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 codes follow the
clig.dev / .claude/rules/cli.md standard: 0 success, 1 user/config
error, 2 system/IO error, 3 policy breach (e.g. would overwrite an
existing same-date document — REQ-0.0.27-04-05 no-overwrite guard).
Supporting Files¶
| File | Role | Read/Write |
|---|---|---|
.gzkit/skills/gz-complexity-distill/SKILL.md |
Canonical skill contract | Read |
.claude/skills/gz-complexity-distill/SKILL.md |
Claude mirror | Read |
.agents/skills/gz-complexity-distill/SKILL.md |
Codex mirror | Read |
.github/skills/gz-complexity-distill/SKILL.md |
Copilot mirror | Read |
data/exemplar_corpus.json |
Pinned-SHA corpus (single source of truth) | Read |
src/gzkit/complexity/distillation.py |
Engine (render functions, frozen models) | Read |
docs/governance/complexity/distilled-characteristics-{date}.md |
Output document | Write |
Related Skills and Commands¶
| Related | Relationship |
|---|---|
/gz-justify |
Pre-execution reasoning if methodology trade-offs feel ambiguous |
/gz-obpi-pipeline |
Distillation pass runs as an OBPI under foundation-kind brief-level Gate 5 |
| skills index | Browse the full skill catalog |
| governance runbook | Workflow context |