---
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.