/abandon

description: Abandon an incomplete increment (requirements changed, obsolete)
argument-hint: [increment-id] --reason="reason"
disable-model-invocation: true

Abandon Increment Command

**Usage**: `sw:abandon <increment-id> --reason="<reason>"`

⚠️ **THIS ACTION MOVES THE INCREMENT TO `_archive/` FOLDER**

---

Purpose

Abandon an increment when:

• **Requirements changed** (feature no longer needed)
• **Approach wrong** (discovered better solution)
• **Superseded** (replaced by different increment)
• **Experiment failed** (spike didn't pan out)

---

Behavior

1. **Normalize increment ID**:

• If ID contains dash (e.g., "0153-feature-name"), extract numeric portion before first dash → "0153"
• Convert to 4-digit format (e.g., "1" → "0001", "153" → "0153")
• Both formats work: `sw:abandon 0153` or `sw:abandon 0153-feature-name`

2. **Validates** increment exists and is NOT "completed" 3. **Prompts** for reason if not provided 4. **Confirmation prompt** ("This is permanent. Continue? [y/N]") 5. **Updates** metadata.json:

• `status`: → "abandoned"
• `abandonedReason`: User-provided reason
• `abandonedAt`: Current timestamp

6. **Moves folder**:

• From: `.specweave/increments/{id}/`
• To: `.specweave/increments/_archive/{id}/`

7. **Displays** confirmation with preserved location

---

Examples

Abandon with reason

sw:abandon 0008 --reason="Requirements changed - feature no longer needed"

⚠️  This will move increment 0008 to _archive/
   Reason: Requirements changed - feature no longer needed

Continue? [y/N]: y

✅ Increment 0008 abandoned
📦 Moved to: .specweave/increments/_archive/0008-old-feature/
📝 Reason: Requirements changed - feature no longer needed
💾 All work preserved for reference

💡 To un-abandon: Manually move back to increments/ folder

Abandon without reason (prompts)

sw:abandon 0009

❓ Why are you abandoning this increment?
   1. Requirements changed
   2. Approach was wrong
   3. Superseded by different work
   4. Experiment failed
   5. Other (type reason)

> 1

⚠️  This will move increment 0009 to _archive/
   Reason: Requirements changed

Continue? [y/N]: y

✅ Increment 0009 abandoned
📦 Moved to: .specweave/increments/_archive/0009-experiment/

---

Edge Cases

Cannot Abandon Completed

sw:abandon 0005

❌ Cannot abandon increment 0005
   Status: completed
   Completed increments cannot be abandoned

💡 Increments are done - no need to abandon

Already Abandoned

sw:abandon 0008

⚠️  Increment 0008 is already abandoned
   Location: .specweave/increments/_abandoned/0008-old-feature/
   Reason: Requirements changed

No action needed.

Increment Not Found

sw:abandon 9999

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

Cancel Abandonment

sw:abandon 0008 --reason="Not needed"

⚠️  This will move increment 0008 to _archive/
   Reason: Not needed

Continue? [y/N]: n

❌ Abandonment cancelled
   Increment 0008 remains active

---

Implementation

This command uses the MetadataManager and file system operations:

import { MetadataManager, IncrementStatus } from '../src/core/increment/metadata-manager';
import * as fs from 'fs-extra';
import * as path from 'path';

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

// Validate can abandon
if (metadata.status === IncrementStatus.COMPLETED) {
  throw new Error('Cannot abandon completed increment');
}

// Confirmation prompt
const confirmed = await prompt('Continue? [y/N]');
if (!confirmed) {
  console.log('Abandonment cancelled');
  return;
}

// Update metadata
MetadataManager.updateStatus(incrementId, IncrementStatus.ABANDONED, reason);

// Move to _archive/ folder
const fromPath = path.join('.specweave/increments', incrementId);
const toPath = path.join('.specweave/increments/_archive', incrementId);
fs.moveSync(fromPath, toPath);

console.log(`✅ Moved to: ${toPath}`);

---

Status Flow

active ──abandon──> abandoned
   │
paused ──abandon──> abandoned
   │
abandoned (already abandoned - no-op)

completed (CANNOT abandon)

---

_archive/ Folder Structure

.specweave/increments/
├── 0023-release-management/      # Active
├── 0024-bidirectional-spec/      # Active
├── 0025-per-project-config/      # Active
├── _archive/                      # All archived/abandoned/old increments
│   ├── 0001-core-framework/       # Completed (archived)
│   ├── 0002-core-enhancements/    # Completed (archived)
│   ├── 0008-old-approach/         # Abandoned
│   │   ├── spec.md
│   │   ├── plan.md
│   │   ├── tasks.md
│   │   └── metadata.json (status: abandoned)
│   ├── 0009-failed-experiment/    # Abandoned
│   └── 0029-cicd-auto-fix/        # Abandoned
└── _backlog/                       # Future work

---

Un-Abandoning (Manual Process)

To un-abandon an increment:

# 1. Move back to increments/
mv .specweave/increments/_archive/0008-feature \
   .specweave/increments/0008-feature

# 2. Resume via command
sw:resume 0008

✅ Increment 0008 resumed
⚠️  Note: Was abandoned 10 days ago
   Reason: Requirements changed
💡 Review spec.md to ensure still relevant

---

Related Commands

• `sw:pause <id>` - Pause increment (temporary, can resume)
• `sw:resume <id>` - Resume paused or abandoned increment
• `sw:status` - Show all increments (including abandoned count)
• `sw:status --abandoned` - Show only abandoned increments

---

Best Practices

✅ **Always provide clear reason** - Future you will thank you

✅ **Document learnings** - Add retrospective notes to spec.md before abandoning

✅ **Extract reusable parts** - Move to _backlog/ if salvageable

✅ **Communicate** - Let team know if collaborative

❌ **Don't abandon as procrastination** - Pause if temporarily blocked

❌ **Don't delete** - Abandon moves to _abandoned/, preserves history

---

Auto-Abandonment (Experiments)

Experiments (--type=experiment)