> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sudocode.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# sudocode spec delete

> Delete one or more specifications

## Syntax

```bash theme={null}
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

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

## Arguments

<ParamField path="spec-id" type="string" required>
  One or more spec IDs to delete

  **Example:** `SPEC-001` or `SPEC-001 SPEC-002 SPEC-003`

  You can delete multiple specs in a single command by providing multiple IDs.
</ParamField>

## Examples

### Delete a Single Spec

Remove one spec:

```bash theme={null}
sudocode spec delete SPEC-050
```

<Accordion title="Expected output">
  ```
  ✓ Deleted spec SPEC-050
  ```
</Accordion>

### Delete Multiple Specs

Remove several specs at once:

```bash theme={null}
sudocode spec delete SPEC-050 SPEC-051 SPEC-052
```

<Accordion title="Expected output">
  ```
  ✓ Deleted spec SPEC-050
  ✓ Deleted spec SPEC-051
  ✓ Deleted spec SPEC-052
  ```
</Accordion>

### Delete Non-Existent Spec

Attempt to delete a spec that doesn't exist:

```bash theme={null}
sudocode spec delete SPEC-999
```

<Accordion title="Expected output">
  ```
  ✗ Spec not found: SPEC-999
  ```
</Accordion>

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

```bash theme={null}
sudocode spec delete SPEC-001 SPEC-999 SPEC-002
```

<Accordion title="Expected output">
  ```
  ✓ Deleted spec SPEC-001
  ✗ Spec not found: SPEC-999
  ✓ Deleted spec SPEC-002
  ```
</Accordion>

### JSON Output

Get machine-readable output:

```bash theme={null}
sudocode --json spec delete SPEC-001 SPEC-002
```

<Accordion title="JSON output">
  ```json theme={null}
  [
    {
      "id": "SPEC-001",
      "success": true
    },
    {
      "id": "SPEC-002",
      "success": true
    }
  ]
  ```
</Accordion>

## What Gets Deleted

When you delete a spec:

<Steps>
  <Step title="Database record removed">
    The spec is deleted from the SQLite `specs` table
  </Step>

  <Step title="Markdown file removed">
    The `.md` file in `.sudocode/specs/` is deleted
  </Step>

  <Step title="JSONL updated">
    The deletion is recorded in `specs.jsonl`
  </Step>

  <Step title="Tags cleaned up">
    Tags associated with the spec are removed
  </Step>
</Steps>

## What Doesn't Get Deleted

<Warning>
  The following are **NOT** automatically deleted:
</Warning>

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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:

    ```bash theme={null}
    sudocode issue list --grep "SPEC-001"
    sudocode issue close ISSUE-001 ISSUE-002
    ```
  </Accordion>

  <Accordion title="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:

    ```bash theme={null}
    sudocode feedback list --spec SPEC-001
    ```
  </Accordion>

  <Accordion title="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:

    ```bash theme={null}
    sudocode spec show SPEC-001  # Check for children
    sudocode spec update SPEC-003 --parent ""  # Remove parent
    ```
  </Accordion>
</AccordionGroup>

## Safe Deletion Workflow

Follow these steps to safely delete a spec:

<Steps>
  <Step title="Review spec details">
    ```bash theme={null}
    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
  </Step>

  <Step title="Handle relationships">
    Close or update related issues:

    ```bash theme={null}
    sudocode issue close ISSUE-001 ISSUE-002
    ```

    Update child specs:

    ```bash theme={null}
    sudocode spec update SPEC-003 --parent ""
    ```
  </Step>

  <Step title="Address feedback">
    Dismiss any open feedback:

    ```bash theme={null}
    sudocode feedback list --spec SPEC-001
    sudocode feedback dismiss FB-001 --comment "Spec deleted"
    ```
  </Step>

  <Step title="Delete the spec">
    ```bash theme={null}
    sudocode spec delete SPEC-001
    ```
  </Step>

  <Step title="Verify deletion">
    ```bash theme={null}
    sudocode spec list
    sudocode spec show SPEC-001  # Should error
    ```
  </Step>
</Steps>

## Alternative: Archive Instead of Delete

Consider archiving instead of deleting:

```bash theme={null}
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

<Steps>
  <Step title="List deprecated specs">
    ```bash theme={null}
    sudocode spec list --grep "deprecated"
    sudocode spec list --priority 4
    ```
  </Step>

  <Step title="Review each spec">
    ```bash theme={null}
    sudocode spec show SPEC-050
    ```
  </Step>

  <Step title="Close related issues">
    ```bash theme={null}
    sudocode issue close ISSUE-020 ISSUE-021
    ```
  </Step>

  <Step title="Delete the specs">
    ```bash theme={null}
    sudocode spec delete SPEC-050 SPEC-051
    ```
  </Step>
</Steps>

### Bulk Delete with Scripting

Delete all archived specs:

```bash theme={null}
# 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:

```bash theme={null}
# Delete all priority 4 specs
sudocode --json spec list --priority 4 | jq -r '.[] | .id' | xargs sudocode spec delete
```

<Warning>
  Be very careful with bulk deletions. Always review specs before deleting.
</Warning>

### Recovering from Accidental Deletion

If you accidentally delete a spec:

<Steps>
  <Step title="Check git history">
    ```bash theme={null}
    git log .sudocode/specs.jsonl
    ```
  </Step>

  <Step title="Restore from git">
    ```bash theme={null}
    git checkout HEAD~1 .sudocode/specs.jsonl
    sudocode sync  # Re-import from JSONL
    ```
  </Step>

  <Step title="Or restore from backup">
    If you have backups of `.sudocode/`, restore the database and JSONL files
  </Step>
</Steps>

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

## Common Questions

<AccordionGroup>
  <Accordion title="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:

    ```bash theme={null}
    alias spec-delete='read -p "Delete spec? (y/n) " -n 1 -r && echo && [[ $REPLY =~ ^[Yy]$ ]] && sudocode spec delete'
    ```
  </Accordion>

  <Accordion title="Can I undo a deletion?">
    Not directly, but you can recover from git:

    ```bash theme={null}
    git checkout HEAD~1 .sudocode/specs.jsonl
    sudocode sync
    ```

    This restores the JSONL file from the previous commit and re-imports it.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="Can I delete multiple specs by pattern?">
    Not directly, but you can use scripting:

    ```bash theme={null}
    # 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!
  </Accordion>

  <Accordion title="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:

    ```bash theme={null}
    sudocode spec update SPEC-003 --parent ""
    ```
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Error: Spec not found">
    **Cause:** The spec ID doesn't exist

    **Solution:**
    Verify the ID:

    ```bash theme={null}
    sudocode spec list
    ```
  </Accordion>

  <Accordion title="Error: Failed to delete spec">
    **Cause:** Database or file system error

    **Solution:**

    1. Check database isn't locked by another process
    2. Verify file permissions on `.sudocode/` directory
    3. Try syncing first: `sudocode sync`
  </Accordion>

  <Accordion title="Spec deleted but still appears in list">
    **Cause:** Cache or sync issue

    **Solution:**
    Run sync to ensure consistency:

    ```bash theme={null}
    sudocode sync
    ```
  </Accordion>

  <Accordion title="Markdown file remains after deletion">
    **Cause:** File deletion failed but database updated

    **Solution:**
    Manually remove the file:

    ```bash theme={null}
    rm .sudocode/specs/spec-name.md
    ```
  </Accordion>
</AccordionGroup>

## Related Commands

<CardGroup cols={3}>
  <Card title="spec list" icon="list" href="/cli/spec-list">
    List all specs
  </Card>

  <Card title="spec show" icon="eye" href="/cli/spec-show">
    View spec details
  </Card>

  <Card title="spec update" icon="pen-to-square" href="/cli/spec-update">
    Update spec (archive instead)
  </Card>

  <Card title="issue close" icon="circle-check" href="/cli/issue-close">
    Close related issues
  </Card>

  <Card title="feedback dismiss" icon="check" href="/cli/feedback-dismiss">
    Dismiss feedback
  </Card>

  <Card title="sync" icon="arrows-rotate" href="/cli/sync">
    Synchronize data
  </Card>
</CardGroup>

## Next Steps

<Steps>
  <Step title="Review the spec">
    ```bash theme={null}
    sudocode spec show SPEC-001
    ```
  </Step>

  <Step title="Consider archiving instead">
    ```bash theme={null}
    sudocode spec update SPEC-001 --archived true
    ```
  </Step>

  <Step title="If deleting, clean up relationships">
    Close issues, dismiss feedback, update children
  </Step>

  <Step title="Delete the spec">
    ```bash theme={null}
    sudocode spec delete SPEC-001
    ```
  </Step>

  <Step title="Commit changes">
    ```bash theme={null}
    git add .sudocode/specs.jsonl
    git commit -m "Delete deprecated spec"
    ```
  </Step>
</Steps>

<Card title="Specs Concept Guide" icon="book" href="/concepts/specs">
  Learn more about specs and their lifecycle
</Card>