gtkb-hygiene-investigation

name

gtkb-hygiene-investigation

description

Run a repeatable, full-coverage GT-KB architecture/hygiene investigation using the proven 4-round probe method (parallel focus-area probes -> gap probe -> completeness critic -> adversarial skeptic) with loop-until-dry and explicit decay disclosure. Emits findings against a structured schema, renders a chunked report via the deterministic report generator, and uses the frozen HYG-001..068 baseline registry for lookup and reporting; baseline diff/delta mode is deferred to a follow-on bridge. Use when the owner asks for a hygiene/architecture investigation, a drift/debt census, or a repeat of the GT-KB self-investigation that produced HYG-001..068.

/gtkb-hygiene-investigation

This skill packages the method that produced the GT-KB self-investigation finding corpus (HYG-001..068, frozen in config/governance/hygiene-baseline-registry.toml). It is the orchestration half of the layered repeatable-investigation design chartered by DELIB-FABLE-GRILL-20260610-Q5: a deterministic detector core (FAB-19, separate thread) feeds a reusable orchestration skill (this skill), and a future delta mode keys re-runs to the baseline registry.

The deterministic-services split (DELIB-S312-DETERMINISTIC-SERVICES-PRINCIPLE) places the stable, re-derivable surfaces — the chunked report generator and the baseline-registry loader — in scripts/hygiene/ as testable Python, and keeps probe design, finding quality, and owner-decision routing in this skill where they require model judgment.

This skill body presents identical content to every harness via the cross-harness skill-adapter pipeline (config/agent-control/harness-capability-registry.toml + scripts/generate_codex_skill_adapters.py). The Codex adapter at .codex/skills/gtkb-hygiene-investigation/SKILL.md carries a GTKB-CODEX-SKILL-ADAPTER marker and is generated, not hand-edited; edit this canonical source and regenerate.

When to invoke

• Explicit owner direction — "run a hygiene investigation", "do an architecture/drift census", "repeat the GT-KB self-investigation".
• Periodic re-baseline — when enough has changed since the last frozen baseline that a fresh full-coverage census is warranted (the differential/delta optimization is a deferred follow-on; see below).
• Pre-release hygiene gate — a full-coverage census before a release lane, to surface drift/debt/defects that mechanical gates do not catch.

This skill surfaces findings and routes owner decisions; it does not auto-remediate. Each finding becomes a governed work_items candidate only through the explicit, owner-gated routing below.

Structured findings schema

Every finding the probes produce conforms to this schema (the same shape the loader and report generator consume — scripts/hygiene/hygiene_baseline.py::HygieneFinding). Required fields are marked *.

Field	Meaning
id*	Stable identifier, HYG-NNN, contiguous within a run.
title*	One-line verbatim finding title.
finding_class*	One of defect, debt, decision-needed, drift.
locations	Concrete file/line/path evidence anchors (a list).
problem_statement	The quantified description of the finding.
verification	The exact commands/reads used to confirm it (reproducibility evidence).
impact	Value assessment: High / Medium / Low.
effort	Value assessment: High / Medium / Low.
confidence	Value assessment: High / Medium / Low.
current_state / expected_state	The observed vs. goal state.
owner_touchpoint_required	true when an owner decision is required to disposition the finding.
owner_question	The owner decision phrased as numbered options (when a touchpoint is required).
decision_complexity	low / medium / high (when a touchpoint is required).
proposed_approach	The minimal remediation path.
related_items	Cross-references to WIs, sibling findings, prior deliberations.
source	Provenance label (e.g. v1_report, a run id).
fab_cluster	The FAB cluster / WI the finding maps to, when known.

A finding is evidence-first: locations and verification are what make it a finding rather than an impression. A finding with impact >= Medium and no verification is incomplete and must go back through the adversarial-skeptic round before it is reported.

The 4-round probe method

Run the rounds in order. Each round is a fan-out of focused sub-agent probes; collect their structured findings, dedup by (finding_class, primary location), and carry the surviving set forward.

Round 1 — parallel focus-area probes (breadth)

Partition the platform into focus areas and probe each independently and blind to the others, so one search angle's blind spots are covered by another's. A good default partition:

• bridge dispatch + automation substrate; MemBase + storage + backups; rule/glossary/narrative surfaces; hooks + gates + enforcement; harness registry + roles + parity; CI + tests + assertions; isolation + root-boundary + Agent-Red residue; backlog + deliberations + work-item hygiene; token/startup cost.

Each probe returns findings against the schema. Breadth, not depth, is the Round-1 goal: name the finding, anchor at least one location, and propose a verification command. Do not stop at the first finding in an area — enumerate.

Round 2 — gap probe (what no focus area owned)

Ask explicitly: what surface did no Round-1 probe own? Cross-cutting concerns (cost economics, duplicate files, cloud-sync residue, retired-but-on-disk subsystems, contradictions between two always-loaded surfaces) routinely fall between focus areas. Probe the seams.

Round 3 — completeness critic

A single critic pass over the accumulated corpus asking: what modality was not run, what claim is unverified, what source went unread? The critic does not re-find; it identifies the missing work, which becomes the next round of probes. Anything the critic surfaces re-enters Round 1/2 for the affected surface.

Round 4 — adversarial skeptic (depth / refutation)

For each finding at impact >= Medium (or any decision-needed), spawn an independent skeptic prompted to refute it: reproduce the verification, check whether the evidence actually supports the claim, and default to "downgrade/withdraw" when uncertain. Record the outcome inline (UPHELD / corrected / withdrawn). This is what separates a high-impact finding from a plausible-but-wrong one.

Loop-until-dry with decay disclosure

Repeat Rounds 1-4 until K consecutive rounds surface nothing new (default K = 2). Simple "run once" misses the tail; loop-until-dry catches it.

Decay disclosure is mandatory. Each loop pass returns fewer and lower-confidence findings; quality decays as the obvious corpus is exhausted. The report MUST state, per surface: how many loop passes ran, when the last new finding appeared, and an explicit honesty note that absence of new findings in the final passes is evidence of coverage, not proof of completeness. Never present a dry run as "the platform is clean" — present it as "this method, at this depth, found no more; deeper or differently-angled probing may still surface findings."

Rendering the report (deterministic)

Use the deterministic report generator rather than hand-assembling a large report:

python scripts/hygiene/hygiene_report.py --baseline   # render the frozen baseline as a chunked report

scripts/hygiene/hygiene_report.py renders a finding list (schema-keyed) into the v1-style report in size-bounded chunks, so a large corpus does not exceed a single context window. It is callable without a live agent run (pure function: generate_report_chunks(findings, max_chars=...)), which is what makes it testable and cheap. Call it from this skill once probing converges; do not re-implement report shaping in prose.

Baseline registry

config/governance/hygiene-baseline-registry.toml is the canonical frozen HYG-001..068 record: the investigation corpus as of 2026-06-10, loadable via scripts/hygiene/hygiene_baseline.py::load_baseline(). Use it to:

• look up whether a fresh finding is already in the baseline (avoid re-reporting known items);
• seed the report generator with the baseline (--baseline) when you need the frozen census rendered;
• serve as the differ's baseline once the deferred delta mode lands.

The baseline is versioned and seeded once; do not silently mutate it. A new full-coverage run produces a new run corpus; promoting that corpus into a new frozen baseline is a separate, owner-gated step.

Routing findings to the backlog (owner-gated, no bulk mutation)

A finding is emitted in a form routable to work_items via scripts/hygiene/hygiene_report.py::finding_to_work_item(finding), which returns the field set gt backlog add consumes (title, origin='hygiene', component, change_reason, description). This is how findings become governed backlog candidates rather than markdown-only context (GOV-08, GOV-STANDING-BACKLOG-001).

This skill performs no bulk backlog/MemBase mutation. Routing a finding into work_items is an explicit, per-finding, owner-gated step under GOV-STANDING-BACKLOG-001 (capture is not implementation approval). A bulk routing run is its own owner-AUQ-approved operation with its own inventory + review packet; this skill only produces the routable form.

Deferred follow-on (NOT in this slice)

The delta mode — diffing the deterministic FAB-19 evidence pack against the baseline registry and probing only the changed surfaces, with the Q5 token targets — is deferred. It depends on the FAB-19 evidence-pack output contract, which is a separate bridge thread. This skill ships the full-run method only; it does not implement, invoke, or consume any FAB-19 evidence pack or delta differ. Do not add a delta procedure here until the follow-on thread lands with the producer contract cited.

Pre-flight

1. Resolve role from the canonical registry — read the active harness role via groundtruth_kb.harness_projection.read_roles (canonical harness-state/harness-registry.json); do not read any retired role-assignments mirror. This skill is required_for_roles = ["prime-builder"].
2. Read TAFE/dispatcher bridge state — use the bridge dispatcher status/health CLI and TAFE-backed bridge-state surfaces to confirm no parallel session is already driving a hygiene-investigation thread. Do not consult or recreate aggregate queue artifacts as bridge authority.
3. No mutation scope is invented — this skill produces findings, a rendered report, and routable work-item forms; any source/config remediation a finding implies is a separate, GO-gated bridge.

Does NOT

• Auto-remediate or auto-route. Findings become backlog items only through explicit owner-gated routing.
• Bulk-mutate work_items or MemBase. It emits the routable form; the routing run is separate and gated.
• Implement delta mode / consume a FAB-19 evidence pack. Deferred follow-on (see above).
• Silently mutate the baseline registry. Re-baselining is an explicit, owner-gated promotion step.
• Present a dry run as "clean". Decay disclosure is mandatory; coverage is not completeness.

Required reading

• .claude/rules/file-bridge-protocol.md — protocol contract for any remediation child-bridge.
• .claude/rules/codex-review-gate.md — review-gate constraints for remediation proposals.
• .claude/rules/deliberation-protocol.md — Deliberation Archive search obligations.
• .claude/rules/operating-model.md — canonical vocabulary.
• DELIB-FABLE-GRILL-20260610-Q5 (Deliberation Archive) — the repeatability-architecture charter.
• DELIB-S312-DETERMINISTIC-SERVICES-PRINCIPLE — the service/skill split rationale.
• config/governance/hygiene-baseline-registry.toml — the frozen HYG-001..068 baseline.

Companion deterministic surfaces

• scripts/hygiene/hygiene_baseline.py — HygieneFinding schema + load_baseline() (the frozen-findings loader).
• scripts/hygiene/hygiene_report.py — generate_report_chunks() (chunked report) + finding_to_work_item() (backlog-routable form).
• The deterministic detector core (FAB-19) is a separate thread; its evidence-pack contract is the input the deferred delta mode will consume.

Copyright

(c) 2026 Remaker Digital, a DBA of VanDusen & Palmeter, LLC. All rights reserved.