Feature Code Hygiene Review

Feature: Code Hygiene Review

A Feature-Pages entry. This page explains the capability; it never redefines it — see Feature-Pages for the canonical/Wiki boundary statement that applies to every page in this pattern.

What it does

When a change adds or edits an issue-tracker reference in a comment, or introduces or renames a variable whose name may hide its intent, the review applies two narrow hygiene checks: an issue-tracker reference that is uninformative, redundant, or obsolete, and a variable name that hides intent where the surrounding code supports exactly one clearer name. It is not a linter — dead code, magic numbers, formatting, and style are out of scope, and lines the change did not touch are never reviewed.

Why it exists

Stale // fix for #75 comments and names like tmp make code harder to maintain, but they rarely deserve a blocked merge. The feature gives them a home that is visible to the author yet cannot hold up the Decision.

When it applies

Conditional and automatic — no invocation option. Both Skills. It runs only when the changed delta contains a tracker-reference comment or a possibly unclear variable name, and is silent otherwise. A pattern match (#75, PROJ-456, tmp) is only a candidate; it is reported only when local context supports it.

How it works

One shared policy serves both adapters, so the same change gets the same result in local-code-review and github-pr-review.

• Tracker references are kept — nothing reported — when they document an active workaround, a known limitation, a decision, an external contract, a compatibility constraint, or traceability the repository requires. They are flagged only when obsolete, redundant, or uninformative, with a concrete rewrite or "delete".
• Names are flagged only with one concrete suggested replacement. Loop indices, short names with clear local meaning, standard abbreviations, and project-convention names are never reported.
• Severity. The default is a severity-less observation (max 3, no ID, no blocking meaning, never counted toward the Decision). A P2 finding needs causal evidence of real maintainability cost. Never P0 or P1.
• Delivery. An optional Code hygiene observations section before Validation; on GitHub it is review-body only — never inline, never a review event.

Limits

No tracker lookup: staleness is judged from local evidence only, so a reference that is live only in the tracker may be flagged when it should be kept — treat an observation as a prompt to check. Naming suggestions can miss domain vocabulary the change does not show.

Example

// see #75        → observation: state the fact or delete
// retry: upstream limits 5 rps (#75)   → kept, nothing reported
const tmp = user.sessionExpiry;  → observation: rename to sessionExpiry
for (let i = 0; …)               → not reported

Related features

Severity-and-Decision-Model · Specialist-Depth-Review · Feature-Rendered-UI-Inspection (the other severity-less observation section).

Canonical references

code-hygiene.md · usage guide docs/features/code-hygiene.md.