Scope Guard

The cheapest feature is the one you never build.

Scope-guard weighs each proposed feature against its value,

its cost, and the branch budget, so only what is earned ships.

Table of Contents

• 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, and 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: 1. Worthiness Scoring - Quantify value vs cost before building 2. Opportunity Cost - Compare against existing backlog 3. 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)

1. Check docs/backlog/queue.md for existing items 2. Compare Worthiness Scores 3. 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: 1. List all proposed features/components 2. Score each with Worthiness formula 3. Defer items scoring < 1.0 to backlog 4. 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: 1. Verify all planned items have Worthiness > 1.0 2. Compare against backlog queue 3. Confirm within branch budget 4. Document any deferrals

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

During superpowers:executing-plans

Periodically during execution: 1. Run threshold check: lines, files, commits, days 2. Warn if Yellow zone reached 3. 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:

1. scope-guard:worthiness-scored 2. scope-guard:backlog-compared 3. scope-guard:budget-checked 4. scope-guard:github-issue-created (MANDATORY if deferring - blocks step 5) 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
• imbue:karpathy-principles - Compact four-principle synthesis covering scope, simplicity, surgical edits, and verifiable goals
• See docs/quality-gates.md#skill-level-quality-gate-composition for the full gate-skill federation graph

Module Reference

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

Anti-Overengineering Rules

Patterns and rules to prevent overengineering during development.

Core Rules

1. Questions Before Solutions

Always ask clarifying questions BEFORE proposing solutions:

• What problem are you solving?
• Where does the application run?
• Who reads the output?
• What's the current pain point?
• What's the stated requirement?

Anti-pattern: Offering 3-5 approaches before understanding the need.

2. No Abstraction Until Third Use Case

Rule: Do NOT create abstractions until you have at least 3 concrete use cases.

Examples:

• Two config formats? → Two simple functions
• Three config formats? → NOW consider abstraction
• "We might need..." → NOT a use case

Explicitly refuse:

• Base classes for 1-2 implementations
• Strategy patterns before third strategy
• Plugin systems for hypothetical future needs

3. Defer "Nice to Have" Features

Rule: Features without clear business value go to backlog.

Test: If you can't answer "Why now?", defer it.

Common rationalizations to block:

• "Users might want this"
• "We'll need this eventually"
• "It's a good practice"
• "Modern applications have this"

4. Stay Within Branch Budget

Default budget: 3 major features per branch

When at budget, adding new feature requires:

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

Budget Check Template:

Branch: [branch-name]
Budget: 3 features

Current allocation:
1. [Primary feature]
2. [Secondary feature]
3. [OPEN SLOT or Third feature]

Proposed: [New feature]
Decision: [Fits/Requires split/Requires drop]

Anti-Rationalization Checklist

If you find yourself thinking:

Red Flags

Red flags that indicate overengineering:

• Enjoying the solution more than solving the problem
• Adding "flexibility" for unspecified future needs
• Creating abstractions before the third use case
• Discussing patterns before discussing requirements
• Branch metrics climbing without proportional value delivery

Cargo Cult Overengineering

Additional red flags from cargo cult programming:

The AI Amplification Problem

AI makes cargo cult overengineering worse because:

1. Confident Explanations - AI sounds authoritative even when wrong 2. Complete Solutions - AI provides full implementations for vague requirements 3. Enterprise Defaults - AI often suggests "scalable" solutions for simple problems 4. No Pushback - AI won't ask "Do you really need this?"

Mitigation: When AI suggests an approach, ask:

• "What simpler alternatives exist?"
• "What are the trade-offs?"
• "What's the minimum version that works?"

Cargo Cult YAGNI

YAGNI (You Aren't Gonna Need It) applies especially to:

Rule: If justification uses "might", "could", or "eventually" - defer to backlog.

See ../../proof-of-work/modules/anti-cargo-cult.md for understanding verification protocols.

"While We're Here" Pattern

Anti-pattern: Scope expansion because you're "already working in this area"

Examples to block:

• "While we're here, let's also refactor..."
• "For consistency, we should update..."
• "Since we're touching this file, we could..."

Response: Evaluate the additional work with Worthiness formula. If < 1.0, defer to backlog.

Agent Psychosis Warning Signs

Source: Ronacher: Agent Psychosis

AI agents create unique overengineering risks through psychological dependency patterns:

Warning Signs to Monitor

The One-Directional Relationship

"The relationship is fundamentally one-directional. The agent reinforces whatever direction the user pushes it toward, lacking genuine critical thinking."

Reality Check Questions:

• "Would a skeptical senior engineer approve this?"
• "Can I explain WHY, not just WHAT?"
• "Have I received feedback from someone not using AI?"

Vibe Coding Red Flags

The 6-Month Wall

Without rigorous oversight, AI-assisted projects hit the "6-month wall" - the point where accumulated debt becomes unmaintainable. Watch for:

• Technical debt accumulating silently ("shadow debt")
• "Mystery code" that works by coincidence
• Unable to explain why certain code exists
• Tests that pass but don't verify behavior

Prevention Protocol

Before claiming any AI-assisted work is complete:

1. Understanding Gate: Can you explain every significant line without referencing AI? 2. External Review: Has someone NOT using AI reviewed this? 3. Refactoring Balance: Did you refactor existing code, not just add new? 4. Test Depth: Do tests cover failures, not just success?

See ../../proof-of-work/modules/anti-cargo-cult.md for full understanding verification protocol.

Baseline Testing Scenarios for scope-guard

Purpose

Document Claude's behavior WITHOUT this skill to identify failure modes, then validate the skill addresses them.

---

Test Execution Summary

Date: 2025-12-08 Status: All scenarios pass with skill loaded

---

Scenario 1: Feature Creep During Brainstorming

Context: User asks Claude to help design a simple logging utility.

Task: "Help me brainstorm a logging solution for my Python app"

Expected Issues (without skill):

• Claude proposes multiple log levels, formatters, handlers, rotation, remote shipping
• Suggests abstraction layers "for flexibility"
• Mentions "we might want to add" features
• No evaluation of which features actually matter for the use case

Baseline Response (RED Phase):

Proposed 4 different approaches:
1. Python's built-in logging module
2. Structured logging with structlog
3. Simple print-based with rich
4. Hybrid approach

Suggested features: JSON logging, formatters, handlers, rotation,
multi-destination support, context binding, request tracking.

No questions asked about actual needs before proposing solutions.

Failure Mode: Scope expansion without business value assessment

Rationalization Detected: "Battle-tested", "modern observability", "great for..."

GREEN Phase Result:

Asked 7 clarifying questions before proposing anything:
1. What problem are you solving?
2. Where does the application run?
3. Who reads the logs?
4. Current pain point?

Provided minimal 5-line solution as baseline.
Explicitly deferred: structured logging, rotation, distributed tracing.
Stated: "Until you answer the questions, I'm deferring these."

Status: PASS - Questions before solutions, explicit deferrals

---

Scenario 2: "While We're Here" Addition

Context: Claude is implementing a specific feature on a branch.

Task: "Add input validation to the user registration form"

Expected Issues (without skill):

• Claude notices related code and suggests refactoring it
• Proposes adding validation to other forms "for consistency"
• Suggests creating a shared validation library
• Branch grows beyond original scope

Baseline Response (RED Phase):

Offered 8+ additional enhancements:
- Real-time validation feedback
- Password strength meter
- Duplicate email/username checking
- Rate limiting
- Email verification flow
- Accessibility improvements
- Unit tests
- Internationalization
- Shared validation utility module

Rationalization: "Since we're working on registration validation,
I'd also recommend..."

Failure Mode: Scope drift from original task

Rationalization Detected: "While we're here, we should also..." / "For consistency..."

GREEN Phase Result:

Primary Task: Add input validation to registration form (only)

Explicitly Out of Scope:
- Login form improvements
- Password reset flow
- Email verification
- Rate limiting
- CAPTCHA

Worthiness check on additions led to: "Defer to backlog"

Status: PASS - Tight scope, explicit out-of-scope list

---

Scenario 3: Premature Abstraction

Context: User needs to parse two similar but slightly different config formats.

Task: "Parse this YAML config and this JSON config"

Expected Issues (without skill):

• Claude creates an abstract ConfigParser base class
• Implements Strategy pattern for format handling
• Adds plugin system for future formats
• Simple 20-line task becomes 200-line architecture

Baseline Response (RED Phase):

Created ConfigLoader class with:
- load() method with format detection
- load_multiple() for merging configs
- get() method with defaults
- Type hints and docstrings
- Extensibility mentions: "Easy to add new formats (TOML, INI, etc.)"

Total: 50+ lines for a 2-format problem

Failure Mode: Abstraction before third use case

Rationalization Detected: "This will be easier to extend..." / "What if you need to add..."

GREEN Phase Result:

def load_yaml_config(path: str) -> dict:
    with open(path, 'r') as f:
        return yaml.safe_load(f)

def load_json_config(path: str) -> dict:
    with open(path, 'r') as f:
        return json.load(f)

Explicitly refused:

• [NO] ConfigLoader class
• [NO] Format registry
• [NO] Extensibility for TOML/INI/XML

Stated: "No abstraction until 3rd use case exists."

**Status**: PASS - Simplest solution, abstraction explicitly refused

---

## Scenario 4: Branch Threshold Ignorance

**Context**: Branch has grown to 1,800 lines over 6 days with 22 commits.

**Task**: "Let's add one more feature before the PR"

**Expected Issues (without skill)**:
- No acknowledgment of branch size
- No suggestion to split or defer
- Continues adding without evaluating scope
- PR becomes unwieldy for review

**Baseline Response (RED Phase)**:

"I'd be happy to help you add a caching layer!"

No mention of:

• Current branch size (1,800 lines)
• Days on branch (6)
• Commit count (22)

Ready to propose "3-5 different caching approaches"

**Failure Mode**: No threshold awareness

**Rationalization Detected**: "It's almost done..." / "This is related to the existing work..."

**GREEN Phase Result**:

[WARNING] YELLOW ZONE - Multiple Metrics Approaching Red

Caching would push to RED zone. Recommendation: DEFER - Create new branch for caching layer.

**Status**: PASS - Full threshold awareness, recommended split

---

## Scenario 5: Low-Value Feature Acceptance

**Context**: User proposes a "nice to have" feature during planning.

**Task**: "We should also add dark mode support"

**Expected Issues (without skill)**:
- Claude accepts without questioning priority
- No comparison to other pending work
- No assessment of business value vs complexity
- Feature gets planned without scoring

**Baseline Response (RED Phase)**:

"I'd be happy to help you add dark mode support!"

Offered 5 implementation approaches: 1. CSS Custom Properties and prefers-color-scheme 2. CSS Variables and Toggle Component 3. Tailwind dark mode 4. CSS-in-JS Theme Provider 5. Third-party library

No questions about business value or priority.

**Failure Mode**: Acceptance without value assessment

**Rationalization Detected**: "That's a good idea..." / "Users would appreciate..."

**GREEN Phase Result**:

Worthiness Score Calculation:

• Business Value: 1-2 (nice-to-have)
• Time Criticality: 0 (no deadline)
• Risk Reduction: 0

Complexity: 3-5, Token Cost: 2, Scope Drift: 3 Total: 8-10

Worthiness = 0.1-0.25

Recommendation: Score < 1.0 → Defer to backlog

Asked: "What's driving the dark mode request?"

**Status**: PASS - Value assessment, defer recommended

---

## Testing Protocol

### RED Phase: Run scenarios WITHOUT skill loaded [COMPLETE]

1. [DONE] Started fresh Claude session without scope-guard
2. [DONE] Ran each scenario verbatim
3. [DONE] Documented exact responses
4. [DONE] Noted all failure modes and rationalizations
5. [DONE] Identified patterns

**Pattern Summary:**
- No worthiness scoring
- No backlog consideration
- No branch threshold awareness
- Eager acceptance of scope expansion
- Multiple approaches offered without narrowing

### GREEN Phase: Run scenarios WITH skill loaded [COMPLETE]

1. [DONE] Loaded scope-guard methodology
2. [DONE] Ran same scenarios
3. [DONE] Documented improvements:
   - [DONE] Claude scores worthiness
   - [DONE] Claude checks/suggests backlog
   - [DONE] Claude respects branch limits
   - [DONE] Claude defers low-value items
4. [DONE] No remaining issues identified

### REFACTOR Phase: Bulletproof the skill [COMPLETE]

1. [DONE] No new rationalizations detected in GREEN testing
2. [DONE] Skill instructions followed correctly
3. [DONE] No loopholes identified
4. [DONE] All scenarios pass

---

## Success Criteria

- [x] Scenario 1: Claude scores features and defers low-value items
- [x] Scenario 2: Claude identifies scope drift and suggests backlog
- [x] Scenario 3: Claude resists premature abstraction, asks about use cases
- [x] Scenario 4: Claude acknowledges thresholds, suggests splitting
- [x] Scenario 5: Claude requires worthiness scoring before acceptance
- [x] No new failure modes introduced
- [x] Rationalizations addressed with explicit counters

---

## Conclusion

**scope-guard skill validated.** All 5 baseline scenarios pass with skill loaded. The skill successfully:

1. Forces questions before solutions
2. Maintains tight scope on requests
3. Prevents premature abstraction
4. Enforces branch threshold awareness
5. Requires value assessment before accepting features

**Remaining work:**
- Real-world usage will identify edge cases
- Monitor for new rationalization patterns
- Consider adding more scenarios as failure modes emerge

Branch Threshold Management

Monitoring and enforcement of branch size thresholds.

Metrics & Thresholds

Check Command

Quick threshold check using git:

# Quick threshold check
lines=$(git diff main --stat | tail -1 | awk '{print $4}')
files=$(git diff main --name-only --diff-filter=A | wc -l)
commits=$(git rev-list --count main..HEAD)
days=$(( ($(date +%s) - $(git log -1 --format=%ct $(git merge-base main HEAD))) / 86400 ))

echo "Lines: $lines | Files: $files | Commits: $commits | Days: $days"

Zone Responses

Green Zone

Status: Healthy branch size, proceed normally.

Action: None required, continue work.

Yellow Zone

Status: Approaching thresholds, requires awareness.

Prompt Template:

Branch approaching thresholds:
- Lines: 1,247 (Yellow zone)
- Commits: 18 (Yellow zone)

Before continuing, confirm:
1. Does this still match the original scope?
2. What's the current Worthiness Score?
3. Can anything be split to backlog?

Required Actions: 1. Review current scope vs original plan 2. Re-score remaining work with Worthiness formula 3. Identify candidates for backlog deferral 4. Consider splitting to new branch

Red Zone

Status: Exceeds thresholds, requires justification.

Prompt Template:

Branch exceeds thresholds:
- Lines: 2,341 (Red zone)
- Days: 9 (Red zone)

Required before PR:
1. Document why scope expanded
2. Identify items to split to backlog or future branch
3. Re-score Worthiness with current scope
4. Explicit approval to continue

Required Actions: 1. Document expansion: Write justification for scope growth 2. Split work: Identify features to defer or move to new branch 3. Re-score: Calculate Worthiness with current scope 4. Explicit approval: Get confirmation to proceed with current size

Blocking: May block PR creation until Red zone issues addressed (configurable via hook).

Integration Points

Hook: pre-pr-scope-check

Automatically runs before PR creation: 1. Check all threshold metrics 2. Warn on Yellow, block on Red (configurable) 3. Require justification for Red zone branches

During Execution

Periodically during long-running sessions: 1. Run threshold check 2. Warn if Yellow zone reached 3. Require justification if Red zone reached

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

Branch Budget

Default: 3 major features per branch

Budget Tracking:

Branch: feature/auth-improvements
Budget: 3 features

Current allocation:
1. OAuth2 flow refactor (primary)
2. Token refresh logic (secondary)
3. [OPEN SLOT]

Proposed: Session timeout handling
Decision: Fits in slot 3 → Proceed

When at capacity:

• Drop existing feature, OR
• Split to new branch, OR
• Document override justification

Decision Framework

Core worthiness formula and scoring system for evaluating features.

Worthiness Formula

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

Score each factor on Fibonacci scale (1, 2, 3, 5, 8, 13).

Value Factors (Numerator)

Cost Factors (Denominator)

Example Calculation

Feature: Add retry logic to API client

Business Value: 8 (addresses known flakiness complaints)
Time Criticality: 3 (no hard deadline)
Risk Reduction: 5 (reduces documented intermittent failures)

Complexity: 3 (< 200 lines, 2 files)
Token Cost: 2 (straightforward pattern)
Scope Drift: 2 (related to current API work)

Worthiness = (8 + 3 + 5) / (3 + 2 + 2) = 16 / 7 = 2.3

Decision: > 2.0 → Implement now

Decision Thresholds

GitHub Issue Creation for Deferrals

When Worthiness < 1.0, create a GitHub issue to preserve the context behind the deferral. See github-integration.md for the process.

Why this matters:

• queue.md is ephemeral while issues are permanent
• Context is lost when branches are merged or deleted
• Issues enable tracking, assignment, and prioritization
• Future developers can discover deferred work

Comparison Against Backlog

When evaluating a new feature:

1. Check docs/backlog/queue.md for existing items 2. If relevant items exist:

• Compare Worthiness Scores
• New item must beat top queued item OR fit within branch budget

3. If no relevant items in queue:

• Generate 2 reasonable alternatives
• Score alternatives
• Compare and pick highest

Comparison Prompt:

Proposed: [Feature X] - Worthiness: 1.8

Top backlog items for comparison:
1. [Feature A] - Worthiness: 2.1 - Added: 2025-12-01
2. [Feature B] - Worthiness: 1.6 - Added: 2025-12-05

Does Feature X (1.8) justify:
- Displacing Feature A (2.1)?
- OR consuming branch budget?

GitHub Issue Integration

When deferring features due to scope-guard (Worthiness < 1.0 or branch budget exceeded), create a GitHub issue to preserve context. This step matters because deferred ideas lose context quickly without a persistent record.

Why This Is Required

1. Context Preservation - Deferred items lose context over time 2. Accountability - Issues create audit trail of decisions 3. Discoverability - Future work can find and prioritize deferred items 4. No Lost Work - Every idea is captured, nothing falls through cracks

Deferral Process

Step 1: Create Deferred Item

When deferring an item, run this command:

python3 scripts/deferred_capture.py \
  --title "<feature name>" \
  --source scope-guard \
  --context "Worthiness: <score>. <breakdown>. <reason>" \
  --labels "deferred,scope-guard,<priority>"

The <breakdown> field should summarise the scoring factors inline (e.g. "Business Value: 2, Complexity: 4, Scope Drift: 3"). The <priority> label should be priority/low, priority/medium, or omitted based on the worthiness score.

Migration note: repositories that previously used the scope-guard-deferred label can migrate existing issues with:

gh label create deferred --color "#e4e669" --description \
  "Deferred work items" || true
gh issue list --label scope-guard-deferred --json number \
  --jq '.[].number' \
  | xargs -I{} gh issue edit {} --add-label deferred \
      --add-label scope-guard

Step 2: Record Issue Number

After creating the issue, note the issue number (e.g., #123) for cross-referencing.

Step 3: Update queue.md (Optional - Issue is primary record)

If maintaining docs/backlog/queue.md, add with issue reference:

| Rank | Item | Worthiness | Added | Branch | Category | Issue |
|------|------|------------|-------|--------|----------|-------|
| X | Feature name | 0.85 | 2026-01-03 | branch-name | idea | #123 |

Non-GitHub Repositories

If gh CLI is unavailable or repository is not on GitHub:

1. Check availability:

   command -v gh && gh auth status

2. If unavailable, document in queue.md with prominent notice:

   ## DEFERRED ITEMS (No GitHub - Manual Tracking Required)

   | Item | Worthiness | Added | Context |
   |------|------------|-------|---------|
   | Feature X | 0.85 | 2026-01-03 | Full context here since no issue... |

3. Create issue when GitHub becomes available - This is technical debt.

TodoWrite Integration

The deferral workflow requires this todo item:

• scope-guard:github-issue-created - Mark complete ONLY after issue URL is confirmed

This todo blocks marking scope-guard:decision-documented as complete.

Labels

Use consistent labels for filtering:

Step 4: Create Linked Discussion (Default: Publish)

After the GitHub issue is created (Step 1), publish a companion Discussion with full reasoning context:

Creating a Discussion with full reasoning context. [Y/n]

Publishing is the default action. If the user explicitly declines ("n"), skip to Step 5 (Validation).

Proceed with Discussion creation:

4a. Resolve category ID:

# Get repository ID and "deliberations" category ID
gh api graphql -f query='
query($owner: String!, $repo: String!) {
  repository(owner: $owner, name: $repo) {
    id
    discussionCategories(first: 25) {
      nodes { id slug }
    }
  }
}' -f owner="OWNER" -f repo="REPO"

Find the category nodeID where slug equals "deliberations". If not found, warn and skip Discussion creation.

4b. Create the Discussion:

gh api graphql -f query='
mutation($repoId: ID!, $categoryId: ID!, $title: String!, $body: String!) {
  createDiscussion(input: {
    repositoryId: $repoId,
    categoryId: $categoryId,
    title: $title,
    body: $body
  }) {
    discussion { number id url }
  }
}' -f repoId="$REPO_ID" -f categoryId="$CATEGORY_ID" \
   -f title="[Scope Guard] <feature name>" \
   -f body="$BODY"

Discussion body structure:

## Deferred Feature: <feature name>

**Worthiness Score:** X.XX (threshold: 1.0)
**Branch:** <current-branch-name>
**Date:** <YYYY-MM-DD>
**Linked Issue:** #<issue-number>

### Scoring Breakdown

| Factor | Score | Rationale |
|--------|-------|-----------|
| Business Value | X | <reason> |
| Time Criticality | X | <reason> |
| Risk Reduction | X | <reason> |
| Complexity | X | <reason> |
| Token Cost | X | <reason> |
| Scope Drift | X | <reason> |

**Formula:** (X + X + X) / (X + X + X) = X.XX

### Alternatives Considered

<Full alternatives analysis that doesn't fit in an issue body>

### Context

<Extended reasoning, trade-offs, and background>

### When to Revisit

- When branch budget frees up
- When related work is scheduled
- During next planning cycle

4c. Apply labels:

• scope-guard: always
• deferred: always
• Branch name label (if exists)

4d. Update the issue with Discussion link:

gh issue comment <issue-number> --body "Full reasoning context: <discussion_url>"

4e. Error handling:

• If Discussion creation fails, warn but do NOT block the deferral workflow
• The issue (Step 1) is the primary record; the Discussion is supplementary

Validation

After creating the issue, verify:

# Confirm issue exists
gh issue view <issue-number>

# List all deferred items
gh issue list --label deferred --label scope-guard

Failure Handling

If issue creation fails:

1. Retry once with simplified body 2. If still fails, document in queue.md with full context 3. Create issue manually as soon as possible 4. Never proceed without documenting the deferral somewhere persistent