clide/.claude/skills/clean-house/references/rules.md

clean-house rule catalog

The rules clean-house runs and the reasoning behind each. New rules land here as their own entry. Catalog churn — additions, refinements, retirements — is tracked in pql's CHANGELOG.md and git log internal/skill/clean-house/. When a rule is retired, leave a Retired stub (ID + one-line reason + retirement commit) so the trail of "we used to check X" is recoverable from this file alone.

Reading a rule

Each entry below has:

• ID — Stable identifier (e.g. RULE-ANCHOR-DRIFT). Used in AskUserQuestion prompts and skip-ledger entries so the user learns what's being checked.
• Category — mechanical or judgment. Drives whether findings batch into one prompt or each get their own.
• Finding ID — Format string for the per-finding stable identifier. Skip-ledger entries are written as <rule-id> <finding-id> <ISO-date>; subsequent runs use the same format to recognize "same finding skipped 3 runs in a row" and escalate. Use only stable inputs (record IDs, file paths, slug strings, body hashes) — never line numbers or timestamps.
• Detection — Concrete steps to find violations. Names the pql command or file primitive used.
• Fix — Mechanical: deterministic action. Judgment: the prompt option list and what each option does.
• Why — One paragraph on the failure mode this rule guards against. Future-you reading the rule benefits from the reasoning, not just the check.

---

RULE-ANCHOR-DRIFT

Category: mechanical

Finding ID: <source-record>:<link-target> (e.g. D-8:#q-1-markdown-mirror-for-tickets or D-8:questions.md#q-1).

Detection:

Anchor-only markdown links ([text](#slug)) resolve against the source file's full heading set, not the body of a single record — record-level headings (### D-N: …) live as siblings in the file and are valid link targets. The previous detection (which used pql decisions read's body-only headings array) missed these and produced false positives.

Per source body:

1. Open the source body's file (<vault>/<file_path> from pql decisions list) and extract every ATX heading. Build a slug index for the file using the GFM convention (lowercase, hyphenate spaces, drop punctuation, disambiguate duplicates with -1/-2). Cache per file — every record in that file uses the same index.
2. For each [text](target) link in the body:
   • Anchor-only (#slug): check slug against the source file's index. Missing → flag.
   • Cross-file (path.md#slug): resolve path.md relative to the source file's directory; check slug against that file's index. Missing file or missing slug → flag.

Fix:

If the slug exists in a sibling file's index (same directory) and the link is anchor-only, rewrite to path.md#slug (the canonical cross-file form). If the slug exists in the source file's index with edit-distance ≤ 2 from the link target, rewrite to the matched slug. Otherwise downgrade to judgment ("no auto-fix; the heading was removed, not renamed") with options: drop the link / point elsewhere / mark as intentionally dangling.

Fix:

If exactly one heading with a closely-matching slug exists (slug edit-distance ≤ 2 or substring match), rewrite the link to point at that heading. If no plausible match exists, downgrade the finding to judgment ("no auto-fix; the heading was removed, not renamed") and prompt the user with options: drop the link / point elsewhere / mark as intentionally dangling.

Why:

When a heading is renamed for clarity, every cross-reference pointing at the old slug silently breaks. The rendered docs still look fine — the link just goes nowhere. Without periodic sweeps these decay indefinitely; the cost of the sweep is small compared to the cost of a reader following a dead link and losing trust in the index.

---

RULE-MISSING-Q-BACKLINK

Category: mechanical

Finding ID: <d-id>:<q-id> (e.g. D-7:Q-2). Order is always D-first regardless of which side is missing the backlink.

Detection:

For each D record body, find lines of the shape Resolves: Q-N (plain text, typically in the metadata block at the top of the record). For each Q-N referenced, fetch that Q record's body via pql decisions read Q-N and check whether it contains a line of the shape Resolved → D-N (or equivalent backlink phrasing — match the project's own convention; default pattern is Resolved → D-N).

Also check the reverse direction: any Q record claiming Resolved → D-N whose D-N body lacks Resolves: Q-N.

Fix:

Insert the missing backlink in-place using Edit:

• Missing on the D side: add Resolves: Q-N to the D's metadata block (typically right after Domain: / Status: lines).
• Missing on the Q side: append Resolved → D-N to the Q's status line (or in the conventional position for that project).

Why:

Bidirectional Q↔D links are the navigation backbone of the DQR system. When one side drifts, search-by-decision finds nothing for that question and search-by-question doesn't surface its resolution. The asymmetric state usually arises from a hand-edit on one record that forgot to update the other; the fix is purely mechanical because the correct content is already determined by the existing pointer in the other direction.

---

RULE-RECORD-SORT

Category: mechanical

Finding ID: <file-path> (e.g. decisions/architecture.md). The whole file is one finding — sort applies to the file as a unit.

Detection:

For each decisions/*.md file, read it directly (no pql) and find all top-level ## D-N / ## Q-N / ## R-N headings in order. Strip the prefix, parse the numeric suffix, and check whether the sequence is monotonically ascending within each ID family (D, Q, R kept separate — files commonly mix families).

Only flag a file if it is otherwise tidy — currently no out-of- order amendments interleaved with new records. The heuristic: if the sort would touch fewer than three records out of position, apply it; if more, downgrade to judgment ("this file looks deliberately arranged — confirm before reordering"). Three is a soft threshold; if the file's last commit message contains WIP or do-not-sort, skip.

Fix:

Reorder the records within the file so each ID family is ascending. Preserve everything else (headings between record blocks, any prose prelude/postlude). Use Edit with full block replacement, not in- place line shuffling — easier to verify the diff.

Why:

Records added at the bottom of a file are easy to write but hard to find. Sorted IDs let a reader find D-37 by jumping to the two-thirds mark of the file rather than scanning. The cost of the sort is one reordering pass; the benefit is paid back on every subsequent read.

---

RULE-EOF-NORMALIZATION

Category: mechanical

Finding ID: <file-path> (one finding per file).

Detection:

For each decisions/*.md file (and any other markdown the skill touched during this run), read directly. Flag if:

• File does not end with exactly one \n.
• Any line contains trailing whitespace before its \n.

Fix:

Trim trailing whitespace from each line. Ensure exactly one trailing newline at end of file. Use Edit only if a violation was found — this rule must not produce a no-op diff.

Why:

Editor and git config drift causes whitespace creep that's invisible in rendering but pollutes diffs (every record edit ends up touching unrelated lines). A periodic normalization keeps future diffs clean without forcing per-editor enforcement on every contributor.

---

RULE-SUNSET-WITHOUT-TICKET

Category: judgment

Finding ID: <record-id>:<phrase-hash-8> where phrase-hash-8 is the first 8 hex chars of sha256(<matched-phrase>). Lets the ledger distinguish two sunset phrases in the same record.

Detection:

For each D record body (via pql decisions read <id>), grep for sunset-shaped phrases. Default regex set:

(?i)\b(delete|remove|sunset|kill[ -]?switch|tear[ -]?down) when\b
(?i)\bmust (track|monitor|watch|follow)\b
(?i)\brevisit (when|after|once)\b
(?i)\b(deprecate|retire) (when|after|once)\b

For each match, run pql ticket list --decision <id>. If no tickets exist, the D has work-shaped intent without a tracked T — flag.

Fix (prompt options):

• File T now — Run pql ticket new task "<phrase>" --decision <id>, then prompt the user for a description (or call pql ticket refine write <T> --description ... after creation).
• Draft a T description first — Open an AskUserQuestion for the description, then file as above.
• Mark as already covered — Add a note to the D body ("Tracked under T-N") via Edit. Skill does not assert which T; user provides the ID.
• Skip — Adds to the ledger.
• Stop asking — Skip remaining sunset findings, summarize.

Why:

Sunset-shaped intent ("we'll handle X when Y happens") is the most common source of accumulated debt in a DQR system: the trigger condition arrives, nobody remembers the D, the work doesn't happen. Linking each sunset to a T is the simplest defense — a T is a backlog item that surfaces in plan whatsnext / plan board. The fix is judgment because the right action depends on whether the D's condition is still relevant, whether it's already covered, and what the right scope is for the resulting T.

---

RULE-FILE-OVER-THRESHOLD

Category: judgment

Finding ID: <file-path> (one finding per file; threshold choice is judgment, not a per-line problem).

Detection:

For each decisions/*.md file, count lines (via wc -l or equivalent). Default threshold: 350 lines. Configurable per project — read decisions/.clean-house.yaml if present, key file_threshold. Fall back to 350.

Fix (prompt options):

• Split now (which axis?) — Prompt for the split axis: by ID family (D/Q/R), by domain, by date range, custom. Then perform the split: create new file(s), move records, update any anchor links pointing into the moved records (run RULE-ANCHOR-DRIFT in apply mode against the affected files after the split).
• Accept and raise the threshold — Update decisions/.clean-house.yaml's file_threshold to the next reasonable round number above the current line count.
• Defer — Skip until next run.

Why:

A single decisions file growing past ~350 lines is the point at which linear scanning starts to lose to grep, and where the cost of splitting (renaming anchors) is still small. Beyond ~600 lines the split cost compounds. The threshold is judgment because some projects deliberately keep one file per domain and accept the size; others split aggressively. The skill surfaces the question; it doesn't decide.

---

RULE-DEAD-FILE-REFERENCE

Category: judgment

Finding ID: <record-id>:<path-token> (path token as written in the body, not resolved).

Detection:

For each D record body (via pql decisions read <id>), grep for path-shaped tokens. Default regex:

\b([\w./-]+\.(md|go|py|sql|yaml|yml|toml))\b

The first detection pass produced 6/6 false positives in real-world use; the regex is necessary but not sufficient. For each match, apply the filters below in order — if any matches, skip without flagging:

1. Placeholder filter. Token contains T-NNN, D-NNN, Q-NNN, R-NNN, ..., <, >, or * — it's a pattern, not a real path.
2. Source-relative resolution. Resolve the token against the source file's directory (<vault>/<file_path>'s dir). If [ -e <resolved> ], the reference is live.
3. Repo-relative resolution. If [ -e <token> ] from the repo root, the reference is live.
4. Basename-fallback. Run find <repo-root> -name <basename> (where basename is the last path component). If exactly one match exists, treat the reference as live and emit a low- priority "consider rewriting to the absolute path" note (not a judgment finding). If multiple matches exist, do not flag — the token is too ambiguous.

Only after all four filters miss does the reference qualify as truly dead and warrant a judgment prompt.

Fix (prompt options):

• Update reference — Prompt for the new path; rewrite the reference via Edit. If the user types a path, validate it exists before applying.
• Mark superseded — Add a note to the D ("This decision references files no longer present; the underlying constraint was retired by D-N") and prompt for the superseding D ID.
• Defer — Skip until next run.

Why:

Decisions reference code paths to ground their reasoning in the codebase that motivated them. When the code moves or gets deleted, the D's reasoning becomes harder to verify. Dead refs are a signal that either the decision should be updated or the decision itself is no longer load-bearing — both are judgment calls the user needs to make.

---

RULE-STALE-OPEN-Q

Category: judgment

Finding ID: <q-id> (one finding per Q-record; staleness threshold is global per run, so a Q is either stale or not).

Detection:

Run pql decisions list --type question --status open. For each returned record, check the date field. Default staleness threshold: 60 days (configurable via decisions/.clean-house.yaml key stale_open_q_days). Flag any Q with date older than the threshold.

Fix (prompt options):

• Still relevant — Touch the Q's date field to today, optionally add a one-line "still open as of YYYY-MM-DD: " to the body.
• Nudge to load-bearing index — If the project keeps a load-bearing Qs list (a curated index of unresolved questions affecting current work), prompt for inclusion and add the Q there.
• Mark withdrawn — Change the Q's status to withdrawn (the DQR system's terminal state for "no longer worth answering"); the user supplies a one-line reason.
• Defer — Skip until next run.

Why:

Open questions are useful when they're current; stale ones become ambient noise that drowns the signal of new questions. Most projects don't enforce explicit Q-lifecycle, so without a periodic prompt the open list grows forever. The right action depends on whether the question is still open in fact — not just in metadata — which only the user can confirm.