Scoping Change Relevance

Scoping Change Relevance

Use this skill to decide, from the diff alone, which quality practices a specific change makes relevant - and to be able to defend the answer.

Running every check on every commit is slow, so teams stop gating on it. Running whatever the author felt like is fast and arbitrary. The middle path is a tag grammar: derive tags mechanically from the diff, map tags to practices with a fixed recipe table, and the scope becomes reproducible. Two people scoping the same diff should land on the same list.

When to Use

• a pre-push or PR gate needs to run a subset of checks, chosen defensibly
• a reviewer needs to know what this diff puts at risk before reading it
• a slow suite has made "run everything" politically impossible
• an agent needs a deterministic scope rather than a judgement call
• a change looks trivial and you want to check whether it actually is

Operating Principles

• Tags come from the diff, not from the author. "It's just a refactor" is a claim; new-public-export is evidence.
• Added lines drive hunk tags. Read + lines. Removed lines matter for deletions of tests and guards, and nothing else here.
• Relevance is a filter, not a discount. A practice out of scope is out of scope for this change; it does not become optional for the project.
• Any auth, secret, migration, or dependency signal wins. These escalate immediately. There is no "small auth change".
• Under-tagging is the expensive error. A false positive costs a check run. A false negative ships the defect. When a rule nearly matches, tag it.
• Deleted guards are changes. A removed test, a removed validation, a loosened type - those are risk-increasing edits, not neutral cleanup.
• Path is not proof. A file under auth/ is auth-relevant; a file elsewhere that verifies a token is too. Read the hunk.

Workflow

Phase 0: Pin the diff

git diff --name-status <base>...HEAD      # three-dot: compares against the merge base
git diff <base>...HEAD -- <path>          # per-file hunks
git log <base>..HEAD --oneline

Use main...HEAD for a branch, HEAD for uncommitted work. Confirm the base ref resolves and the diff is non-empty before going further - a bad ref silently produces an empty scope, which reads as "nothing to check".

Exclude non-source noise from tagging, but list what you excluded: lockfiles are excluded from hunk tagging yet are themselves a added-dependency signal; snapshots, generated clients, and build output are excluded; docs are excluded unless they are the deliverable.

Phase 1: Assign file tags

Apply the path rules in ./resources/tag-rules.md to every changed path. File tags describe where the change landed: source, test, config, infra, public-api, schema, auth, critical-path, db-migration, ai, secret-suspect, generated.

A path can carry several tags. A path that looks like both test and source is a test.

Phase 2: Assign hunk tags

For each changed source file, read the added lines and apply the content rules in ./resources/tag-rules.md. Hunk tags describe what changed: new-public-export, new-endpoint, modified-auth, secret-like-string, sql-string, exec-call, db-migration, modified-error-handling, modified-request-schema, added-dependency, modified-prompt, removed-test, loosened-type, new-external-call.

Do this by reading, not only by pattern matching. The patterns are a floor: they catch the common shapes and miss anything expressed unusually. If a hunk introduces a new public capability by any route, it is new-public-export.

Phase 3: Resolve relevant practices

Apply ./resources/relevance-recipes.md. Each practice declares the tags that make it relevant; a practice is in scope if any of its declared tags is present. Record, per practice, which tag triggered it - that is what makes the scope reviewable.

Then subtract: a practice not in the project's quality contract is not in scope. If a contract exists (see deriving-a-quality-contract), intersect with it and note practices that would have been triggered but are not contracted. That list is useful evidence next time the contract is reviewed.

Phase 4: Rank and report

Use ./resources/change-scope-template.md. Rank by escalation:

State the blind spots explicitly: what the tags cannot see. A pure-rename diff that changes behaviour through a config default, a change whose risk lives in the data rather than the code, a removal whose consequence is elsewhere in the system. The tag grammar is mechanical and therefore blind in known ways - name them rather than implying coverage.