h-semio-review - SKILL.md Agent Skill

name: h-semio-review description: | INTERNAL SUBROUTINE — semiotic / fanout audit on a concept rename, deprecation sweep, or doc-vs-code consistency check. Walks all carriers (filenames, manifests, stale refs, review surfaces, dashboards, prompts) until fixed-point clean, because one-shot text replacement creates rework when carriers diverge. Manual invocation only. Do not auto-select for general work — for code review use Claude Code review; for FPF reasoning about decisions use h-frame / h-decide. when_to_use: | Internal subroutine only. Manual invocation on a specific concept rename, deprecation cleanup, or spec consistency audit where carriers may have drifted. argument-hint: "[concept being renamed or audit target]" disable-model-invocation: true allowed-tools: Bash Read Grep Glob mcphafthaft_query

h-semio-review — Fanout audit (subroutine)

You are running the semiotic fanout audit per FPF X-FANOUT-AUDIT and the semiotics_slideument discipline. The premise: on concept rename / deprecation / spec consistency check, the change must sweep ALL carriers — prose, filenames, manifests, review bundles, provenance, tests, schemas — until fixed-point clean. Skipping carriers leaves zombie references that mislead future operators and agents.

Explicit-only — disable-model-invocation: true.

Step 1 — Identify the object of talk

What CONCEPT or TERM is being renamed / deprecated / audited? Get it from the operator explicitly. Bad: "audit the docs"; good: "rename Service to EnablingSystem across docs and code".

If renaming, capture both old and new names. If deprecating, capture the old name and the replacement (or explicit "no replacement").

Step 2 — Map carriers exhaustively

Run discovery across all carrier surfaces:

# Prose carriers
grep -rl "<term>" --include="*.md" --include="*.txt" --include="*.rst"

# Code carriers
grep -rl "<term>" --include="*.go" --include="*.py" --include="*.ts" --include="*.tsx" --include="*.rs" \
                  --include="*.java" --include="*.js" --include="*.jsx"

# Manifest carriers
grep -rl "<term>" --include="package.json" --include="Cargo.toml" --include="pyproject.toml" \
                  --include="go.mod" --include="*.yaml" --include="*.yml" --include="*.toml"

# Filenames
find . -name "*<term>*" -not -path "./node_modules/*" -not -path "./.git/*"

# Test fixtures
grep -rl "<term>" --include="*_test.*" --include="*.test.*" --include="testdata/*"

# Review bundles & specs
grep -rl "<term>" .haft/ docs/ .context/ 2>/dev/null

Build a carrier-by-carrier inventory. Every hit is a potential semio failure if the rename / deprecation doesn't sweep it.

Step 3 — Classify each hit by statement type

For every hit, classify the statement type (per FPF X-STATEMENT-TYPE):

Rule (definition / law)
Promise (deontic commitment)
Plan (intention)
Explanation (descriptive)
Decision (binding choice)
Gate (admissibility condition)
Evidence (observation)

This matters because rename behavior differs per type:

Rule rename = update the definition itself
Promise rename = potentially break compatibility — flag for operator
Decision rename = check if referenced in active DRRs (mcp__haft__haft_query(action="search", query="<term>"))
Evidence rename = update label only; observation content is immutable

Step 4 — Same-name / different-thing check

Look for cases where the term being renamed already has a DIFFERENT meaning elsewhere in the codebase. Example: renaming Service to EnablingSystem — but Service already means something else in auth/ (HTTP service vs FPF enabling system).

For each ambiguous hit, ask the operator whether this hit is in-scope for the rename.

Step 5 — Different-name / same-thing check

The inverse: look for cases where the OLD concept appears under different aliases. Example: renaming Service to EnablingSystem — but the same concept might also be called Creator, Builder, Producer in different carriers. Surface aliases for operator decision.

Step 6 — Produce fanout repair plan

Output as ordered repair list:

Fanout repair plan for rename "<old>" → "<new>":

Phase A — Definitional carriers (update first):
- docs/glossary.md (Rule)
- .haft/specs/term-map.md (Rule)
- internal/types/service.go:42 (Rule — Go type declaration)

Phase B — Reference carriers (update after definitions stable):
- internal/auth/handler.go:80 (uses term in implementation)
- internal/auth/handler_test.go:120 (test fixture)
- README.md:55 (prose explanation)

Phase C — Manifest carriers:
- internal/auth/_meta.yaml:3
- pyproject.toml:14

Out of scope (different concept, same name):
- internal/network/service.go (HTTP service abstraction, not FPF EnablingSystem)

Aliases to disambiguate (operator decision):
- "Creator" appears in 4 files — operator confirm: is this the same concept?

Step 7 — Fixed-point check

After the operator (or downstream agent) applies the repair plan, re-run discovery. Repeat until grep returns zero unexpected hits. Per X-FANOUT-AUDIT: not iterating to fixed-point is the failure mode.

Step 8 — Surface to operator

Present:

Carrier inventory (with counts per carrier type)
Statement-type classification
Same-name / different-thing ambiguities
Different-name / same-thing aliases
Ordered fanout repair plan (Phase A definitional, then references, then manifests)
Out-of-scope hits explicitly listed

The operator decides what to act on. This skill stops at audit + recommendation — it does NOT execute the renames.

What NOT to do

DO NOT bulk-rename without operator approval per ambiguous hit. Same-name / different-thing is the catastrophic semio failure.
DO NOT skip the fixed-point re-check. Stopping after one pass leaves zombies.
DO NOT auto-update spec carriers — those are operator authorship per h-onboard discipline.
DO NOT use this skill for general code search — it's specifically for semio / rename / fanout audit.
DO NOT classify every hit identically — statement-type matters because rename semantics differ per type.

FPF spec references

X-FANOUT-AUDIT — on concept rename, sweep all carriers until fixed-point
X-STATEMENT-TYPE — every load-bearing sentence = rule / promise / explanation / gate / evidence
F.17 — Unified Term Sheet (UTS) — the canonical term-mapping carrier
A.7 — Object / Description / Carrier — what changes vs what holds it
A.6.9 — Cross-Context Sameness Disambiguation
E.10 — Lexical discipline

Look up via mcp__haft__haft_query(action="fpf", query="X-FANOUT-AUDIT"). The semiotics_slideument in .context/semiotics_slideument.md carries the human-facing rationale.