| name | sdd-modify |
| description | Apply spec modifications systematically. Use to apply review feedback, bulk modifications, or interactive spec updates with safety checks, validation, and rollback support. |
Spec-Driven Development: Modify Skill
When to Use This Skill
Use Skill(sdd-toolkit:sdd-modify) to:
- Apply review feedback systematically - Parse and apply modifications from sdd-fidelity-review or sdd-plan-review outputs
- Execute bulk modifications - Apply multiple spec changes from JSON files with validation
- Interactive spec updates - Guided workflow for making structural changes to specifications
- Parse review reports - Convert review feedback to structured modification format
- Preview modifications - See what would change before applying (dry-run mode)
Do NOT use for:
- Simple task status updates (use
sdd-updateinstead) - Creating new specifications (use
sdd-planinstead) - Validation only (use
sdd-validateinstead) - Finding next task to work on (use
sdd-nextinstead)
Core Philosophy
Systematic Modification: Spec modifications should be systematic, validated, and safe. This skill provides a guided workflow with previews, user approval, automatic backups, validation, and rollback support to ensure spec integrity.
Feedback Loop Completion: This skill closes the loop: Review → Parse → Modify → Validate → Re-review. It enables systematic application of review feedback without manual error-prone editing.
Skill Family
This skill is part of the Spec-Driven Development workflow:
- sdd-plan - Creates specifications
- sdd-fidelity-review - Reviews implementation against spec
- sdd-plan-review - Multi-model spec review before implementation
- sdd-modify (this skill) - Applies modifications systematically
- sdd-validate - Validates spec structure
- sdd-update - Tracks task progress and metadata
Relationship to sdd-update
When to use sdd-modify vs sdd-update:
| Operation | Use sdd-modify | Use sdd-update |
|---|---|---|
| Change task status (in_progress, blocked) | ❌ No | ✅ Yes |
| Mark task completed | ❌ No | ✅ Yes |
| Add journal entries | ❌ No | ✅ Yes |
| Update task descriptions | ✅ Yes | ❌ No |
| Add/remove tasks | ✅ Yes | ❌ No |
| Add verification steps | ✅ Yes | ❌ No |
| Apply review feedback | ✅ Yes | ❌ No |
| Bulk structural changes | ✅ Yes | ❌ No |
| Move spec between folders | ❌ No | ✅ Yes |
| Update spec metadata | ✅ Yes (structural) | ✅ Yes (progress) |
Summary:
- sdd-update = Task progress, status, journaling (lightweight metadata updates)
- sdd-modify = Structural changes, bulk modifications, review feedback (heavyweight spec restructuring)
Reading Specifications (CRITICAL)
When working with spec files, ALWAYS use sdd CLI commands:
- ✅ ALWAYS use
sddcommands to read/query spec files - ❌ NEVER use
Read()tool on .json spec files - bypasses hooks and wastes context tokens - ❌ NEVER use Bash commands to read spec files (e.g.,
cat,head,tail,grep,jq) - The
sddCLI provides efficient, structured access with proper parsing and validation - Spec files can be 50KB+ and reading them directly wastes valuable context window space
Command Execution Best Practices (CRITICAL)
CRITICAL: Run sdd commands individually, never in loops or chains
DO: Individual Command Execution
Run each sdd command as a separate Bash tool call:
# Parse review report
sdd parse-review my-spec-001 --review reports/review.md --output suggestions.json
# Preview modifications
sdd apply-modifications my-spec-001 --from suggestions.json --dry-run
# Apply modifications
sdd apply-modifications my-spec-001 --from suggestions.json
DON'T: Loops, Chains, or Compound Commands
Never use bash loops:
# ❌ WRONG - Do not use loops
for spec in specs/*.json; do
sdd apply-modifications $(basename $spec .json) --from mods.json
done
Never chain commands:
# ❌ WRONG - Do not chain commands
sdd parse-review my-spec-001 --review review.md && sdd apply-modifications my-spec-001 --from suggestions.json
Never use compound commands:
# ❌ WRONG - Do not combine with other commands
echo "Parsing review..." && sdd parse-review my-spec-001 --review review.md
Never use semicolons:
# ❌ WRONG - Do not use semicolons
sdd parse-review spec-1 --review r1.md; sdd parse-review spec-2 --review r2.md
Why Individual Execution Matters
- Transaction Safety - Each modification operation is a transaction with automatic rollback
- Error Handling - Easier to identify which operation failed
- Rollback Boundaries - Clear transaction boundaries prevent partial modifications
- Permission Clarity - User can approve/deny each operation separately
- Progress Visibility - User sees each step complete
- Debugging - Easier to trace issues to specific operations
- Idempotency - Safe to retry individual failed operations
Correct Pattern: Sequential Individual Calls
For multiple specs:
# ✅ CORRECT - Individual calls
sdd apply-modifications spec-1 --from mods.json
# Wait for completion, check result
sdd apply-modifications spec-2 --from mods.json
# Wait for completion, check result
sdd apply-modifications spec-3 --from mods.json
# Wait for completion, check result
For workflow steps:
# ✅ CORRECT - Sequential individual operations
sdd parse-review my-spec-001 --review reports/review.md --output suggestions.json
# Wait, parse results
sdd apply-modifications my-spec-001 --from suggestions.json --dry-run
# Wait, review preview
sdd apply-modifications my-spec-001 --from suggestions.json
# Wait, verify completion
Workflow 1: Apply Review Feedback
Complete workflow for applying feedback from sdd-fidelity-review or sdd-plan-review.
Step 1: Generate Review Report
First, run a review to identify issues:
# Run fidelity review
Skill(sdd-toolkit:sdd-fidelity-review) "Review implementation for spec my-spec-001"
# This generates: reports/my-spec-001-fidelity-review.md
Step 2: Parse Review Report
Convert review feedback to structured modifications:
sdd parse-review my-spec-001 --review reports/my-spec-001-fidelity-review.md --output suggestions.json
Output:
✓ Parsed 5 modifications from review report
✓ Saved to suggestions.json
Modifications by type:
- update_task: 3
- add_verification: 2
Confidence scores:
- High confidence: 4 modifications
- Medium confidence: 1 modification
- Low confidence: 0 modifications
Step 3: Preview Modifications
See what would change before applying:
sdd apply-modifications my-spec-001 --from suggestions.json --dry-run
Output:
📋 Modification Preview (Dry-Run)
Tasks to Update:
task-2-1: "Implement auth"
→ "Implement OAuth 2.0 authentication with PKCE flow"
task-2-2: "Add login endpoint"
→ "Add /auth/login endpoint with rate limiting"
task-3-1: "Write tests"
→ "Write comprehensive tests covering edge cases and error handling"
Verification Steps to Add:
task-2-1 verify-2-1-3: "Verify token expiration handling"
task-2-2 verify-2-2-4: "Verify rate limiting with concurrent requests"
Impact Summary:
- 3 tasks will be updated
- 2 verification steps will be added
- 2 phases affected
- 0 tasks will be added
- 0 tasks will be removed
No validation errors predicted.
Step 4: Apply Modifications
Apply the changes with automatic backup and validation:
sdd apply-modifications my-spec-001 --from suggestions.json
Output:
✓ Backup created: specs/.backups/my-spec-001-20251106-143022.json
✓ Applied 5 modifications
✓ Validation passed
✓ Spec updated successfully
Changes:
- Updated 3 task descriptions
- Added 2 verification steps
Next steps:
- Review updated spec: sdd context show my-spec-001
- Continue implementation with updated guidance
- Run fidelity review again to confirm issues resolved
Step 5: Verify Results
Optionally, run fidelity review again to confirm issues are resolved:
Skill(sdd-toolkit:sdd-fidelity-review) "Re-review spec my-spec-001 after modifications"
Workflow 2: Bulk Modifications from JSON
Apply pre-defined modifications from a JSON file.
Step 1: Create Modification File
Create a JSON file with desired modifications:
{
"modifications": [
{
"operation": "update_task",
"task_id": "task-2-1",
"field": "description",
"value": "Implement OAuth 2.0 authentication with PKCE flow and refresh tokens"
},
{
"operation": "add_verification",
"task_id": "task-2-1",
"verify_id": "verify-2-1-4",
"description": "Verify refresh token rotation works correctly",
"command": "pytest tests/test_auth.py::test_refresh_token_rotation -v"
},
{
"operation": "update_task",
"task_id": "task-2-2",
"field": "task_category",
"value": "implementation"
}
]
}
Save as: my-modifications.json
Step 2: Validate Modification Structure
Check that the modification file is valid:
sdd validate-modifications my-modifications.json
Output:
✓ Modification file is valid
✓ All task references exist in spec
✓ All required fields present
✓ No schema violations
Ready to apply 3 modifications.
Step 3: Preview Impact
Run dry-run to see what would change:
sdd apply-modifications my-spec-001 --from my-modifications.json --dry-run
Step 4: Apply with Validation
Apply the modifications:
sdd apply-modifications my-spec-001 --from my-modifications.json
Output shows:
- Backup location
- Number of modifications applied
- Validation results
- Changes summary
Workflow 3: Interactive Guided Modification
Use the skill for step-by-step guided modifications (NOT YET IMPLEMENTED - FUTURE ENHANCEMENT).
Skill(sdd-toolkit:sdd-modify) "Guide me through updating spec my-spec-001"
Future workflow:
- Skill asks what type of modification you want to make
- Provides options: Update task, Add task, Add verification, etc.
- Prompts for required information
- Shows preview of change
- Asks for confirmation
- Applies modification
- Validates result
- Offers to make more changes or finish
Current Status: Interactive mode is planned for Phase 2. For now, use Workflows 1 or 2.
CLI Commands Reference
Parse Review Report
Convert review feedback to structured modification JSON:
sdd parse-review <spec-id> --review <review-report.md> --output <suggestions.json>
Options:
--review- Path to review report (markdown from sdd-fidelity-review or sdd-plan-review)--output- Where to save parsed modifications JSON (optional, defaults to{spec-id}-suggestions.json)
Example:
sdd parse-review my-spec-001 \
--review reports/my-spec-001-review.md \
--output suggestions.json
Apply Modifications
Apply modifications to a spec with validation and backup:
sdd apply-modifications <spec-id> --from <modifications.json> [--dry-run] [--no-validate]
Options:
--from- Path to modifications JSON file (required)--dry-run- Preview changes without applying (optional)--no-validate- Skip validation after applying (NOT RECOMMENDED)
Examples:
# Preview modifications
sdd apply-modifications my-spec-001 --from suggestions.json --dry-run
# Apply modifications with validation
sdd apply-modifications my-spec-001 --from suggestions.json
# Apply without validation (dangerous, not recommended)
sdd apply-modifications my-spec-001 --from suggestions.json --no-validate
Validate Modifications
Check modification file structure before applying:
sdd validate-modifications <modifications.json>
Example:
sdd validate-modifications suggestions.json
Modification JSON Schema
Modification files use this structure:
{
"modifications": [
{
"operation": "update_task",
"task_id": "task-2-1",
"field": "description",
"value": "New task description"
},
{
"operation": "add_verification",
"task_id": "task-2-1",
"verify_id": "verify-2-1-4",
"description": "Verification description",
"command": "optional command to run"
},
{
"operation": "update_metadata",
"task_id": "task-2-1",
"field": "actual_hours",
"value": 4.5
}
]
}
Supported Operations
1. update_task - Modify existing task fields
{
"operation": "update_task",
"task_id": "task-2-1",
"field": "description",
"value": "Updated description"
}
Updatable fields:
description- Task descriptiontask_category- Task category (implementation, test, documentation, etc.)skill- Skill to use for this taskcommand- Command to run for this taskfile_path- Related file pathstatus_note- Note about current status
2. add_verification - Add verification step to task
{
"operation": "add_verification",
"task_id": "task-2-1",
"verify_id": "verify-2-1-4",
"description": "Verify X works correctly",
"command": "pytest tests/test_x.py -v"
}
Required fields:
task_id- Parent taskverify_id- Unique verification ID (must follow pattern verify-X-Y-Z)description- What to verifycommand- Optional command to run
3. update_metadata - Update task metadata
{
"operation": "update_metadata",
"task_id": "task-2-1",
"field": "actual_hours",
"value": 4.5
}
Updatable metadata:
actual_hours- Actual time spentestimated_hours- Estimated timepriority- Task prioritycomplexity- Task complexity
4. add_task - Add new task to phase (FUTURE)
{
"operation": "add_task",
"phase_id": "phase-2",
"task_id": "task-2-5",
"description": "New task description",
"task_category": "implementation"
}
5. remove_task - Remove task from spec (FUTURE)
{
"operation": "remove_task",
"task_id": "task-2-5",
"reason": "No longer needed after refactoring"
}
6. reorder_tasks - Change task order within phase (FUTURE)
{
"operation": "reorder_tasks",
"phase_id": "phase-2",
"new_order": ["task-2-2", "task-2-1", "task-2-3"]
}
Safety Features
1. Automatic Backup
Every apply operation creates a backup before making changes:
specs/.backups/my-spec-001-20251106-143022.json
Backups include:
- Full spec content at time of modification
- Timestamp in filename
- Preserved indefinitely (manual cleanup required)
Restoring from backup:
cp specs/.backups/my-spec-001-20251106-143022.json specs/active/my-spec-001.json
2. Transaction Rollback
If validation fails after applying modifications:
- All changes are automatically rolled back
- Spec restored to pre-modification state
- Backup preserved for manual inspection
- Clear error message indicates rollback occurred
Example rollback scenario:
✗ Validation failed after applying modifications
✓ Rolled back all changes
✓ Spec restored to original state
✓ Backup preserved: specs/.backups/my-spec-001-20251106-143022.json
Validation errors:
- Task task-2-3 missing required field: description
- Invalid phase_id reference in task task-3-1
Suggestions:
- Review modification file for invalid task references
- Ensure all required fields are included
- Run sdd-validate on modification file before applying
3. Validation After Apply
After every modification (unless --no-validate used):
- Full spec validation runs
- Checks schema compliance
- Validates references (phase_id, task_id, etc.)
- Ensures required fields present
- Reports any issues found
If validation passes:
- Changes committed
- Success message shown
- Ready to continue
If validation fails:
- Automatic rollback triggered
- Error messages explain what's wrong
- Suggestions for fixing provided
4. Idempotency
Modifications are designed to be idempotent:
- Applying same modification twice is safe
- Second application results in "no changes" not error
- Safe to retry failed operations
Example:
# First application
sdd apply-modifications my-spec-001 --from mods.json
# Output: ✓ Applied 5 modifications
# Second application (same file)
sdd apply-modifications my-spec-001 --from mods.json
# Output: ✓ No changes needed (all modifications already applied)
5. Preview Before Apply
Always preview with --dry-run before applying significant changes:
# Preview first
sdd apply-modifications my-spec-001 --from mods.json --dry-run
# Review output, then apply if looks correct
sdd apply-modifications my-spec-001 --from mods.json
Integration with Review Skills
sdd-fidelity-review Integration
Complete closed-loop workflow:
# 1. Run fidelity review
Skill(sdd-toolkit:sdd-fidelity-review) "Review spec my-spec-001"
# → Generates: reports/my-spec-001-fidelity-review.md
# 2. Parse review to extract fixes
sdd parse-review my-spec-001 --review reports/my-spec-001-fidelity-review.md
# 3. Preview modifications
sdd apply-modifications my-spec-001 --from my-spec-001-suggestions.json --dry-run
# 4. Apply modifications
sdd apply-modifications my-spec-001 --from my-spec-001-suggestions.json
# 5. Re-review to confirm fixes
Skill(sdd-toolkit:sdd-fidelity-review) "Re-review spec my-spec-001"
# → Should show issues resolved
sdd-plan-review Integration
Apply consensus recommendations:
# 1. Run multi-model plan review
Skill(sdd-toolkit:sdd-plan-review) "Review spec my-spec-001"
# → Generates consensus recommendations
# 2. Extract high-confidence recommendations
# (Manual step or automated filter for consensus items)
# 3. Apply consensus improvements
sdd apply-modifications my-spec-001 --from consensus-improvements.json
Error Handling
Common Error Scenarios
1. Spec Not Found
✗ Error: Spec 'my-spec-001' not found
Searched locations:
- specs/active/my-spec-001.json
- specs/pending/my-spec-001.json
- specs/completed/my-spec-001.json
Suggestions:
- Verify spec ID is correct
- Check that spec exists in specs/ folder
- Use full path if spec is in non-standard location
2. Invalid Modification File
✗ Error: Modification file invalid
Validation errors:
- Line 5: Missing required field 'operation'
- Line 12: Invalid task_id format 'task2' (expected 'task-2-X')
- Line 18: Unknown operation 'delete_task' (supported: update_task, add_verification, update_metadata)
Suggestions:
- Review modification schema documentation
- Use sdd parse-review to generate valid modification files
- Validate modification file structure before applying
3. Task Reference Error
✗ Error: Task not found in spec
Cannot modify task-5-3: Task does not exist in spec my-spec-001
Available tasks in spec:
- task-1-1 through task-1-3 (Phase 1)
- task-2-1 through task-2-4 (Phase 2)
- task-3-1 through task-3-2 (Phase 3)
Suggestions:
- Verify task_id exists in spec
- Use sdd context show my-spec-001 to see all task IDs
- Check for typos in task_id
4. Validation Failure After Apply
✗ Error: Validation failed after applying modifications
✓ All changes rolled back
✓ Spec restored to original state
Validation errors:
- Task task-2-3: Missing required field 'description'
- Task task-3-1: Invalid phase_id reference 'phase-5' (phase doesn't exist)
Modifications attempted: 5
Backup location: specs/.backups/my-spec-001-20251106-143022.json
Suggestions:
- Review modification file for completeness
- Ensure all required fields included in update operations
- Verify phase references are correct
- Fix issues and retry
Rollback Communication
When rollback occurs:
- Clear indication - "All changes rolled back"
- Reason explained - Shows validation errors that triggered rollback
- Backup location - Shows where backup is preserved
- Actionable suggestions - Tells you how to fix the issue
Best Practices
1. Always Preview First
Run --dry-run before applying significant changes:
# Preview
sdd apply-modifications my-spec-001 --from mods.json --dry-run
# Review output carefully
# Apply if preview looks correct
sdd apply-modifications my-spec-001 --from mods.json
2. Start with Small Batches
When making many changes:
- Apply in small batches (5-10 modifications at a time)
- Validate after each batch
- Easier to identify and fix issues
# Split modifications into batches
sdd apply-modifications my-spec-001 --from batch1.json
sdd apply-modifications my-spec-001 --from batch2.json
sdd apply-modifications my-spec-001 --from batch3.json
3. Preserve Backups
Keep backups until changes are verified:
- Don't delete backups immediately
- Wait until implementation complete
- Use for comparison or rollback if needed
# Compare current spec to backup
diff specs/active/my-spec-001.json specs/.backups/my-spec-001-20251106-143022.json
4. Validate Modification Files
Before applying, validate the modification file structure:
# Validate first
sdd validate-modifications my-modifications.json
# Then apply
sdd apply-modifications my-spec-001 --from my-modifications.json
5. Document Major Changes
After significant modifications, add journal entry via sdd-update:
sdd add-journal my-spec-001 \
--title "Spec Updated from Fidelity Review" \
--content "Applied 5 modifications based on fidelity review feedback. Updated task descriptions for clarity and added verification steps." \
--entry-type note
6. Use Parse-Review for Review Feedback
Don't manually create modification files from review reports:
- Use
sdd parse-reviewto automatically extract modifications - Reduces errors
- Faster
- More reliable
# ✓ Good
sdd parse-review my-spec-001 --review reports/review.md
# ✗ Bad
# Manually transcribing review feedback into JSON
7. Re-Review After Modifications
After applying review feedback, run review again to confirm:
# Apply modifications
sdd apply-modifications my-spec-001 --from suggestions.json
# Re-review to confirm issues resolved
Skill(sdd-toolkit:sdd-fidelity-review) "Re-review spec my-spec-001"
8. Handle Rollbacks Gracefully
If rollback occurs:
- Read the error messages carefully
- Fix issues in modification file
- Preview again with
--dry-run - Retry application
# Failed with rollback
sdd apply-modifications my-spec-001 --from mods.json
# ✗ Rolled back due to validation errors
# Fix mods.json based on error messages
# Preview to verify fix
sdd apply-modifications my-spec-001 --from mods.json --dry-run
# Retry
sdd apply-modifications my-spec-001 --from mods.json
Limitations
Current Limitations
- No interactive guided mode - Interactive workflow is planned for Phase 2
- Limited operation types - Only update_task, add_verification, update_metadata currently supported
- No task reordering - Cannot change task order within phases yet
- No phase operations - Cannot add/remove/reorder phases
- Single spec at a time - No batch operations across multiple specs
- Manual batch creation - No automated batching or dependency resolution
Future Enhancements (Phase 2)
- Interactive modification builder - Guided prompts for building modifications
- Modification templates - Common patterns as reusable templates
- Diff visualization - Better visual diff output with highlighting
- Undo/redo support - History of modifications with rollback to any point
- Automated batching - Smart grouping of related modifications
- Multi-spec operations - Apply same modification to multiple specs
- Phase operations - Add, remove, reorder phases
- Task operations - Add, remove, reorder tasks
- Dependency tracking - Handle task dependencies during modifications
Troubleshooting
Issue: Parse-review finds no modifications
Problem:
sdd parse-review my-spec-001 --review reports/review.md
✗ No modifications found in review report
Solutions:
- Check review report format - Should contain clear modification language
- Ensure review was generated by sdd-fidelity-review or sdd-plan-review
- Look for patterns like "update task X to Y", "add verification step"
- Manual modification file creation may be needed for non-standard formats
Issue: Task ID not found
Problem:
✗ Error: Task task-5-3 not found in spec
Solutions:
- List all task IDs:
sdd context show my-spec-001 - Check for typos in task_id
- Verify task exists in current spec version
- Ensure you're modifying the correct spec
Issue: Validation fails after apply
Problem:
✗ Validation failed after applying modifications
✓ Rolled back all changes
Solutions:
- Read validation error messages carefully
- Check that all required fields are included in modifications
- Verify all references (phase_id, task_id) are valid
- Fix issues in modification file
- Preview with --dry-run before retrying
- Apply in smaller batches to isolate problematic modifications
Issue: Modifications applied but no visible changes
Problem:
✓ Applied 5 modifications
# But spec looks unchanged
Solutions:
- Check if modifications were already applied (idempotency)
- Verify modification file targets correct fields
- Compare with backup:
diff specs/active/spec.json specs/.backups/spec-backup.json - Review modification values - may be identical to existing values
Issue: Cannot find backup file
Problem: Need to rollback but backup file missing
Solutions:
- Check
.backups/folder in specs directory - Backups use timestamp:
{spec-id}-{YYYYMMDD-HHMMSS}.json - If backup missing, check git history for previous version
- Use
git log specs/active/{spec-id}.jsonto see commits
Examples Directory
See skills/sdd-modify/examples/ for detailed walkthroughs:
- apply-review.md - Complete workflow for applying fidelity review feedback
- bulk-modify.md - Bulk modifications from JSON file
- interactive.md - Interactive guided modification (future)
Summary
The sdd-modify skill provides systematic, safe spec modification:
- ✅ Safe - Automatic backup, validation, and rollback
- ✅ Systematic - Parse review feedback automatically
- ✅ Validated - Full validation after every apply
- ✅ Transparent - Clear previews and error messages
- ✅ Integrated - Works seamlessly with review workflows
Key Workflow:
Review → Parse → Preview → Apply → Validate → Re-review
For simple task status updates and journaling, use Skill(sdd-toolkit:sdd-update) instead.