tmusser/ai-engineering-skills / skills/scope-freeze
scope-freeze
VerifiedExplicitly limit blast radius before any implementation or file changes.
Scope Freeze
Purpose
Prevent uncontrolled changes by defining a narrow, enforceable boundary. This freezes write scope, not discovery.
When to use
Immediately before editing files or running state-changing commands.
Inputs
- SPEC.md / PLAN.md / TODO.md
- Selected task
- Current repo state
- Git base used to judge the implementation diff
- Optional SPEC implementation diff budget
Workflow
-
Name the exact task.
-
List allowed files/folders as exact paths, directory prefixes, or globs.
-
Do not use repo-wide catch-all patterns (
*,**,**/*) inAllowed writes. If the task genuinely spans multiple areas, enumerate the narrowest relevant prefixes and set a changed-file budget. -
List read-only files/folders.
-
List forbidden paths and operations.
-
Set max files changed and rename/deletion rules when helpful. If SPEC.md has an enforced implementation diff budget, keep the scope's hard file cap at or below that accepted file budget unless scope is renegotiated before implementation.
-
List allowed commands.
-
List compatibility seams and test-integrity triggers before editing.
-
Define clear stop condition.
-
Note that reads/searches are allowed unless explicitly forbidden.
-
Persist the canonical block as
SCOPE.mdbefore the first implementation write when the route invokesscope-freezeandscripts/scope_gate.pyis available. -
After the implementation diff is complete, run:
python scripts/scope_gate.py --base <frozen-base> -
Treat scope-gate
FAILas a hard stop: revert the violating write or renegotiate scope before continuing. TreatREVIEW_REQUIREDas unresolved review, not implicit permission.
Do not widen SCOPE.md after an out-of-scope change merely to make the gate pass. A legitimate scope expansion must be surfaced and agreed before the newly allowed write.
The scope gate's Max files changed is a hard write-boundary rule and remains a FAIL when exceeded. An optional SPEC implementation diff budget is different: verify_gate.py treats file/added-line overruns as REVIEW_REQUIRED so a legitimate but unexpectedly large patch can be reconsidered rather than mislabeled as a functional failure.
Outputs
Canonical output block:
SCOPE FREEZE
Task: ...
Allowed writes: ...
Read-only: ...
Forbidden: ...
Compatibility seams to preserve:
- Public imports / APIs: ...
- CLI behavior: ...
- Output schema: ...
- Fixture/data meaning: ...
- Existing tests that must remain meaningful: ...
Test integrity:
- Existing tests may be added to: yes/no
- Existing tests may be changed only if: ...
Review required if:
- tests changed
- dependencies changed
- protected paths touched
- compatibility seams changed
Max files changed: ...
Renames allowed: yes/no
Deletions allowed: yes/no
Allowed commands: ...
Stop when: ...
Invalid if: ...
Use path/glob entries for the machine-enforceable portions of Allowed writes, Read-only, and Forbidden. Allowed writes must remain meaningfully narrower than the repository root; repo-wide catch-all globs are invalid scope-freeze output. Non-path forbidden operations remain part of the human contract but cannot be proven by a file-diff gate.
See Deterministic Scope Gate for status semantics and supported review triggers.
Success looks like
- The canonical block above exists before implementation writes.
Allowed writesnames a real blast-radius boundary rather than a repo-wide catch-all.- The final live diff receives scope-gate
PASS, or an explicit human resolves everyREVIEW_REQUIREDtrigger. - No violating write is justified retroactively by silently widening the scope artifact.
Stop conditions
- Scope is narrow enough for safe implementation.
- Task requires changes outside boundary → pause and renegotiate before the write.
- Scope gate returns
FAIL→ stop, revert, or renegotiate. - Scope gate returns
REVIEW_REQUIRED→ obtain the named review before claiming completion.
Anti-patterns
- Roaming the entire repo for a small fix.
- Using
*,**, or**/*asAllowed writesand calling the result scoped. - Expanding scope because "nearby code looked easy."
- Running write commands before boundary is agreed.
- Editing
SCOPE.mdafter a violation to manufacture compliance. - Treating an allowed path as proof that all behavior inside it is authorized.
- Forbidding necessary discovery reads.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |