Philosophy
When to Use
When NOT to Use
Quick Start
1. Score the Feature
2. Check Against Backlog
3. Verify Branch Budget
4. Monitor Thresholds
Core Workflow
Step 1: Calculate Worthiness (scope-guard:worthiness-scored)
Step 2: Compare Against Backlog (scope-guard:backlog-compared)
Step 3: Check Branch Budget (scope-guard:budget-checked)
Step 4: Document Decision (scope-guard:decision-documented)
Anti-Overengineering Rules
Backlog Management
Directory Structure
Queue Rules
Adding to Queue
Integration Points
With superpowers:brainstorming
With superpowers:writing-plans
During superpowers:executing-plans
Required TodoWrite Items
Related Skills
Module Reference

Scope Guard

Prevents overengineering by both Claude and human during the brainstorm→plan→execute workflow. Forces explicit evaluation of every proposed feature against business value, opportunity cost, and branch constraints.

Philosophy

Core Belief: Not all features deserve implementation. Most ideas should be deferred to backlog until proven necessary.

Three Pillars:

Worthiness Scoring - Quantify value vs cost before building
Opportunity Cost - Compare against existing backlog
Branch Discipline - Respect size thresholds

When To Use

During brainstorming sessions before documenting designs
During planning sessions before finalizing implementation plans
When evaluating "should we add this?" decisions
Automatically via hooks when branches approach thresholds
When proposing new features, abstractions, or patterns

When NOT To Use

Bug fixes with clear, bounded scope
Documentation-only changes
Trivial single-file edits (< 50 lines)
Emergency production fixes

Quick Start

1. Score the Feature

Use the Worthiness formula:

(Business Value + Time Criticality + Risk Reduction) / (Complexity + Token Cost + Scope Drift)

Verification: Run the command with --help flag to verify availability.

See decision-framework.md for details.

Thresholds:

> 2.0 → Implement now
1.0 - 2.0 → Discuss first
< 1.0 → Defer to backlog

2. Check Against Backlog

Compare against docs/backlog/queue.md:

Does it beat top queued items?
Is there room in branch budget?

3. Verify Branch Budget

Default: 3 major features per branch

If at capacity, must drop existing feature, split to new branch, or justify override.

4. Monitor Thresholds

Watch for Yellow/Red zones:

Lines: 1000/1500/2000
Commits: 15/25/30
Days: 3/7/7+

See branch-management.md for monitoring.

Core Workflow

Step 1: Calculate Worthiness (`scope-guard:worthiness-scored`)

Score each factor (1, 2, 3, 5, 8, 13):

Value Factors: Business Value, Time Criticality, Risk Reduction
Cost Factors: Complexity, Token Cost, Scope Drift

Details: decision-framework.md

Step 2: Compare Against Backlog (`scope-guard:backlog-compared`)

Check docs/backlog/queue.md for existing items
Compare Worthiness Scores
New item must beat top queued item OR fit within branch budget

Step 3: Check Branch Budget (`scope-guard:budget-checked`)

Count current features in branch. If at budget (default: 3), new feature requires:

Dropping an existing feature, OR
Splitting to new branch, OR
Explicit override with justification

Step 4: Document Decision (`scope-guard:decision-documented`)

Record outcome:

Implementing: Note Worthiness Score and budget slot
Deferring (MANDATORY STEPS):
1. Create GitHub issue immediately - See github-integration.md Steps 1-3
2. Mark scope-guard:github-issue-created complete
3. Create Discussion - See github-integration.md Step 4. Prompt: "Creating a Discussion with full reasoning context. [Y/n]" Publishing is the default. If the user explicitly declines, skip Discussion creation. If publishing fails, continue.
4. Optionally add to docs/backlog/queue.md with issue link
Rejecting: Document why (low value, out of scope)

IMPORTANT: Deferral is NOT complete until a GitHub issue exists. This prevents context loss when branches are merged or abandoned.

Anti-Overengineering Rules

Key Principles:

Ask clarifying questions BEFORE proposing solutions
No abstraction until 3rd use case
Defer "nice to have" features
Stay within branch budget

See anti-overengineering.md for full rules and red flags.

Backlog Management

Directory Structure

**Verification:** Run the command with `--help` flag to verify availability.
docs/backlog/
├── queue.md              # Active ranked queue
└── archive/
    ├── ideas.md          # Deferred feature ideas
    ├── optimizations.md  # Deferred performance work
    ├── refactors.md      # Deferred cleanup
    └── abstractions.md   # Deferred patterns

Verification: Run the command with --help flag to verify availability.

Queue Rules

Max 10 items in active queue
Items older than 30 days without pickup → move to archive
Re-score monthly or when project context changes

Adding to Queue

When deferring, add to docs/backlog/queue.md:

| Rank | Item | Worthiness | Added | Branch/Epic | Category |
|------|------|------------|-------|-------------|----------|
| 1 | [New item description] | 1.8 | 2025-12-08 | current-branch | idea |

Verification: Run the command with --help flag to verify availability.

Re-rank by Worthiness Score after adding.

Integration Points

With superpowers:brainstorming

At end of brainstorming, before documenting design:

List all proposed features/components
Score each with Worthiness formula
Defer items scoring < 1.0 to backlog
Check branch budget for remaining items

Self-invoke prompt: "Before documenting this design, let me evaluate the proposed features with scope-guard."

With superpowers:writing-plans

Before finalizing implementation plan:

Verify all planned items have Worthiness > 1.0
Compare against backlog queue
Confirm within branch budget
Document any deferrals

Self-invoke prompt: "Before finalizing this plan, let me verify scope with scope-guard."

During superpowers:executing-plans

Periodically during execution:

Run threshold check: lines, files, commits, days
Warn if Yellow zone reached
Require justification if Red zone reached

Self-invoke prompt: "This branch has grown significantly. Let me check scope-guard thresholds."

Required TodoWrite Items

When evaluating a feature, create these todos:

scope-guard:worthiness-scored
scope-guard:backlog-compared
scope-guard:budget-checked
scope-guard:github-issue-created (MANDATORY if deferring - blocks step 5)
scope-guard:decision-documented

Note: Step 4 (github-issue-created) is REQUIRED when deferring items. You cannot mark decision-documented complete without first completing github-issue-created for deferrals.

Related Skills

superpowers:brainstorming - Ideation workflow this guards
superpowers:writing-plans - Planning workflow this validates
imbue:review-core - Review methodology pattern

Module Reference

decision-framework.md - Worthiness formula, scoring, thresholds
github-integration.md - MANDATORY issue creation for deferrals
anti-overengineering.md - Rules, patterns, red flags
branch-management.md - Thresholds, monitoring, zones
baseline-scenarios.md - Testing scenarios and validation

Troubleshooting

Common Issues

Command not found Ensure all dependencies are installed and in PATH

Permission errors Check file permissions and run with appropriate privileges

Unexpected behavior Enable verbose logging with --verbose flag

Scope Guard

Philosophy

When To Use

When NOT To Use

Quick Start

1. Score the Feature

2. Check Against Backlog

3. Verify Branch Budget

4. Monitor Thresholds

Core Workflow

Step 1: Calculate Worthiness (scope-guard:worthiness-scored)

Step 2: Compare Against Backlog (scope-guard:backlog-compared)

Step 3: Check Branch Budget (scope-guard:budget-checked)

Step 4: Document Decision (scope-guard:decision-documented)

Anti-Overengineering Rules

Backlog Management

Directory Structure

Queue Rules

Adding to Queue

Integration Points

With superpowers:brainstorming

With superpowers:writing-plans

During superpowers:executing-plans

Required TodoWrite Items

Related Skills

Module Reference

Troubleshooting

Common Issues

Step 1: Calculate Worthiness (`scope-guard:worthiness-scored`)

Step 2: Compare Against Backlog (`scope-guard:backlog-compared`)

Step 3: Check Branch Budget (`scope-guard:budget-checked`)

Step 4: Document Decision (`scope-guard:decision-documented`)

scope-guard

Table of Contents