Scope change workflow for modifying, adding, or removing requirements at any point during a build. Triggers on "change:" prefix, "I forgot to add", "actually I also want", "can we add", "remove X from scope", "I changed my mind about", "before we continue add", "one more thing", "I want to change the spec", "revert the X change". Handles new additions, removals, renames, backlog operations, and reverting previous changes. Assesses impact before touching any file. Updates all affected docs in the correct order. If BRIEF.md doesn't exist, updates SPEC.md and DECISIONS.md only.
Handles scope changes at any point during the build — safely, in the right order. Always assesses impact first. Always waits for confirmation. Never edits files speculatively.
Always run in Plan Mode (Shift+Tab). Do not write any code in this skill.
Drift prevention — scope changes must be logged explicitly. An informal "just quickly add X" mid-task produces a codebase that doesn't match its documentation. When review: runs, it finds violations with no logged context. change: prevents this by stopping work, assessing impact, and updating all affected documents before building continues.
Any time the user signals a scope change:
change: add dark mode before we build screenschange: remove social login — email onlychange: add push notifications to backlogchange: promote push notifications to activechange: rename "ideas" to "posts" throughoutchange: revert the PDF attachment change we made last weekExtract:
If ambiguous, ask ONE clarifying question.
Confirm:
"Got it — you want to [add/remove/modify/revert] [X]. Let me check what this affects."
Read in order. Skip files that don't exist — note their absence:
BRIEF.md (if exists) — original problem, core value, v1 feature setvibe/ARCHITECTURE.md (if exists) — established patterns and principlesvibe/SPEC.md — what is currently in scopevibe/SPEC_INDEX.md — feature list and statevibe/TASKS.md — active work, done vs pendingvibe/PLAN.md — current architecturevibe/CODEBASE.md — what has actually been builtIf active feature or bug folder exists (from TASKS.md active block):
8. Active FEATURE_TASKS.md or BUG_TASKS.md
Before any code — doc updates only. Zero retrofit. Between tasks — last task done, next not started. New tasks slot cleanly. Mid-phase — some tasks done. May need to pause and insert new tasks. Cross-phase — change affects already-built architecture or data layer. Retrofit needed. Post-completion — fully built and conformance-checked. Full retrofit + regression strategy.
If vibe/PLAN.md exists and has a Section 6 feature map — run this check:
Find the affected feature in the feature map.
Extract:
depended_on_by — features that cannot start until this one is doneshared_data — entities this feature creates that others consumeparallel_candidates — features planned to run alongside this oneFor each feature in depended_on_by:
For each shared_data entity this change affects:
Surface cascade clearly in Step 4:
Feature map cascade:
⚠️ [Feature X] depends on [changed feature] — [built/in progress/planned]
Impact: [what breaks or needs updating]
⚠️ [Feature Y] reads [affected entity] — [built/in progress/planned]
Impact: [schema change affects Y's data layer]
✅ [Feature Z] — no dependency on changed feature
If no feature map in PLAN.md — skip this check, note its absence.
If the change is reverting a previous scope change (e.g. "remove the PDF feature we added"):
Change requested: [one sentence plain English]
Build stage: [Before code / Between tasks / Mid-phase / Cross-phase / Post-completion]
What this affects:
- Spec: [what changes in plain English]
- Tasks: [N new / M retrofit / K removed — plain English]
- Code already built: [affected — what needs revisiting / not affected]
- Architecture: [patterns affected / not affected]
Feature map cascade: [None / see cascade findings above]
- [Feature X] — [built/planned] — [impact]
- [Feature Y] — [built/planned] — [impact]
Effort: [Small — doc only / Medium — new tasks / Large — retrofit needed]
Recommendation: [Add to backlog / Insert before next task / Address now with retrofit]
Ready to proceed? (or "add to backlog instead")
Wait for confirmation. Never touch files before confirmation.
Always updated together — never one without the other.
Adding a feature: Add section with acceptance criteria. Add update note at top:
> ⚠️ Last updated: [date] · Scope addition: [what] · Build stage: [stage]
Removing a feature: Strikethrough — never delete:
~~## Feature: [Name]~~
> ⚠️ Removed: [date] · Reason: [why] · See DECISIONS.md D-[ID]
Modifying: Edit in-place, mark what changed:
> ~~Original: [old]~~
> Changed [date]: [new] — [reason]
SPEC_INDEX.md update: Update relevant entry. Update sync date.
Save both.
If BRIEF.md doesn't exist — skip this step, note it in the user's summary.
BRIEF.md must reflect current reality — not the original idea.
Feature added/removed: Update v1 feature set table. Core value changed: Update core value section with change and reason. Stack changed: Update tech stack table. Always append:
- Scope change [date]: [what changed and why — one line]
Save updated BRIEF.md.
Only if change affects: patterns, conventions, folder structure, state management, API design, testing philosophy, or tech decisions.
Add new pattern or update changed decision. Always add changelog line if updated:
> 📝 [date] · Scope change D-[ID] — [what changed architecturally]
Skip and state explicitly if no architecture impact.
Only if change affects: data model, API shape, architecture layers, or phase structure.
Add changelog line at top. Update relevant sections in-place. Skip and state explicitly if no impact.
All TASKS.md updates in plain English. Task IDs stay for agent sequencing.
Adding new tasks — expand inline feature block, insert in correct sequence. Adding retrofit tasks — add HM-001-R style entries inline with plain English. Removing tasks — strikethrough inline with plain English reason. Reverting — add retrofit tasks for any completed work that needs undoing.
Always update "What just happened" and "What's next":
## What just happened
🔄 Scope change: [plain English — what changed and why]
[N new tasks / M retrofits / K removed]
## What's next
⬜ [TASK-ID] · [plain English next task]
Say "next" to continue.
---
### D-[ID] — [Short title]
- **Date**: [date] · **Type**: scope-change
- **Trigger**: change: command — user-initiated
- **Build stage**: [stage]
- **What changed**: [exact description]
- **Why**: [user's stated reason]
- **Before**: [original scope]
- **After**: [new scope]
- **Tasks affected**: New: [IDs] · Retrofit: [IDs] · Removed: [IDs]
- **Folders affected**: [feature/bug folders or "none"]
- **Architecture impact**: [Yes — what / None]
- **BRIEF.md updated**: [Yes / No — didn't exist]
- **Approved by**: human
---
Update only if: the change removes/renames something built, or establishes a new pattern. Skip and state explicitly if no update needed.
Add to vibe/backlog/[YYYY-MM-DD]-[feature-slug].md:
# [Feature Name]
> Added: [date] | Status: deferred
## What
[Description]
## Why deferred
[Reason]
## Effort estimate
[Small / Medium / Large]
## Dependencies
[What must be done before this]
## Promote when
[Condition]
## Promote with