majiayu000 Restore Increment from Archive
Restore an archived increment back to the main increments folder. Useful when you need to reference, update, or continue work on an old increment.
Usage
# Restore specific increment
/sw:restore 0031
# Restore multiple increments
/sw:restore 0001 0002 0003
# List archived increments
/sw:restore --list
Arguments
<increment-ids>: Increment IDs to restore (e.g., "1", "0001", "0031")--list: List all archived increments without restoring
Examples
Example 1: Restore Specific Increment
/sw:restore 0031
Output:
📦 Restoring increment from archive...
Increment: 0031-external-tool-status-sync
Source: .specweave/increments/_archive/0031-external-tool-status-sync/
Target: .specweave/increments/0031-external-tool-status-sync/
Checking target location...
✓ Target location is empty
✅ Restored: 0031-external-tool-status-sync
Location: .specweave/increments/0031-external-tool-status-sync/
📊 Archive Statistics:
Active: 33 increments (+ 1 restored)
Archived: 30 increments (- 1)
Next: /sw:do 0031 (to continue work)
Example 2: List Archived Increments
/sw:restore --list
Output:
📦 Archived Increments:
.specweave/increments/_archive/
├── 0001-core-framework (152 days old)
├── 0002-plugin-system (148 days old)
├── 0003-auth-service (145 days old)
├── 0004-payment-integration (142 days old)
├── 0005-api-gateway (140 days old)
...
├── 0030-jira-integration (35 days old)
└── 0031-external-tool-status-sync (12 days old)
Total: 31 archived increments
To restore: /sw:restore <increment-id>
Example 3: Restore Multiple Increments
/sw:restore 0030 0031
Output:
📦 Restoring increments from archive...
Restoring 0030-jira-integration...
✅ Restored
Restoring 0031-external-tool-status-sync...
✅ Restored
✅ Restored: 2 increments
📊 Archive Statistics:
Active: 34 increments (+ 2 restored)
Archived: 29 increments (- 2)
Error Handling
Increment Not Found in Archive
❌ Error: Increment 0031 not found in archive
Archive location: .specweave/increments/_archive/
Available archived increments:
• 0001-core-framework
• 0002-plugin-system
• 0003-auth-service
...
Use: /sw:restore --list to see all
Target Location Already Exists
❌ Error: Cannot restore 0031 - already exists in active folder
Conflict:
Archive: .specweave/increments/_archive/0031-external-tool-status-sync/
Active: .specweave/increments/0031-external-tool-status-sync/
Options:
1. Delete active version first (if it's a duplicate)
2. Resolve duplicates: /sw:fix-duplicates
3. Archive active version: /sw:archive 0031
4. Rename one version manually
Recommended: /sw:fix-duplicates (auto-resolves conflicts)
Permission Errors
❌ Error: Permission denied
Could not move:
From: .specweave/increments/_archive/0031-external-tool-status-sync/
To: .specweave/increments/0031-external-tool-status-sync/
Check:
• File permissions
• Disk space
• Files not open in another program
Safety Checks
Before restoring, the system checks:
- ✅ Increment exists in archive: Source folder exists
- ✅ Target location empty: No conflict in main folder
- ✅ Valid increment structure: Has required files (metadata.json)
- ✅ Disk space available: Enough space for restored files
Related Commands
/sw:archive <increment-id>- Archive completed increments/sw:status- View archive statistics/sw:fix-duplicates- Auto-resolve duplicate increments/sw:do <increment-id>- Resume work on restored increment
Implementation
import { Task } from '@claude/types';
const task = new Task('restore-increment', 'Restore increment from archive');
task.run(async () => {
const { IncrementArchiver } = await import('../../../dist/src/core/increment/increment-archiver.js');
const archiver = new IncrementArchiver(process.cwd());
// Parse arguments
const args = process.argv.slice(2);
// List mode
if (args.includes('--list')) {
const archived = await archiver.listArchived();
console.log('\n📦 Archived Increments:\n');
if (archived.length === 0) {
console.log('No archived increments found.');
return;
}
console.log('.specweave/increments/_archive/');
archived.forEach(inc => {
console.log(`├── ${inc}`);
});
console.log(`\nTotal: ${archived.length} archived increments`);
console.log('\nTo restore: /sw:restore <increment-id>');
return;
}
// Restore mode
const incrementIds = args.filter(arg => !arg.startsWith('--'));
if (incrementIds.length === 0) {
console.error('❌ Error: No increment IDs provided');
console.log('\nUsage:');
console.log(' /sw:restore <increment-id>');
console.log(' /sw:restore --list');
return;
}
// Restore each increment
let restored = 0;
let errors = 0;
for (const id of incrementIds) {
try {
// Normalize ID to 4-digit format
const normalizedId = id.padStart(4, '0');
// Find archived increment
const archived = await archiver.listArchived();
const match = archived.find(inc => inc.startsWith(normalizedId));
if (!match) {
console.error(`❌ Increment ${normalizedId} not found in archive`);
errors++;
continue;
}
// Restore increment
await archiver.restore(match);
console.log(`✅ Restored: ${match}`);
restored++;
} catch (error) {
console.error(`❌ Failed to restore ${id}: ${error.message}`);
errors++;
}
}
// Show statistics
if (restored > 0 || errors > 0) {
console.log('\n📊 Restore Summary:');
if (restored > 0) {
console.log(` ✅ Restored: ${restored} increment${restored > 1 ? 's' : ''}`);
}
if (errors > 0) {
console.log(` ❌ Errors: ${errors} increment${errors > 1 ? 's' : ''}`);
}
// Show updated stats
const stats = await archiver.getStats();
console.log('\n📊 Archive Statistics:');
console.log(` Active: ${stats.active} increments`);
console.log(` Archived: ${stats.archived} increments`);
}
});
export default task;
Important Notes
Archive is Not Deletion
Archives are preserved history, not deleted work. You can restore anytime:
- ✅ Full increment structure preserved
- ✅ All files, reports, and metadata intact
- ✅ Git history preserved (if committed)
- ✅ External tool links preserved in metadata
When to Restore
Common scenarios for restoring from archive:
- 🔍 Reference old implementation - Check how something was done
- 🔄 Resume abandoned work - Pick up where you left off
- 🐛 Bug investigation - Review completed increment for context
- 📝 Documentation - Update reports or completion summaries
- 🔗 External sync recovery - Re-sync to GitHub/JIRA if needed
After Restoring
Once restored, the increment is back in the active folder:
- ✅ Shows up in
/sw:status - ✅ Can be resumed with
/sw:do - ✅ Can be re-archived with
/sw:archive - ✅ Included in increment counts and WIP limits
Best Practice: Keep archives clean by only restoring when needed, then re-archiving when done.
Recommended Workflow:
# 1. List archived increments
/sw:restore --list
# 2. Restore specific increment
/sw:restore 0031
# 3. Review or update the increment
cat .specweave/increments/0031-external-tool-status-sync/spec.md
# 4. Re-archive when done
/sw:archive 0031