A Stated Rule Needs Annotated Exceptions Agent Skill

A stated rule needs annotated exceptions

"No hardcoded whites on semantic surfaces" is a good rule with real exceptions: a control floating

over a photo or a video legitimately stays white. That combination — enforceable, but not

absolutely — is the one that decays, because after a few months nobody can tell which of the

remaining hardcoded colours were decisions.

The fix is cheap and mechanical: state the rule where it is established, write one line of reason

where it is broken, and keep a command that lists both.

Traps

A rule you cannot grep for will not be enforced. "No hardcoded whites on semantic surfaces" is

enforceable because the violation is a literal token. "Use semantic colours" is not, because the

compliant form is the absence of something. Write rules in terms of what appears in the file.

The reason belongs at the call site, on the line above. A file-header note saying "the whites in

this file are all over video" is true on the day it is written and false the first time somebody adds

a block below. It also cannot be read at the point where the reviewer is looking.

A block annotation covers a run of siblings only while they stay siblings. Four icons in one

overlay row under one comment is reasonable; the moment one is moved or copied elsewhere it arrives

with no reason attached and looks exactly like a violation. If a group is likely to be split, annotate

each member.

Do not annotate the compliant lines. Comments on code that follows the rule dilute the audit

until the exceptions are unfindable, which is the same end state as annotating nothing.

Scope the audit to the code the rule governs, or it drowns. The rule here applies to one look;

the other look on the same screen predates it and never adopted it. Auditing the whole package

returns dozens of hits from code the rule never covered, and an audit that always fails is an audit

nobody runs. Derive the file list from something structural — the files that read theme roles, say —

and say what the list means.

Distinguish "exception" from "out of scope". A colour on a surface that is not themed at all is

not an exception to the theming rule; it is simply outside it. Recording it as an exception makes the

exception list meaningless.

Expect the audit to find unannotated hits, and treat that as the mechanism working. Run step 3

here and the tally comes back as a couple of dozen bare against a handful annotated inside the

governed subtree. That ratio is only useful to whoever re-derives it and then annotates or fixes each

one — quoting a number somebody else printed is the same rot the rule exists to prevent.

A comment-window heuristic over-reports compliance. Checking "is there a // within two lines"

counts any nearby comment, including one about something else entirely — read the ok hits here and

some are a comparison against a colour, or a comment merely naming the token, rather than a painted

colour. That inaccuracy is the argument for codifying the rule as a lint or static-analysis check

once the exception rate is low enough; the comment convention is the fallback for rules a tool

cannot evaluate, such as "is this drawn over video?".

State the rule once, where it is established. The KDoc of the file that sets up the themed

subtree is the right place — it is what a reader hits before writing the code the rule governs. Two

copies of a rule drift like any other duplicate.

Verifying it

• The rule statement exists and is findable:

   grep -rn --include='*.kt' --exclude-dir=build "no hardcoded whites\|hardcoded white" .

• Run the audit. The file list is derived, not typed — change the two greps to match your own rule's

scope and token:

   D=$(dirname "$(grep -rl --include='*.kt' --exclude-dir=build '^class .*ContentState(' .)")
   grep -rl "MaterialTheme.colorScheme" $(find "$D" -name '*.kt') | while read -r f; do
     awk -v F="$(basename "$f")" '/Color\.(White|Black)/ {
            print (p1 ~ /\/\// || p2 ~ /\/\// ? "  ok " : "BARE ") F ":" NR
          } { p2=p1; p1=$0 }' "$f"
   done

• The tally, which is the number to watch over time:

   D=$(dirname "$(grep -rl --include='*.kt' --exclude-dir=build '^class .*ContentState(' .)")
   grep -rl "MaterialTheme.colorScheme" $(find "$D" -name '*.kt') | while read -r f; do
     awk '/Color\.(White|Black)/ { print (p1 ~ /\/\// || p2 ~ /\/\// ? "ok" : "BARE") } { p2=p1; p1=$0 }' "$f"
   done | sort | uniq -c

• Spot-check three ok hits by reading them. If any of the three turns out to have a nearby comment

about something unrelated, the heuristic is over-reporting and the real annotated count is lower

than the tally claims.