flow-hygiene

# FLOW Hygiene

Audit the health of the project's instruction corpus. Reads CLAUDE.md,
`.claude/rules/*.md`, and auto-memory files, then checks for six types
of drift: stale references, orphaned content, unenforced claims,
misplaced content, duplicated constraints, and contradictions. Read-only
— reports findings but does not fix anything.

Complements `/flow:flow-doc-sync`, which compares code behavior against
documentation. This skill compares instruction surfaces against each
other and against the codebase structure they reference.

## Usage

```text
/flow:flow-hygiene
```

## Announce

At the very start, output the following banner in your response (not via Bash) inside a fenced code block:

````markdown
```text
──────────────────────────────────────────────────
  FLOW v2.6.0 — flow:flow-hygiene — STARTING
──────────────────────────────────────────────────
```
````

## Finding Taxonomy

Eight finding types, each with a severity tag:

| Tag | Severity | Meaning |
|-----|----------|---------|
| `[STALE]` | High | A file path, function name, test name, or command referenced in an instruction surface no longer exists in the codebase |
| `[ORPHANED]` | Medium | A rule file or CLAUDE.md section describes a feature, hook, or pattern that no longer exists — the content itself is orphaned, not just a single reference |
| `[UNENFORCED]` | Medium | An instruction claims enforcement ("CI enforces via X", "hook blocks Y") but the named enforcer does not exist or does not check the claimed condition |
| `[MISPLACED]` | Low | Content is stored in the wrong persistence layer per the routing decision tree — e.g., an imperative constraint in CLAUDE.md instead of a rule, or a project fact in memory instead of CLAUDE.md |
| `[DUPLICATE]` | Low | The same constraint or fact appears in multiple surfaces with identical or near-identical wording — creates update burden when the constraint changes |
| `[CONTRADICTION]` | High | Two surfaces prescribe opposite behavior for the same situation — one says "always do X", another says "never do X" |
| `[CLAUDE_MD_MANDATE]` | High | A project-local rule file mandates that descriptive content be documented in CLAUDE.md — the mandate is itself the misclassification per `.claude/rules/persistence-routing.md` "Cross-Surface Application". Fix routes the mandated prose to a feature-specific `.claude/rules/<feature>.md` file plus a one-line CLAUDE.md index entry. |
| `[SIZE_BUDGET]` | Medium | CLAUDE.md exceeds the configurable size budget (`claude_md_budget` in `.flow.json`, defaults 12000 chars / 400 lines). Descriptive prose should land in feature-specific rule files, not in CLAUDE.md itself, so the budget overrun signals that recent additions failed the obey-vs-describe gate. |

## Steps

### Step 1 — Discover surfaces

Instruction surfaces are scattered across multiple files and formats.
Before any analysis can happen, the skill needs a complete inventory of
what exists and what each surface claims.

Identify and read all instruction surfaces in the project.

Use the Glob tool to find:

- `CLAUDE.md` in the current working directory
- `.claude/rules/*.md` in the current working directory

Read each discovered file using the Read tool. For each file, note:

- File path
- All file paths, function names, test names, and commands mentioned in backticks
- All enforcement claims ("CI enforces", "hook blocks", "test validates")
- All behavioral constraints (imperatives: "never", "always", "must", "do not")
- All architectural facts (descriptions of how things work)

For auto-memory: read the memory index (`MEMORY.md`) from conversation
context if it is loaded. If individual memory files are referenced in the
index, read them using the Read tool. Memory files live at
`~/.claude/projects/*/memory/` and are user-scoped — they may not exist
for every project.

**CLAUDE.md size budget check.** A CLAUDE.md that grows unchecked
signals that descriptive content is being added where only behavioral
content belongs, per `.claude/rules/persistence-routing.md` "Cross-
Surface Application". Read `.flow.json` from the project root using
the Read tool. If the file exists and contains a `claude_md_budget`
object, parse its `chars` and `lines` fields. If the file is missing
or the field is absent, use the defaults: 12000 chars and 400 lines.
Fail safe to the defaults whenever the input is unreliable: if
`.flow.json` is present but is not valid JSON, or `claude_md_budget`
is present but is not an object, or `chars`/`lines` is present but
is not a positive integer, use the defaults rather than prompting
or erroring.

Measure CLAUDE.md by reading the file with the Read tool — character
count is the byte length of the content, line count is the count of
newlines plus one for the final line. Emit a `[SIZE_BUDGET]` finding
when either count exceeds its budget. The finding's body cites the
measured value, the budget, the override path (`.flow.json` field
`claude_md_budget`), and the recommended fix (route descriptive prose
to feature-specific `.claude/rules/<feature>.md` files plus one-line
CLAUDE.md index entries).

### Step 2 — Structural verification

Instruction surfaces routinely drift from the codebase they describe as
files are renamed, functions deleted, and commands refactored. A
mechanical reference check is the only way to detect this without
reading every file manually.

Verify that references in instruction surfaces point to things that
exist. This is a mechanical pass — each check is a Grep or Glob call.

**File path references.** For each file path mentioned in backticks in
any surface, use the Glob tool to verify the file exists in the current
working directory. Tag missing files as `[STALE]`.

**Function and test name references.** For each function name or test
name mentioned in backticks, use the Grep tool to verify it exists as a
definition in the codebase. Tag missing definitions as `[STALE]`.

**Command references.** For each `bin/flow` subcommand mentioned (e.g.,
`bin/flow check-phase`, `bin/flow tombstone-audit`), use the Grep tool
to verify the subcommand is registered in the dispatcher or source. Tag
missing commands as `[STALE]`.

**Enforcement claims.** For each claim that names a specific enforcer:

- "CI enforces via `test_name`" — Grep for the test function definition
- "hook blocks" or "hook validates" — Grep for the hook name in `hooks/hooks.json`
- "`tests/file.rs` enforces" — verify the test file exists

If the named enforcer does not exist, tag as `[UNENFORCED]`. If the
enforcer exists but does not check the claimed condition (requires
reading the test or hook body), tag as `[UNENFORCED]` with a note
explaining the gap.

**Orphan detection.** After all reference checks, identify rule files
or CLAUDE.md sections where the majority of references are stale. If a
rule file's primary subject (the feature, hook, or pattern it describes)
no longer exists, tag the entire file as `[ORPHANED]`.

### Step 3 — Classification audit

Content placed in the wrong persistence layer creates maintenance burden
— a constraint in CLAUDE.md instead of a rule file must be updated in
two places when it changes, and a memory entry that duplicates a rule
silently diverges over time.

Apply the persistence routing decision tree to each content block.

The decision tree (from `.claude/rules/persistence-routing.md`):

1. Is it specific to this user? → Memory
2. Is it a behavioral constraint? (imperative guardrail) → Rule
3. Is it project knowledge? → CLAUDE.md
4. Can you derive it by reading code? → Do not store anywhere

**CLAUDE.md audit.** Read each section of CLAUDE.md. For each content
block, apply the imperative test: "Can you phrase this as an imperative
('do X', 'never Y', 'when X do Y')?" If yes, it belongs in a rule
file, not CLAUDE.md. Tag as `[MISPLACED]` with a recommendation to
move it to `.claude/rules/<topic>.md`.

Exclude sections that are genuinely project knowledge even if they
contain imperative-sounding language (e.g., "Phase gates prevent
skipping ahead" is a description, not an instruction).

**Memory audit.** For each memory file, check whether its content
duplicates an existing rule or CLAUDE.md section. If the same
constraint appears in both memory and a rule file, the memory entry is
redundant. Tag as `[MISPLACED]` with a recommendation to remove the
memory entry (rules are the authoritative source).

Also check whether memory files contain architecture facts, code
patterns, or file paths — these should be derivable from the code
and do not belong in memory. Tag as `[MISPLACED]`.

**CLAUDE.md mandate scan.** Project-local rules that mandate
CLAUDE.md prose for descriptive content invert the persistence
routing — the mandate is itself the misclassification per
`.claude/rules/persistence-routing.md` "Cross-Surface Application".
Use the Grep tool against `.claude/rules/*.md` (and any project-
local rule subdirectories) for the four canonical paraphrased
substrings the upstream rule catalogs. These four entries are
*pattern shapes*, not literal grep strings — match them by
judgment against the prose a rule file actually uses. In the
first entry, `X` and `Y` are placeholders standing in for a
project-specific noun (the descriptive surface) and a project-
specific documentation requirement; a real rule file will use
concrete nouns in those slots. Read each candidate rule file and
decide whether its prose expresses one of these shapes:

- `treats X added without Y documented in CLAUDE.md` — the
  enforcement-claim shape where a project-local rule asserts CI
  fails when a descriptive surface is added without a CLAUDE.md
  paragraph
- `must be documented in CLAUDE.md` — the direct-mandate shape
- `documentation home is CLAUDE.md` — the routing-destination shape
  for descriptive content
- `CLAUDE.md as the canonical destination` — the
  authoritative-source shape

For each match, emit a `[CLAUDE_MD_MANDATE]` finding citing the
rule file path, the matched line, and the recommended fix:
"Rewrite this rule to route descriptive content to a feature-
specific `.claude/rules/<feature>.md` plus a one-line CLAUDE.md
index entry per `.claude/rules/persistence-routing.md` Cross-
Surface Application."

Exclude matches inside quoted-example fences (Markdown code blocks)
or in paragraphs whose surrounding prose explicitly names the
pattern as an anti-pattern — those occurrences are documentation of
the pattern, not enforcement of it.

### Step 4 — Cross-reference audit

When the same constraint lives in multiple surfaces, a change to one
copy leaves the others stale. When two surfaces prescribe opposite
behavior, the model follows whichever it reads last — producing
unpredictable results.

Compare all surfaces pairwise for duplicates and contradictions.

**Duplicate detection.** For each behavioral constraint found in
Step 1, search all other surfaces for the same constraint expressed
in similar words. Exact duplicates and near-duplicates (same meaning,
different wording) both count. Tag as `[DUPLICATE]` with the two
source locations.

Focus on constraints that would need to be updated in multiple places
if the rule changed — identical constraints in CLAUDE.md and a rule
file, or the same rule stated in two different rule files.

**Contradiction detection.** For each pair of constraints, check
whether they prescribe opposite behavior. Common patterns:

- "Always do X" in one surface vs "Never do X" in another
- "Use A for this" vs "Use B for this" where A and B are mutually exclusive
- Conflicting scope — one surface says a rule applies to all phases, another limits it to specific phases

Tag as `[CONTRADICTION]` with both source locations and the specific
conflict.

### Step 5 — Report

The audit is only useful if its findings are actionable. Grouping by
source file lets the user address all issues in one file at a time,
and severity tags help prioritize what to fix first.

Produce the findings report inline in the response.

**Summary line.** Start with a one-line summary:

> **Hygiene: N findings (X stale, Y orphaned, Z unenforced, W misplaced, V duplicate, U contradiction, M claude-md-mandate, B size-budget)**

If no findings, output:

> **Hygiene: Clean — no instruction corpus drift detected.**

**Findings by source file.** Group findings by the source file where
the problematic content lives. For each file with findings, show the
file path as a heading, then each finding:

```text
## <source_file_path>

**[STALE]** <description>
- References: <what it references>
- Status: <not found / renamed to X / removed>

**[UNENFORCED]** <description>
- Claims: <what it claims is enforced>
- Enforcer: <named test/hook>
- Status: <enforcer not found / enforcer does not check this>

**[MISPLACED]** <description>
- Content: <summary of the content>
- Current location: <where it is>
- Recommended location: <where it should be>

**[DUPLICATE]** <description>
- Location 1: <file:line>
- Location 2: <file:line>

**[CONTRADICTION]** <description>
- Surface 1: <file> says <X>
- Surface 2: <file> says <Y>
```

**Orphaned files.** List `[ORPHANED]` findings separately at the end
under an "## Orphaned" heading.

After the report, output the following banner in your response (not via Bash) inside a fenced code block:

````markdown
```text
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  ✓ FLOW v2.6.0 — flow:flow-hygiene — COMPLETE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```
````

## Hard Rules

- Read-only — never fix, edit, or commit anything
- No state file mutations — this is a stateless utility skill
- No AskUserQuestion — produce the report and finish
- No sub-agents — all comparison is inline
- Never use Bash to print banners — output them as text in your response
- Never use Bash for file reads — use Glob, Read, and Grep tools
- Focus on structural accuracy and classification correctness, not style