validating-diff

Validating Diffs

Overview

The captured ruleset is enforced at meaningful checkpoints, not after every keystroke. This skill is the gate at those checkpoints.

This skill calls the validate_diff MCP tool.

When to call — the right cadence

The right call frequency is 3–8 times per phase, not 1 (too coarse) and not 12+ (too noisy). The pattern is "once per testable behavior" — every time a logical unit reaches a state worth gating on.

Call when:

• A logical unit is complete: a service + its controller + its spec, written and assembled into something that could be tested.
• A TDD cycle finished — failing test → passing implementation → cleanup. After cleanup is the natural validation point.
• About to commit a batch of changes.
• About to tell the user "the change is in" / "ready" / "done".
• About to hand off to the verifying skill (which runs validate_diff again as the final gate).

Do NOT call when:

• Writing a test fixture, snapshot, or pure data file. Nothing the engine can flag.
• Mid-TDD red phase, where the implementation file is empty or stub. Nothing decorated yet.
• Mid-refactor with files in inconsistent intermediate states. The transient state will produce false positives that disappear once the refactor lands.
• Writing a single line of formatting / imports / comments. Trivial edits don't shift any rule outcome.

Why not "every file write":

Three concrete costs. (1) During partial multi-file changes, a controller method calling a not-yet-written service method would spuriously trigger edge-forbidden flags that resolve once the second file lands — training the agent to ignore violations in general. (2) TDD-red phases have nothing to validate; calling anyway is theater. (3) Stop-start fragmenting natural reasoning seams reduces flow without catching anything you wouldn't catch at the next checkpoint.

The earlier you call within the right cadence, the cheaper the iteration. But "earlier" means "at the next logical-unit boundary", not "between every two characters typed."