> ## 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 issue delete

> Delete one or more issues

## Syntax

```bash theme={null}
sudocode issue delete <issue-id> [<issue-id>...] [options]
```

## Description

The `issue delete` command removes issues from your project. By default, it performs a **soft delete** (closes the issue). Use `--hard` for permanent deletion.

### Soft Delete (Default)

* Sets issue status to `closed`
* Records `closed_at` timestamp
* Issue remains in database and JSONL
* Can be reopened if needed

### Hard Delete (with --hard flag)

* Permanently removes from database
* Updates JSONL to remove the issue
* Cannot be undone (except via git restore)

<Warning>
  **Hard deletion is permanent and cannot be undone** (except by restoring from git history). Consider closing or archiving issues instead if you might need to reference them later.
</Warning>

## Arguments

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

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

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

## Options

<ParamField path="--hard" type="boolean">
  Permanently delete from database (vs soft delete)

  **Example:** `--hard`

  Without this flag, the command performs a soft delete (closes the issue).
</ParamField>

## Examples

### Soft Delete (Default)

Close the issue (default behavior):

```bash theme={null}
sudocode issue delete ISSUE-050
```

<Accordion title="Expected output">
  ```
  ✓ Closed issue ISSUE-050
  ```
</Accordion>

This sets the status to `closed` but keeps the issue in the database.

### Hard Delete

Permanently remove an issue:

```bash theme={null}
sudocode issue delete ISSUE-050 --hard
```

<Accordion title="Expected output">
  ```
  ✓ Permanently deleted issue ISSUE-050
  ```
</Accordion>

### Delete Multiple Issues

Soft delete several issues:

```bash theme={null}
sudocode issue delete ISSUE-050 ISSUE-051 ISSUE-052
```

<Accordion title="Expected output">
  ```
  ✓ Closed issue ISSUE-050
  ✓ Closed issue ISSUE-051
  ✓ Closed issue ISSUE-052
  ```
</Accordion>

### Hard Delete Multiple Issues

Permanently remove several issues:

```bash theme={null}
sudocode issue delete ISSUE-050 ISSUE-051 ISSUE-052 --hard
```

<Accordion title="Expected output">
  ```
  ✓ Permanently deleted issue ISSUE-050
  ✓ Permanently deleted issue ISSUE-051
  ✓ Permanently deleted issue ISSUE-052
  ```
</Accordion>

### Delete Non-Existent Issue

Attempt to delete an issue that doesn't exist:

```bash theme={null}
sudocode issue delete ISSUE-999
```

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

### JSON Output

Get machine-readable output:

```bash theme={null}
sudocode --json issue delete ISSUE-050 --hard
```

<Accordion title="JSON output">
  ```json theme={null}
  [
    {
      "id": "ISSUE-050",
      "success": true,
      "action": "hard_delete"
    }
  ]
  ```
</Accordion>

For soft delete:

```json theme={null}
[
  {
    "id": "ISSUE-050",
    "success": true,
    "action": "soft_delete",
    "status": "closed"
  }
]
```

## Soft Delete vs Hard Delete

<CardGroup cols={2}>
  <Card title="Soft Delete (Default)" icon="circle-xmark">
    **Closes the issue**

    * Status set to `closed`
    * Remains in database
    * Can be reopened
    * Preserves relationships
    * Safer option
  </Card>

  <Card title="Hard Delete (--hard)" icon="trash">
    **Permanent removal**

    * Removed from database
    * Removed from JSONL
    * Cannot be undone
    * Orphans relationships
    * Use with caution
  </Card>
</CardGroup>

**When to use each:**

* **Soft delete:** Most cases - completed work, decided not to do, obsolete
* **Hard delete:** Duplicates, test issues, genuinely wrong content

## What Gets Deleted (Hard Delete)

When you hard delete an issue:

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

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

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

## What Doesn't Get Deleted (Hard Delete)

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

<AccordionGroup>
  <Accordion title="Relationships">
    Relationships to/from the deleted issue remain in the database as orphaned entries.

    **Impact:** Specs or other issues that reference the deleted issue will show broken relationships.

    **Solution:** Manually remove relationships before deleting.
  </Accordion>

  <Accordion title="Feedback provided by this issue">
    Feedback this issue provided to specs is not automatically deleted.

    **Impact:** Feedback entries remain but point to a non-existent issue.

    **Solution:** Review and dismiss feedback before deleting:

    ```bash theme={null}
    sudocode issue show ISSUE-050  # Check for feedback
    ```
  </Accordion>

  <Accordion title="Child issues">
    If the deleted issue is a parent, child issues are not deleted. They become orphaned with invalid `parent_id` references.

    **Impact:** Child issues lose their parent relationship.

    **Solution:** Update or delete child issues first:

    ```bash theme={null}
    sudocode issue show ISSUE-050  # Check for children
    ```
  </Accordion>

  <Accordion title="Blocking relationships">
    Issues blocked by the deleted issue remain blocked with invalid blocker reference.

    **Impact:** Blocked issues stay blocked but blocker doesn't exist.

    **Solution:** Remove blocking relationships first.
  </Accordion>
</AccordionGroup>

## Safe Deletion Workflow

Follow these steps to safely hard delete an issue:

<Steps>
  <Step title="Review issue details">
    ```bash theme={null}
    sudocode issue show ISSUE-050
    ```

    Check for:

    * Outgoing relationships (what it implements/blocks)
    * Incoming relationships (what blocks it)
    * Parent/child relationships
    * Feedback provided
  </Step>

  <Step title="Remove relationships">
    Manually clean up if needed (no unlink command currently exists)
  </Step>

  <Step title="Update dependent issues">
    If this issue blocks others, unblock them:

    ```bash theme={null}
    sudocode issue show ISSUE-051  # Check what was blocked
    ```
  </Step>

  <Step title="Hard delete">
    ```bash theme={null}
    sudocode issue delete ISSUE-050 --hard
    ```
  </Step>

  <Step title="Verify deletion">
    ```bash theme={null}
    sudocode issue list
    sudocode issue show ISSUE-050  # Should error
    ```
  </Step>
</Steps>

## Alternative: Close or Archive

Consider these alternatives to deletion:

### Close (Soft Delete)

```bash theme={null}
sudocode issue close ISSUE-050
# or
sudocode issue delete ISSUE-050  # Without --hard
```

**Benefits:**

* Issue preserved for reference
* Can be reopened if needed
* Relationships stay intact
* Shows in closed issues list

### Archive

```bash theme={null}
sudocode issue update ISSUE-050 --archived true
```

**Benefits:**

* Hidden from default listings
* Preserves all data and relationships
* Can be unarchived later
* Good for abandoned work

### Comparison

| Action          | Visible             | Reopenable                 | Relationships | Best For             |
| --------------- | ------------------- | -------------------------- | ------------- | -------------------- |
| **Close**       | Yes (when filtered) | Yes                        | Intact        | Completed work       |
| **Archive**     | No (hidden)         | Yes                        | Intact        | Abandoned work       |
| **Hard Delete** | No (gone)           | No (must restore from git) | Orphaned      | Duplicates, mistakes |

## Common Workflows

### Cleaning Up Duplicates

<Steps>
  <Step title="Find duplicates">
    ```bash theme={null}
    sudocode issue list --grep "duplicate"
    ```
  </Step>

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

  <Step title="Hard delete duplicates">
    ```bash theme={null}
    sudocode issue delete ISSUE-050 ISSUE-051 --hard
    ```
  </Step>
</Steps>

### Bulk Delete with Scripting

Delete all closed issues older than 90 days:

```bash theme={null}
# Soft delete (close) old issues
sudocode --json issue list --status closed | \
  jq -r '.[] | select(.closed_at < (now - 90*24*60*60 | strftime("%Y-%m-%dT%H:%M:%SZ"))) | .id' | \
  xargs sudocode issue delete --hard
```

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

### Recovering from Accidental Deletion

If you accidentally hard delete an issue:

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

  <Step title="Restore from git">
    ```bash theme={null}
    git checkout HEAD~1 .sudocode/issues.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="What's the difference between delete and close?">
    Without `--hard`, `issue delete` is identical to `issue close` - it soft deletes by closing the issue.

    * `sudocode issue delete ISSUE-001` = `sudocode issue close ISSUE-001`
    * `sudocode issue delete ISSUE-001 --hard` = permanent deletion

    Use `issue close` for clarity when you intend to close (not delete).
  </Accordion>

  <Accordion title="Is there a confirmation prompt?">
    No, the command executes immediately without confirmation, even for hard deletes.

    For safety, create a shell alias with confirmation:

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

  <Accordion title="Can I undo a deletion?">
    * **Soft delete:** Yes, reopen the issue: `sudocode issue update ISSUE-001 --status open`
    * **Hard delete:** Not directly, but recover from git: `git checkout HEAD~1 .sudocode/issues.jsonl`
  </Accordion>

  <Accordion title="What happens to issues that depend on a deleted issue?">
    They become orphaned with broken relationships:

    * Issues implementing a deleted spec show broken `implements` link
    * Issues blocked by a deleted issue show broken `blocks` link

    **Best practice:** Clean up relationships before hard deleting.
  </Accordion>

  <Accordion title="Should I delete or archive completed work?">
    **Close** completed work (or soft delete):

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

    **Archive** abandoned work:

    ```bash theme={null}
    sudocode issue update ISSUE-001 --archived true
    ```

    **Hard delete** only:

    * Duplicate issues
    * Test issues
    * Genuinely incorrect content
  </Accordion>

  <Accordion title="Can I delete multiple issues by pattern?">
    Yes, using scripting:

    ```bash theme={null}
    # Delete all issues matching "test" in title (soft delete)
    sudocode --json issue list --grep "test" | jq -r '.[] | .id' | xargs sudocode issue delete

    # Hard delete (be very careful!)
    sudocode --json issue list --grep "test" | jq -r '.[] | .id' | xargs sudocode issue delete --hard
    ```

    **Always review the list first!**
  </Accordion>
</AccordionGroup>

## Troubleshooting

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

    **Solution:**
    Verify the ID:

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

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

    **Solution:**

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

  <Accordion title="Issue 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="Hard delete failed but database updated">
    **Cause:** JSONL export failed

    **Solution:**
    Run export manually:

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

## Related Commands

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

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

  <Card title="issue close" icon="circle-check" href="/cli/issue-close">
    Close issues (soft delete)
  </Card>

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

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

## Next Steps

<Steps>
  <Step title="Review the issue">
    ```bash theme={null}
    sudocode issue show ISSUE-050
    ```
  </Step>

  <Step title="Consider alternatives">
    Close: `sudocode issue close ISSUE-050`

    Archive: `sudocode issue update ISSUE-050 --archived true`
  </Step>

  <Step title="If hard deleting, clean up">
    Remove relationships and update dependencies
  </Step>

  <Step title="Delete">
    ```bash theme={null}
    sudocode issue delete ISSUE-050 --hard
    ```
  </Step>

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

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