Gz Foundation Triage

---
name: gz-foundation-triage
persona: main-session
description: Use to rank the in-flight foundation backlog by insight signal, GHI count and invariants.
category: adr-lifecycle
lifecycle_state: active
owner: gzkit-governance
last_reviewed: 2026-10-17
metadata:
  skill-version: "1.1.1"
model: sonnet
---

# gz-foundation-triage

Rank the in-flight foundation backlog by priority. The bundled script does the
deterministic work (gather Draft/Proposed foundation ADRs, count governance
signals, render the deliverable). The agent does the cognitive work (read each
candidate's § Intent and § Decision, classify severity, flag port/adapter
reclassification candidates). Determinism lives at the rendering edge;
cognitive freedom lives only on the input edge.

This skill is **diagnosis only**. It MUST NOT mutate any foundation ADR,
ledger entry, registry, or promote/complete/change-status on any artifact.
Running the skill is read-only across the governance surface.

The bundled script reports raw signal counts. Weighted scoring is the
foundation-triage-rubric surface at `src/gzkit/foundation/rubric.py`:
`uv run python -m gzkit.foundation.rubric` prints a `priority_score` with its
evidence for each in-flight foundation. Read those scores as evidence in the
cognitive pass; they never enter the rank-input JSON, whose schema rejects
extra fields.

## Invocation

```text
/gz-foundation-triage
```

## Triage Procedure (binding — three steps)

When this skill is invoked, the agent MUST execute the three steps below in
order. The deliverable is the rank-ordered list from Step 3.

### Step 1 — Mechanical pre-pass (single script call)

Run the bundled helper once with `--format json` to gather every in-flight
(Draft or Proposed) foundation ADR with its governance-signal counts inline:

```bash
uv run python .gzkit/skills/gz-foundation-triage/scripts/triage.py --format json
```

Each record contains: `id` (canonical ADR id, e.g. `ADR-0.0.57`), `status`
(one of `Draft`/`Proposed`), `title`, `path` (foundation ADR file relative
to repo root), `insight_count` (`agent-insights.jsonl` mentions of the ADR
id), `ghi_count` (GHI references mined from the same insights stream),
`invariant_mentions` (occurrences in `AGENTS.md` and `.gzkit/rules/*.md`).
The script is read-only over the governance corpus — it parses files; it
never writes them.

### Step 2 — Cognitive pass (read each candidate, classify severity)

For each record in the Step 1 JSON, read the foundation ADR's `§ Intent`
section and `§ Decision` section. This is the contract; everything else
hangs off it. Do not classify without reading both.

Then apply the **port/adapter reclassification check** (mirrored from the
pool-triage cognitive-pass pattern, which adopted GHI #424 round-3
hardening): flag any candidate whose scope authors an invariant or
prerequisite without which downstream features cannot exist. A flagged
candidate is emitted as `{id, reclassify: "foundation"}` in a separate
annotation list, NOT as a rank-input entry. Ranked candidates and
reclassification annotations are mutually exclusive: a single candidate
appears in one list or the other, never both.

**Where the foundation kind is closed, the annotation list stays empty.** A
project that has closed the kind carries `data/foundation_grandfather.json`,
and gzkit has (`AGENTS.md` § Gate Covenant; `gz validate --taxonomy`). A closed
kind takes no new member, so emit `"reclassify_foundation": []` and rank every
candidate. Where the kind is open, the check applies as written, and the
example below shows that case.

Compose a single rank-input JSON document with one entry per candidate the
agent recommends working on:

```json
{
  "rankings": [
    {"id": "ADR-0.0.57", "severity": "urgent"},
    {"id": "ADR-0.0.48", "severity": "next-quarter"}
  ],
  "reclassify_foundation": [
    {"id": "ADR-pool.some-slug", "reclassify": "foundation"}
  ]
}
```

**Rendering-edge contract (binding — structural-only schema):**

| Field | Constraint |
|-------|------------|
| `rankings[*].id` | str; must appear in the Step 1 fetched set |
| `rankings[*].severity` | one of `urgent` (pull this quarter), `next-quarter`, `latent` |
| `reclassify_foundation[*].id` | pool ADR id (slug-form) |
| `reclassify_foundation[*].reclassify` | literal `"foundation"` |
| any other field | rejected by the renderer |

The schema is structural-only by design. The agent's cognitive contribution
is **selection + ordering + severity + reclassification flag**; the renderer
owns all prose, derived from the fetched candidate set.

### Step 3 — Deterministic rendering

Write the rank-input JSON to a cache file under `.gzkit/cache/foundation-triage/`,
then pass that path to the script with `--format rank`:

```bash
# Write tool: .gzkit/cache/foundation-triage/rank.json
uv run python .gzkit/skills/gz-foundation-triage/scripts/triage.py \
    --format rank --rank-input .gzkit/cache/foundation-triage/rank.json
```

The script renders a deterministic markdown deliverable: one numbered row
per ranked foundation, each row containing the severity and title in a
fixed shape; the reclassification annotations render in a separate section
beneath. **The script's stdout IS the deliverable** — do not echo, restate,
copy, or paraphrase that output in agent-generated text.

There is no Step 4. The rank list and the reclassification annotation list
together ARE the recommended work order.

## Output Contract

Declared form: **deterministic markdown**, the script's `--format rank`
output, presented verbatim. Chat-renderable; no Rich box-drawing glyphs;
no ANSI color sequences.

## Ephemeral-output invariant (binding)

After a foundation-triage run, the following MUST hold:

```bash
git status --porcelain docs/design/adr/foundation/ .gzkit/ledger.jsonl
# Expected: empty output
```

If any foundation ADR file or `.gzkit/ledger.jsonl` shows as modified, the
ephemeral / diagnosis-only invariant has been violated and the skill is
defective. The skill is a read-only diagnostic; promotion remains an
operator decision under the relevant lifecycle ADR.

## Anti-patterns

- Running foundation-triage as a commit gate (it is on-demand only)
- Auto-promoting foundations from the triage output
- Mutating any foundation ADR or ledger entry as a side-effect
- Restating the rendered deliverable in agent-generated prose
- Adding agent-supplied prose fields to the rank-input JSON schema

## Related

- ADR-0.0.57 — foundation-ADR nominal-ID semantics and priority triage
- `.gzkit/skills/ghi-triage/SKILL.md` — sibling pattern in the
  `governance-triage` bounded context
- pool-triage cognitive-pass — the port/adapter reclassification check
  inherits its language from the pool-triage cognitive-pass pattern