sudocode spec delete

Syntax

sudocode spec delete <spec-id> [<spec-id>...]

Description

The spec delete command permanently removes specifications from your project. This operation:

Deletes the spec from the SQLite database
Removes the markdown file from .sudocode/specs/
Updates the JSONL file to reflect the deletion
Does NOT automatically delete related issues or relationships

This operation is permanent and cannot be undone. Consider archiving specs instead if you might need to reference them later.

Arguments

spec-id

string

required

One or more spec IDs to deleteExample: SPEC-001 or SPEC-001 SPEC-002 SPEC-003You can delete multiple specs in a single command by providing multiple IDs.

Examples

Delete a Single Spec

Remove one spec:

sudocode spec delete SPEC-050

Expected output

✓ Deleted spec SPEC-050

Delete Multiple Specs

Remove several specs at once:

sudocode spec delete SPEC-050 SPEC-051 SPEC-052

Expected output

✓ Deleted spec SPEC-050
✓ Deleted spec SPEC-051
✓ Deleted spec SPEC-052

Delete Non-Existent Spec

Attempt to delete a spec that doesn’t exist:

sudocode spec delete SPEC-999

Expected output

✗ Spec not found: SPEC-999

When deleting multiple specs, valid deletions proceed even if some IDs don’t exist:

sudocode spec delete SPEC-001 SPEC-999 SPEC-002

Expected output

✓ Deleted spec SPEC-001
✗ Spec not found: SPEC-999
✓ Deleted spec SPEC-002

JSON Output

Get machine-readable output:

sudocode --json spec delete SPEC-001 SPEC-002

JSON output

[
  {
    "id": "SPEC-001",
    "success": true
  },
  {
    "id": "SPEC-002",
    "success": true
  }
]

What Gets Deleted

When you delete a spec:

Database record removed

The spec is deleted from the SQLite specs table

Markdown file removed

The .md file in .sudocode/specs/ is deleted

JSONL updated

The deletion is recorded in specs.jsonl

Tags cleaned up

Tags associated with the spec are removed

What Doesn’t Get Deleted

The following are NOT automatically deleted:

Relationships

Relationships to/from the deleted spec remain in the database as orphaned entries. This is by design to preserve relationship history.Impact: Issues or other specs that reference the deleted spec will show broken relationships.Solution: Manually remove relationships before deleting, or clean them up afterward.

Issues implementing the spec

Issues that implement the deleted spec are not deleted. They remain in the database with an implements relationship pointing to a non-existent spec.Impact: These issues become orphaned.Solution: Close or reassign these issues before deleting the spec:

sudocode issue list --grep "SPEC-001"
sudocode issue close ISSUE-001 ISSUE-002

Feedback on the spec

Feedback provided to the spec is not automatically deleted.Impact: Feedback entries remain but point to a non-existent spec.Solution: Review and dismiss feedback before deleting:

sudocode feedback list --spec SPEC-001

Child specs

If the deleted spec is a parent, child specs are not deleted. They become orphaned with invalid parent_id references.Impact: Child specs lose their parent relationship.Solution: Update or delete child specs first:

sudocode spec show SPEC-001  # Check for children
sudocode spec update SPEC-003 --parent ""  # Remove parent

Safe Deletion Workflow

Follow these steps to safely delete a spec:

Review spec details

sudocode spec show SPEC-001

Check for:

Incoming relationships (issues implementing it)
Outgoing relationships (specs it depends on)
Child specs (if it’s a parent)
Feedback received

Handle relationships

Close or update related issues:

sudocode issue close ISSUE-001 ISSUE-002

Update child specs:

sudocode spec update SPEC-003 --parent ""

Address feedback

Dismiss any open feedback:

sudocode feedback list --spec SPEC-001
sudocode feedback dismiss FB-001 --comment "Spec deleted"

Delete the spec

sudocode spec delete SPEC-001

Verify deletion

sudocode spec list
sudocode spec show SPEC-001  # Should error

Alternative: Archive Instead of Delete

Consider archiving instead of deleting:

sudocode spec update SPEC-001 --archived true

Benefits of archiving:

Spec is hidden from default listings
Historical reference is preserved
Relationships remain intact
Can be unarchived if needed

When to delete vs archive:

Delete: Duplicate specs, test specs, genuinely wrong/useless content
Archive: Deprecated features, superseded designs, historical documentation

Common Workflows

Cleaning Up Old Specs

List deprecated specs

sudocode spec list --grep "deprecated"
sudocode spec list --priority 4

Review each spec

sudocode spec show SPEC-050

Close related issues

sudocode issue close ISSUE-020 ISSUE-021

Delete the specs

sudocode spec delete SPEC-050 SPEC-051

Bulk Delete with Scripting

Delete all archived specs:

# Get archived spec IDs and delete them
sudocode --json spec list --archived true | jq -r '.[] | .id' | xargs sudocode spec delete

Delete all low-priority specs:

# Delete all priority 4 specs
sudocode --json spec list --priority 4 | jq -r '.[] | .id' | xargs sudocode spec delete

Be very careful with bulk deletions. Always review specs before deleting.

Recovering from Accidental Deletion

If you accidentally delete a spec:

Check git history

git log .sudocode/specs.jsonl

Restore from git

git checkout HEAD~1 .sudocode/specs.jsonl
sudocode sync  # Re-import from JSONL

Or restore from backup

If you have backups of .sudocode/, restore the database and JSONL files

This is why sudocode uses git-tracked JSONL files as the source of truth. You can always recover from git history.

Common Questions

Is there a confirmation prompt before deleting?

No, spec delete executes immediately without confirmation. Be careful with this command.For safety, you could create a shell alias that prompts for confirmation:

alias spec-delete='read -p "Delete spec? (y/n) " -n 1 -r && echo && [[ $REPLY =~ ^[Yy]$ ]] && sudocode spec delete'

Can I undo a deletion?

Not directly, but you can recover from git:

git checkout HEAD~1 .sudocode/specs.jsonl
sudocode sync

This restores the JSONL file from the previous commit and re-imports it.

What happens to issues that implement a deleted spec?

The issues remain in the database, but their implements relationship points to a non-existent spec. This creates an orphaned relationship.Best practice: Close or update these issues before deleting the spec.

Should I delete or archive deprecated specs?

Archive for:

Superseded designs you might reference later
Historical documentation
Deprecated features still in use

Delete for:

Duplicate/accidental specs
Test/temporary specs
Genuinely incorrect content

Can I delete multiple specs by pattern?

Not directly, but you can use scripting:

# Delete all specs matching "test" in title
sudocode --json spec list --grep "test" | jq -r '.[] | .id' | xargs sudocode spec delete

Always review the list before executing!

Will deleting a parent spec delete children?

No, child specs are not automatically deleted. They become orphaned with invalid parent_id references.Update children first:

sudocode spec update SPEC-003 --parent ""

Troubleshooting

Error: Spec not found

Cause: The spec ID doesn’t existSolution: Verify the ID:

sudocode spec list

Error: Failed to delete spec

Cause: Database or file system errorSolution:

Check database isn’t locked by another process
Verify file permissions on .sudocode/ directory
Try syncing first: sudocode sync

Spec deleted but still appears in list

Cause: Cache or sync issueSolution: Run sync to ensure consistency:

sudocode sync

Markdown file remains after deletion

Cause: File deletion failed but database updatedSolution: Manually remove the file:

rm .sudocode/specs/spec-name.md

spec list

List all specs

spec show

View spec details

spec update

Update spec (archive instead)

issue close

Close related issues

feedback dismiss

Dismiss feedback

sync

Synchronize data

Next Steps

Review the spec

sudocode spec show SPEC-001

Consider archiving instead

sudocode spec update SPEC-001 --archived true

If deleting, clean up relationships

Close issues, dismiss feedback, update children

Delete the spec

sudocode spec delete SPEC-001

Commit changes

git add .sudocode/specs.jsonl
git commit -m "Delete deprecated spec"

Specs Concept Guide

Learn more about specs and their lifecycle

CLI Reference

Spec Commands

Issue Commands

Relationship Commands

Feedback Commands

Query & Sync Commands

sudocode spec delete

Syntax

Description

Arguments

Examples

Delete a Single Spec

Delete Multiple Specs

Delete Non-Existent Spec

JSON Output

What Gets Deleted

What Doesn’t Get Deleted

Safe Deletion Workflow

Alternative: Archive Instead of Delete

Common Workflows

Cleaning Up Old Specs

Bulk Delete with Scripting

Recovering from Accidental Deletion

Common Questions

Troubleshooting

spec list

spec show

spec update

issue close

feedback dismiss

sync

Next Steps

Specs Concept Guide

CLI Reference

Spec Commands

Issue Commands

Relationship Commands

Feedback Commands

Query & Sync Commands

​Syntax

​Description

​Arguments

​Examples

​Delete a Single Spec

​Delete Multiple Specs

​Delete Non-Existent Spec

​JSON Output

​What Gets Deleted

​What Doesn’t Get Deleted

​Safe Deletion Workflow

​Alternative: Archive Instead of Delete

​Common Workflows

​Cleaning Up Old Specs

​Bulk Delete with Scripting

​Recovering from Accidental Deletion

​Common Questions

​Troubleshooting

​Related Commands

spec list

spec show

spec update

issue close

feedback dismiss

sync

​Next Steps

Specs Concept Guide

Syntax

Description

Arguments

Examples

Delete a Single Spec

Delete Multiple Specs

Delete Non-Existent Spec

JSON Output

What Gets Deleted

What Doesn’t Get Deleted

Safe Deletion Workflow

Alternative: Archive Instead of Delete

Common Workflows

Cleaning Up Old Specs

Bulk Delete with Scripting

Recovering from Accidental Deletion

Common Questions

Troubleshooting

Related Commands

Next Steps