name: backlog description: Move an increment to backlog (planned but not ready to start) argument-hint: [increment-id] --reason="reason"

Backlog Increment Command

Usage: /sw:backlog <increment-id> --reason="<reason>"

Purpose

Move an increment to backlog when:

• Planned but not ready to start yet
• Low priority compared to other work
• Waiting for decisions or approvals before starting
• Multiple ideas you want to plan without violating WIP limits

Key Difference:

• Backlog = Never started, planned for future (does NOT count towards WIP)
• Paused = Started but blocked (does NOT count towards WIP)

Behavior

1. Validates increment exists and is "active"
2. Prompts for reason if not provided via --reason flag
3. Updates metadata.json:
   • status: "active" → "backlog"
   • backlogReason: User-provided reason
   • backlogAt: Current timestamp
4. Displays confirmation message
5. Suggests next actions (/sw:resume to start work)

Examples

Move to backlog with reason

/sw:backlog 0032 --reason="Low priority, focus on 0031 first"

✅ Increment 0032 moved to backlog
📝 Reason: Low priority, focus on 0031 first
🗂️  No longer counts toward WIP limits
💡 Start work with: /sw:resume 0032

Move to backlog without reason (prompts)

/sw:backlog 0032

❓ Why are you moving this to backlog?
   1. Low priority
   2. Waiting for decisions/approvals
   3. Multiple planned ideas
   4. Other (type reason)

> 1

✅ Increment 0032 moved to backlog
📝 Reason: Low priority
💡 Start work with: /sw:resume 0032

Edge Cases

Already in Backlog

/sw:backlog 0032 --reason="Different reason"

⚠️  Increment 0032 is already in backlog
   Previous reason: Low priority
   New reason: Different reason

Update reason? [Y/n]: y

✅ Reason updated
📝 New reason: Different reason

Cannot Backlog Completed

/sw:backlog 0005

❌ Cannot move increment 0005 to backlog
   Status: completed
   Completed increments cannot be moved to backlog

Cannot Backlog Paused

/sw:backlog 0008

❌ Cannot move increment 0008 to backlog
   Status: paused
   Paused work should be resumed or abandoned, not moved to backlog
   Resume it: /sw:resume 0008

Increment Not Found

/sw:backlog 9999

❌ Increment not found: 9999
💡 Check available increments: /sw:status

Implementation

This command uses the MetadataManager to update increment status:

import { MetadataManager, IncrementStatus } from '../src/core/increment/metadata-manager';

// Read current metadata
const metadata = MetadataManager.read(incrementId);

// Validate can move to backlog
if (metadata.status !== IncrementStatus.ACTIVE) {
  throw new Error(`Cannot move increment with status: ${metadata.status}`);
}

// Update status
MetadataManager.updateStatus(incrementId, IncrementStatus.BACKLOG, reason);

Status Flow

active ──backlog──> backlog
   │
   └──resume──> active

Related Commands

• /sw:resume <id> - Move from backlog to active (start work)
• /sw:pause <id> - Pause active work (different from backlog)
• /sw:status - Show all increment statuses including backlog
• /sw:abandon <id> - Abandon increment (permanent)

Best Practices

✅ Use backlog for planning - Plan multiple increments without violating WIP

✅ Prioritize backlog regularly - Review and reorder based on value

✅ Clear reasons - Helps with prioritization decisions

✅ Start when ready - Use /sw:resume to move from backlog to active

❌ Don't confuse with paused - Backlog = never started, Paused = started but blocked

❌ Don't let backlog grow unbounded - Review and abandon obsolete items

Backlog vs Paused

Warning: Large Backlog

If your backlog grows too large (10+ increments), /sw:status will warn:

/sw:status

🗂️  Backlog (12):
  📦 0032-feature-a [feature] - Low priority
  📦 0033-feature-b [feature] - Waiting for decisions
  📦 0034-feature-c [feature] - Multiple planned ideas
  ... (9 more)

⚠️  Large backlog! Consider:
   - Abandoning obsolete items
   - Consolidating similar features
   - Reviewing priorities

💡 Actions:
   /sw:resume <id>  # Start work on highest priority
   /sw:abandon <id> # Remove obsolete items

Command: /sw:backlog Plugin: specweave (core) Version: v0.19.0 Part of: Backlog Support Feature