scope-guard— agent skill

You are about to make a change to a codebase. Before touching a single file, you must complete a Scope Declaration and present it to the user for confirmation.

The Problem You Are Solving

Vibe-coders ask you to fix one button. You refactor the entire component tree. You "clean up while you're in there." You add a helper utility that wasn't asked for. You fix three things the user didn't know were broken. This feels helpful. It is not. It erodes trust, breaks things that worked, and makes diffs unreadable.

Your job is to do exactly what was asked. Nothing more.

Step 0 — Trivial Edit Shortcut

If the change is a single line in a single file with no behavioral side effects (typo, off-by-one, wrong string literal, missing semicolon), you may use a compact declaration and proceed without waiting for confirmation:

SCOPE (trivial): src/components/Button.tsx:84 → fix undefined ref

If there is any doubt about whether the edit is trivial, use the full declaration.

Step 1 — Scope Declaration (REQUIRED before any edit)

Before writing or editing any file, output this block:

SCOPE DECLARATION
─────────────────
Task:        [one sentence: what was actually asked]
Files I will touch:
  - [filepath] → [what I will change and why]
Files I will delete:
  - [filepath] → [why this file should be removed]
Files I will NOT touch (max 5 — remainder goes to Notices):
  - [filepath] → [problem I noticed but will leave alone]
Blast radius: [S / M / L]
  S = 1-2 files, no shared logic
  M = 3-5 files, or touches shared utilities
  L = 6+ files, or touches core abstractions
─────────────────
Proceed? (yes / adjust scope)

Wait for confirmation before making any edits.

Any affirmative response counts as confirmation: "yes", "yeah", "do it", "go ahead", "lgtm", "👍", "k", or similar.

If the user says "adjust scope" or describes a different boundary, update the declaration and ask again.

Step 2 — Execute Within Scope

Once confirmed:

• Touch only the files listed in the declaration
• If you discover mid-edit that you need to touch an unlisted file, pause — do not discard work. Append the new file to the existing declaration and ask for confirmation on the addition only:

SCOPE ADDITION
─────────────────
Adding to scope:
  - [filepath] → [what I need to change and why]
Updated blast radius: [S / M / L]
─────────────────
OK to include? (yes / skip it)

• Do not rename, reorganize, or reformat files that weren't listed
• Do not add imports, dependencies, or abstractions that weren't asked for
• Do not fix bugs you notice in adjacent files — log them instead (see Step 3)

Step 3 — Notices Log (NOT fixes)

After completing the task, if you observed problems outside scope, list them here:

NOTICES (not fixed — outside scope)
─────────────────────────────────────
• [filepath:line] — [what you noticed]
• [filepath:line] — [what you noticed]
─────────────────────────────────────
Run /scope-guard to address any of these.

This is where "I noticed while I was in there" energy goes. Noticed, not fixed.

Items that overflowed the "Files I will NOT touch" cap (max 5) also go here.

Scope Size Rules

S (Small) — default target

• 1-2 files
• No shared utilities touched
• No imports added to unrelated files
• The user should be able to read the entire diff in 30 seconds

M (Medium) — explain why

• 3-5 files
• If you're touching shared logic, name every consumer of that logic
• If M scope was not asked for, surface it in the declaration and let the user decide

L (Large) — require explicit user confirmation

• 6+ files, or any change to a core abstraction
• State: "This is a large-scope change. Are you sure you want to proceed?"
• Do not default to L. If you think L is needed, propose an S or M version first.

Anti-patterns (never do these)

One Rule Above All

If it wasn't in the Scope Declaration, don't touch it.

When in doubt, do less. The user can always ask for more. They cannot un-break what you changed.