specweave 0.6.8 → 0.7.0

package/plugins/specweave/commands/specweave-abandon.md

@@ -0,0 +1,314 @@
+---
+name: abandon
+description: Abandon an incomplete increment (requirements changed, obsolete)
+usage: /specweave:abandon <increment-id> --reason="<reason>"
+---
+
+# Abandon Increment Command
+
+**Usage**: `/specweave:abandon <increment-id> --reason="<reason>"`
+
+⚠️  **THIS ACTION MOVES THE INCREMENT TO `_abandoned/` 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. **Validates** increment exists and is NOT "completed"
+2. **Prompts** for reason if not provided
+3. **Confirmation prompt** ("This is permanent. Continue? [y/N]")
+4. **Updates** metadata.json:
+   - `status`: → "abandoned"
+   - `abandonedReason`: User-provided reason
+   - `abandonedAt`: Current timestamp
+5. **Moves folder**:
+   - From: `.specweave/increments/{id}/`
+   - To: `.specweave/increments/_abandoned/{id}/`
+6. **Displays** confirmation with preserved location
+
+---
+
+## Examples
+
+### Abandon with reason
+```bash
+/abandon 0008 --reason="Requirements changed - feature no longer needed"
+
+⚠️  This will move increment 0008 to _abandoned/
+   Reason: Requirements changed - feature no longer needed
+
+Continue? [y/N]: y
+
+✅ Increment 0008 abandoned
+📦 Moved to: .specweave/increments/_abandoned/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)
+```bash
+/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 _abandoned/
+   Reason: Requirements changed
+
+Continue? [y/N]: y
+
+✅ Increment 0009 abandoned
+📦 Moved to: .specweave/increments/_abandoned/0009-experiment/
+```
+
+---
+
+## Edge Cases
+
+### Cannot Abandon Completed
+```bash
+/abandon 0005
+
+❌ Cannot abandon increment 0005
+   Status: completed
+   Completed increments cannot be abandoned
+
+💡 Increments are done - no need to abandon
+```
+
+### Already Abandoned
+```bash
+/abandon 0008
+
+⚠️  Increment 0008 is already abandoned
+   Location: .specweave/increments/_abandoned/0008-old-feature/
+   Reason: Requirements changed
+
+No action needed.
+```
+
+### Increment Not Found
+```bash
+/abandon 9999
+
+❌ Increment not found: 9999
+💡 Check available increments: /status
+```
+
+### Cancel Abandonment
+```bash
+/abandon 0008 --reason="Not needed"
+
+⚠️  This will move increment 0008 to _abandoned/
+   Reason: Not needed
+
+Continue? [y/N]: n
+
+❌ Abandonment cancelled
+   Increment 0008 remains active
+```
+
+---
+
+## Implementation
+
+This command uses the MetadataManager and file system operations:
+
+```typescript
+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 _abandoned/ folder
+const fromPath = path.join('.specweave/increments', incrementId);
+const toPath = path.join('.specweave/increments/_abandoned', 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)
+```
+
+---
+
+## _abandoned/ Folder Structure
+
+```
+.specweave/increments/
+├── 0001-core-framework/          # Active/completed
+├── 0002-core-enhancements/       # Active/completed
+├── 0003-model-selection/         # Active/completed
+├── _abandoned/                    # Abandoned increments
+│   ├── 0008-old-approach/        # Abandoned
+│   │   ├── spec.md
+│   │   ├── plan.md
+│   │   ├── tasks.md
+│   │   └── metadata.json (status: abandoned)
+│   ├── 0009-failed-experiment/
+│   └── 0010-superseded-feature/
+└── _backlog/                      # Future work
+```
+
+---
+
+## Un-Abandoning (Manual Process)
+
+To un-abandon an increment:
+
+```bash
+# 1. Move back to increments/
+mv .specweave/increments/_abandoned/0008-feature \
+   .specweave/increments/0008-feature
+
+# 2. Resume via command
+/resume 0008
+
+✅ Increment 0008 resumed
+⚠️  Note: Was abandoned 10 days ago
+   Reason: Requirements changed
+💡 Review spec.md to ensure still relevant
+```
+
+---
+
+## Related Commands
+
+- `/pause <id>` - Pause increment (temporary, can resume)
+- `/resume <id>` - Resume paused or abandoned increment
+- `/status` - Show all increments (including abandoned count)
+- `/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:
+
+```bash
+# Create experiment
+/specweave:inc "Try GraphQL" --type=experiment
+
+# ... 15 days pass with no activity ...
+
+# Automatic abandonment
+/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 /do or manual touch
+```
+
+---
+
+## Statistics
+
+View abandonment statistics:
+
+```bash
+/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 `_abandoned/` folder for insights
+
+---
+
+**Command**: `/specweave:abandon` (or `/abandon`)
+**Plugin**: specweave (core)
+**Version**: v0.7.0+
+**Part of**: Increment 0007 - Smart Status Management