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) auto-abandon after 14 days of inactivity:

# Create experiment
/sw:inc "Try GraphQL" --type=experiment

# ... 15 days pass with no activity ...

# Automatic abandonment
/sw:status

📊 Auto-Abandoned (1):
  🧪 0010-graphql-experiment [experiment]
     Abandoned: automatically (14+ days inactive)
     Created: 15 days ago
     Last activity: 15 days ago

💡 Experiments auto-abandon after 14 days of inactivity
   To prevent: Update lastActivity via /sw:do or manual touch

---

Statistics

View abandonment statistics:

/sw:status

✅ Completed (4):
  0001-core-framework
  0002-core-enhancements
  0003-model-selection
  0004-plugin-architecture

❌ Abandoned (3):
  0008-old-approach (Requirements changed)
  0009-failed-experiment (Experiment failed)
  0010-superseded (Replaced by 0011)

📊 Summary:
  - Success rate: 57% (4/7 completed)
  - Abandonment rate: 43% (3/7 abandoned)
  - Common reasons: Requirements changed (2), Experiment failed (1)

---

Abandoned Increments as Learning

Abandoned work is valuable!

• Retrospectives: What went wrong? Why did requirements change?
• Patterns: Are we over-committing? Under-planning?
• Learnings: Failed experiments teach us what NOT to do
• Reference: Abandoned specs can inform future work

💡 Periodically review

_archive/

folder for insights

---

Command:

/sw:abandon

Plugin: specweave (core) Version: v0.7.0 Part of: Increment 0007 - Smart Status Management