Codebase Scope Guard

The Problem

You ask your AI agent to fix a bug in one function.

It fixes the bug. It also refactors three adjacent functions, renames a variable across four files, and "cleans up" an import pattern it didn't like — in files you didn't ask it to touch.

Now your diff is enormous. You can't tell what was the fix and what was the agent's unsolicited opinion. The tests that were passing aren't anymore, and tracking down why takes longer than the original bug would have.

Three failure modes compound each other:

Blind editing — The agent writes code without reading the structure it's modifying. It doesn't check what calls the function, what the function exports, or whether shared utilities are affected. It produces code that looks right but breaks things downstream.

Pattern mixing — The codebase has two ways of handling errors. The agent picks whichever it saw most recently and applies it alongside the existing pattern. Now both coexist. Neither is wrong, but the inconsistency becomes permanent.

Scope drift — The agent was asked to change one thing. It changed seven. Five of those changes were "obvious improvements" that you didn't ask for, don't want right now, and can't easily separate from the actual fix.

How It Works

This skill installs three guards on every coding task.

Guard 1 — Read Before Write

Before modifying any file, the agent reads:

• Exports — what the target file or function exposes to the rest of the codebase
• Direct callers — what calls the function or imports the module being changed
• Shared utilities — any helper, constant, or type that the target code depends on

This is not optional and not skipped for "small" changes. The agent that doesn't know what calls a function before changing its signature is the agent that breaks things silently.

[Read check]: 
- Target file: [name] — exports: [list]
- Direct callers: [list or "none found"]
- Shared utilities referenced: [list or "none"]
- Structural intent confirmed: [one sentence — what this code is designed to do]

Guard 2 — Conflict Resolution

When the codebase contains two or more conflicting patterns (naming conventions, error handling styles, state management approaches, import organization), the agent does not average them or apply both.

It picks one. It explains why. It reports the other as a cleanup candidate.

[Pattern conflict detected]:
- Pattern A: [description] — adopted, reason: [one line]
- Pattern B: [description] — cleanup candidate, not applied

Mixing conflicting patterns to avoid making a decision is not neutrality — it is permanent inconsistency.

Guard 3 — Scope Discipline

The agent makes only the changes that were requested. It does not:

• Refactor adjacent code that "could be cleaner"
• Rename things that weren't mentioned
• Add error handling that wasn't asked for
• Reorganize imports as a side effect
• Fix anything it notices while working on something else

If the agent touches a file that was not part of the declared scope, it reports the reason before doing so. "I touched it because it seemed related" is not a sufficient reason.

[Scope report]: Files changed: [list]
Out-of-scope touches: [file — reason] or "none"

Before / After

Before:

Agent: "I fixed the authentication bug. I also cleaned up the token validation logic in three other files since I was in the area, and standardized the error format across the auth module."
Human: [reviews diff] — 47 files changed.

After (with Codebase Scope Guard):

Agent: [Read check] — auth.py exports: validate_token, refresh_token. Direct callers: middleware.py, api/routes.py. Shared utilities: jwt_utils.
[Scope report] — Files changed: auth.py. Out-of-scope touches: none.
[Pattern conflict] — Error handling: dict-style in auth.py, exception-style in middleware.py. Adopted dict-style (matches auth.py convention). Cleanup candidate: middleware.py exception pattern.

Hard Rules

1. Read before write, every time. The read check is not skipped for small changes, single-line edits, or tasks where the agent is "confident" about the structure. Confidence is not knowledge of the current codebase state.

2. Exports and callers must be confirmed, not assumed. "This function is probably only called from one place" is not a read check. The callers must be identified.

3. Conflicting patterns are resolved by choosing, not mixing. When two patterns exist, one is adopted and the other is flagged as a cleanup candidate. Applying both is a violation.

4. Scope is declared before work begins. The files to be changed are identified at the start. Any deviation from that list requires a reported reason before the change is made.

5. Unsolicited improvements are proposals, not implementations. If the agent notices something that could be improved outside the declared scope, it records it as a suggestion — it does not implement it without being asked.

6. Scope report is mandatory at completion. Every task ends with a list of files changed and explicit confirmation (or explanation) of any out-of-scope touches. A task without a scope report is not complete.