Surgical Diff

surgical-diff

Audit a diff against its stated intent. Every changed line must trace to the request.

Trigger on

• "review this diff"
• "is this surgical"
• "did I change too much"
• "audit this patch"
• "scope-check this PR"
• User pastes a diff plus a statement of what the change was supposed to do

Input shapes

| shape | handling | |-------|----------| | unified diff + stated intent | full analysis | | diff only, no intent | ask for intent first, do not guess | | file-before + file-after | treat as implicit diff | | PR description + diff | extract intent from description | | commit message + diff | extract intent from subject line |

Analysis passes

Pass 1 — scope trace

For each changed line: does this line solve the stated request? Mark yes / no / indirect.

Pass 2 — drift detection

Universal drift flags:

| drift type | examples | |------------|----------| | style | quote style changes, whitespace, trailing commas | | type theatre | type hints added to unrelated functions | | doc theatre | docstrings added to unrelated functions | | rename | variable / function renames not required by fix | | scope creep | new features adjacent to the fix | | unauthorized delete | pre-existing dead code removed | | dependency creep | new import not needed by the fix | | test theatre | unrelated tests added alongside the fix |

Language-specific drift:

| language | flag when you see | |----------|-------------------| | Python | f-string conversion of unrelated % or .format() lines; list → List type annotation backport on unrelated functions | | TypeScript | any → specific type on unrelated signatures; interface → type or reverse | | JavaScript | var → const/let on unrelated lines; function → arrow on unrelated | | Go | error wrap reformat on unrelated errors; interface{} → any swap on unrelated | | Rust | unwrap() → ? conversion on unrelated call sites | | Java | var local-type inference backport on unrelated locals |

Pass 3 — orphan check

After the edit, are imports / variables / functions orphaned?

| orphan type | action | |-------------|--------| | Import your edit orphaned | remove | | Variable your edit orphaned | remove | | Function your edit orphaned | remove | | Orphan that pre-existed | leave. flag only if user asks about it |

Output

stated intent: {one line}
lines changed: {n}
lines tracing to intent: {n} ({pct}%)

drift flags:
  style: {line numbers}
  type-theatre: {line numbers}
  doc-theatre: {line numbers}
  rename: {line numbers}
  scope-creep: {line numbers + description}
  unauthorized-delete: {line numbers}
  dependency-creep: {line numbers}
  language-specific: {type + line numbers}
  orphans-created: {list — remove}
  orphans-untouched: {list — leave, informational}

minimal diff (only lines tracing to intent):
```diff
{the subset}

verdict: {surgical | minor drift | scope creep | rewrite needed} reasoning: {one line}

## Verdict thresholds

| tracing % | verdict |
|-----------|---------|
| ≥ 95 | surgical |
| 80–94 | minor drift (acceptable with flags) |
| 50–79 | scope creep (split into multiple PRs) |
| < 50 | rewrite needed (start from stated intent again) |

## Hard rules
- Never recommend deleting pre-existing dead code unless user asked.
- Style drift is a flag, not an error. Flag it, let the user decide.
- If stated intent is missing, do not analyze. Ask for it first.
- If the diff is under 5 lines, skip and say "too small to drift".
- Type hints on NEW code do not flag. Type hints added to UNRELATED code do.
- Tests added that cover the stated fix do NOT flag. Tests unrelated to the fix do.
- Whitespace-only diffs (reformat commits) are flagged as their own category — suggest splitting into a separate PR.
- Never "fix" the diff yourself. Report and propose. The user decides.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Vix0007](https://github.com/Vix0007)
- **Source:** [Vix0007/vixero-skills](https://github.com/Vix0007/vixero-skills)
- **License:** MIT
- **Homepage:** https://vixdev.cloud/

Install and usage instructions live in the source repository linked above.