> ## 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 blocked

> Find issues that are blocked by dependencies and identify project bottlenecks

## Syntax

```bash theme={null}
sudocode blocked [options]
```

## Description

The `blocked` command identifies issues that cannot proceed because they're waiting on other work to complete. These are issues that:

* Have status `open`, `in_progress`, or `blocked`
* Are not archived
* Have at least one active "blocks" relationship where the blocker is still open

This command is essential for:

* Identifying bottlenecks in your project
* Understanding project dependencies
* Prioritizing work to unblock others
* Finding issues that need attention

<Warning>
  Blocked issues cannot be started or progressed until their blocking dependencies are resolved. Use this command to understand what's preventing progress.
</Warning>

## How "Blocked" is Determined

An issue is considered blocked when:

<Steps>
  <Step title="Active status">
    The issue has `status IN ('open', 'in_progress', 'blocked')`

    Closed issues are excluded even if they have blocking relationships.
  </Step>

  <Step title="Not archived">
    The issue must not be archived (`archived = 0`)
  </Step>

  <Step title="Has active blockers">
    The issue has at least one "blocks" relationship where:

    * The relationship points FROM this issue TO a blocker
    * The blocker issue has status `open`, `in_progress`, or `blocked`

    If all blockers are closed, the issue is no longer considered blocked.
  </Step>
</Steps>

### Blocked Issues View

The command queries the `blocked_issues` database view:

```sql theme={null}
SELECT
    i.*,
    COUNT(r.to_id) as blocked_by_count,
    GROUP_CONCAT(r.to_id) as blocked_by_ids
FROM issues i
JOIN relationships r ON i.id = r.from_id AND r.from_type = 'issue'
JOIN issues blocker ON r.to_id = blocker.id AND r.to_type = 'issue'
WHERE i.status IN ('open', 'in_progress', 'blocked')
  AND i.archived = 0
  AND r.relationship_type = 'blocks'
  AND blocker.status IN ('open', 'in_progress', 'blocked')
GROUP BY i.id
ORDER BY priority DESC, created_at DESC;
```

This ensures only issues with active blockers are shown.

## Examples

### Find Blocked Issues

List all blocked issues:

```bash theme={null}
sudocode blocked
```

<Accordion title="Expected output">
  ```
  Blocked Issues (2):

  ISSUE-007 Implement password reset flow
    Reason: blocked

  ISSUE-015 Deploy authentication service to production
    Reason: open
  ```
</Accordion>

### No Blocked Issues

When all issues are unblocked:

```bash theme={null}
sudocode blocked
```

<Accordion title="Expected output">
  ```
  No blocked issues
  ```
</Accordion>

### JSON Output

Get detailed information about blocked issues:

```bash theme={null}
sudocode --json blocked
```

<Accordion title="JSON output">
  ```json theme={null}
  {
    "issues": [
      {
        "id": "ISSUE-007",
        "uuid": "a1b2c3...",
        "title": "Implement password reset flow",
        "content": "...",
        "status": "blocked",
        "priority": 1,
        "assignee": "alice",
        "archived": 0,
        "created_at": "2025-10-28T10:00:00Z",
        "updated_at": "2025-10-29T09:00:00Z",
        "closed_at": null,
        "parent_id": null,
        "blocked_by_count": 2,
        "blocked_by_ids": "ISSUE-005,ISSUE-006"
      },
      {
        "id": "ISSUE-015",
        "uuid": "d4e5f6...",
        "title": "Deploy authentication service to production",
        "content": "...",
        "status": "open",
        "priority": 0,
        "assignee": null,
        "archived": 0,
        "created_at": "2025-10-27T14:00:00Z",
        "updated_at": "2025-10-27T14:00:00Z",
        "closed_at": null,
        "parent_id": null,
        "blocked_by_count": 1,
        "blocked_by_ids": "ISSUE-012"
      }
    ]
  }
  ```
</Accordion>

The JSON output includes:

* **blocked\_by\_count** - Number of issues blocking this one
* **blocked\_by\_ids** - Comma-separated list of blocker IDs

## Output Format

Blocked issues are displayed with:

* **Issue ID** (cyan) - The unique identifier
* **Title** - Issue description
* **Reason** - Current status (usually "blocked" or "open")

Issues are sorted by:

1. **Priority** (descending) - Highest priority first
2. **Created date** (descending) - Older issues first

## Finding What Blocks an Issue

To see detailed blocker information:

```bash theme={null}
sudocode issue show ISSUE-007
```

<Accordion title="Example output showing blockers">
  ```
  ISSUE-007: Implement password reset flow
  Status: blocked
  Priority: 1
  Assignee: alice

  Content:
  Add password reset functionality to the authentication system...

  Incoming Relationships:
    ISSUE-005 (blocks) → ISSUE-007
    ISSUE-006 (blocks) → ISSUE-007

  Outgoing Relationships:
    ISSUE-007 (implements) → SPEC-001
  ```
</Accordion>

The "Incoming Relationships" with type "blocks" show what's blocking this issue.

## Common Workflows

### Identify Bottlenecks

<Steps>
  <Step title="Find blocked issues">
    ```bash theme={null}
    sudocode blocked
    ```
  </Step>

  <Step title="Review each blocker">
    For each blocked issue, check details:

    ```bash theme={null}
    sudocode issue show ISSUE-007
    ```

    Note the incoming "blocks" relationships
  </Step>

  <Step title="Prioritize blockers">
    Focus on completing the blocking issues:

    ```bash theme={null}
    sudocode issue update ISSUE-005 --priority 0
    sudocode issue update ISSUE-006 --priority 0
    ```
  </Step>

  <Step title="Complete blockers">
    Work on and close the blocking issues
  </Step>

  <Step title="Verify unblocked">
    ```bash theme={null}
    sudocode blocked
    ```

    ISSUE-007 should no longer appear
  </Step>
</Steps>

### Unblock High-Priority Work

<Steps>
  <Step title="Find blocked high-priority issues">
    ```bash theme={null}
    sudocode --json blocked | jq '.issues[] | select(.priority == 0)'
    ```
  </Step>

  <Step title="Identify their blockers">
    ```bash theme={null}
    sudocode issue show ISSUE-015
    ```
  </Step>

  <Step title="Complete blocker">
    ```bash theme={null}
    sudocode issue close ISSUE-012
    ```
  </Step>

  <Step title="Update blocked issue">
    ```bash theme={null}
    # Can now start work
    sudocode issue update ISSUE-015 --status in_progress
    ```
  </Step>
</Steps>

### Weekly Bottleneck Review

Regular review to prevent blocked work piling up:

```bash theme={null}
#!/bin/bash
echo "Blocked Issues Review - $(date)"
echo "==============================="
echo ""

count=$(sudocode --json blocked | jq '.issues | length')
echo "Total blocked: $count"

if [ "$count" -gt 0 ]; then
  echo ""
  echo "Blocked issues:"

  sudocode --json blocked | jq -r '.issues[] |
    "  \(.id): \(.title)
    Status: \(.status)
    Blocked by: \(.blocked_by_count) issue(s)
    Blocker IDs: \(.blocked_by_ids)
    Priority: \(.priority)
    ---"'
fi
```

## Understanding Blocker Relationships

### Why Issues Become Blocked

<AccordionGroup>
  <Accordion title="Explicit dependency">
    **Scenario:** ISSUE-007 depends on ISSUE-005 being completed first

    **Setup:**

    ```bash theme={null}
    sudocode link ISSUE-005 ISSUE-007 blocks
    ```

    **Result:** ISSUE-007 is blocked until ISSUE-005 is closed
  </Accordion>

  <Accordion title="Sequential work">
    **Scenario:** Testing can't start until implementation is done

    **Setup:**

    ```bash theme={null}
    # ISSUE-010: Implementation
    # ISSUE-011: Testing
    sudocode link ISSUE-010 ISSUE-011 blocks
    ```

    **Result:** ISSUE-011 blocked until ISSUE-010 complete
  </Accordion>

  <Accordion title="Multiple blockers">
    **Scenario:** Deployment needs both testing and documentation

    **Setup:**

    ```bash theme={null}
    sudocode link ISSUE-012 ISSUE-015 blocks  # Testing blocks deployment
    sudocode link ISSUE-013 ISSUE-015 blocks  # Docs block deployment
    ```

    **Result:** ISSUE-015 blocked until BOTH are complete
  </Accordion>

  <Accordion title="Cascading blocks">
    **Scenario:** Chain of dependencies

    **Setup:**

    ```bash theme={null}
    sudocode link ISSUE-001 ISSUE-002 blocks
    sudocode link ISSUE-002 ISSUE-003 blocks
    ```

    **Result:**

    * ISSUE-002 blocked by ISSUE-001
    * ISSUE-003 blocked by ISSUE-002
    * ISSUE-003 indirectly blocked by ISSUE-001
  </Accordion>
</AccordionGroup>

### Unblocking Issues

To unblock an issue, complete its blockers:

<Steps>
  <Step title="Find the blockers">
    ```bash theme={null}
    sudocode issue show ISSUE-007
    ```

    Look for "Incoming Relationships" with type "blocks"
  </Step>

  <Step title="Complete each blocker">
    ```bash theme={null}
    sudocode issue close ISSUE-005
    sudocode issue close ISSUE-006
    ```
  </Step>

  <Step title="Verify unblocked">
    ```bash theme={null}
    sudocode blocked
    ```

    ISSUE-007 should no longer appear

    Check ready work:

    ```bash theme={null}
    sudocode ready
    ```

    ISSUE-007 should now be ready if status is 'open'
  </Step>
</Steps>

## Blocked vs Ready

<CardGroup cols={2}>
  <Card title="blocked" icon="ban">
    **Cannot proceed**

    * Has active blockers
    * Waiting on dependencies
    * May have status 'blocked'
    * Shows bottlenecks

    ```bash theme={null}
    sudocode blocked
    ```
  </Card>

  <Card title="ready" icon="circle-check">
    **Can start now**

    * No active blockers
    * Status is 'open'
    * Available for work
    * Shows opportunities

    ```bash theme={null}
    sudocode ready
    ```
  </Card>
</CardGroup>

An issue is either blocked OR ready, never both:

* **Blocked** = has dependencies
* **Ready** = no dependencies

## Scripting Examples

### Find Critical Blocked Work

Identify high-priority blocked issues:

```bash theme={null}
#!/bin/bash
# Find P0 blocked issues

p0_blocked=$(sudocode --json blocked | jq '.issues[] | select(.priority == 0)')

if [ -n "$p0_blocked" ]; then
  echo "ALERT: High-priority work is blocked!"
  echo "$p0_blocked" | jq -r '.id + ": " + .title'
else
  echo "No high-priority blocked issues"
fi
```

### Blocker Dependency Report

Show what blocks what:

```bash theme={null}
#!/bin/bash
echo "Blocker Dependency Report"
echo "========================="
echo ""

sudocode --json blocked | jq -r '.issues[] |
"Issue: \(.id) - \(.title)
Status: \(.status)
Priority: \(.priority)
Blocked by \(.blocked_by_count) issue(s): \(.blocked_by_ids)
"'
```

### Auto-prioritize Blockers

Automatically increase priority of blockers:

```bash theme={null}
#!/bin/bash
# For each blocked P0 issue, set its blockers to P0

sudocode --json blocked | jq -r '.issues[] | select(.priority == 0) | .blocked_by_ids' | \
tr ',' '\n' | \
while read blocker_id; do
  if [ -n "$blocker_id" ]; then
    echo "Prioritizing blocker: $blocker_id"
    sudocode issue update "$blocker_id" --priority 0
  fi
done
```

### Monitor Block Duration

Track how long issues have been blocked:

```bash theme={null}
#!/bin/bash
# Find issues blocked for more than 7 days

seven_days_ago=$(date -d '7 days ago' '+%Y-%m-%dT%H:%M:%SZ')

sudocode --json blocked | jq --arg threshold "$seven_days_ago" -r '
.issues[] |
select(.updated_at < $threshold) |
"WARNING: \(.id) blocked since \(.updated_at)
  Title: \(.title)
  Priority: \(.priority)
"'
```

## Common Questions

<AccordionGroup>
  <Accordion title="Why is my issue blocked even though I can work on it?">
    The "blocks" relationship is explicitly defined, not based on actual work capability. If you can work on it independently:

    1. Consider if the blocker relationship is necessary
    2. Remove the relationship if not needed:
       ```bash theme={null}
       # Currently no unlink command, would need database edit
       ```
  </Accordion>

  <Accordion title="Can I work on a blocked issue anyway?">
    Yes technically, but not recommended. The relationship exists for a reason - usually technical or logical dependencies. Working on a blocked issue may lead to:

    * Rework when blocker completes
    * Conflicts or compatibility issues
    * Wasted effort
  </Accordion>

  <Accordion title="How do I find what's blocking a specific issue?">
    Use `issue show`:

    ```bash theme={null}
    sudocode issue show ISSUE-007
    ```

    Look for "Incoming Relationships" with type "blocks"
  </Accordion>

  <Accordion title="What if I have circular blocking relationships?">
    This creates a deadlock where nothing can proceed. To detect:

    ```bash theme={null}
    sudocode blocked
    ```

    Check if issues block each other. Resolve by removing one relationship or completing one issue first.
  </Accordion>

  <Accordion title="Can specs be blocked too?">
    The current `blocked` command only shows issues. Specs can have blocking relationships, but aren't included in this command's output.
  </Accordion>

  <Accordion title="Why doesn't blocked count match the number shown?">
    The count shows issues with active blockers. Some blockers may have been closed recently, causing the counts to update.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Issue appears in both blocked and ready">
    **Cause:** Database inconsistency

    **Solution:**

    ```bash theme={null}
    sudocode sync
    ```

    This should not happen - an issue should be either blocked OR ready, never both.
  </Accordion>

  <Accordion title="Closed a blocker but issue still shows as blocked">
    **Cause:** Other blockers still open, or database not refreshed

    **Solution:**

    1. Check all blockers:
       ```bash theme={null}
       sudocode issue show ISSUE-007
       ```
    2. Sync database:
       ```bash theme={null}
       sudocode sync
       sudocode blocked
       ```
  </Accordion>

  <Accordion title="Blocked list shows issues I don't recognize">
    **Cause:** May include archived or old issues

    **Solution:**
    Check individual issues:

    ```bash theme={null}
    sudocode issue show ISSUE-XXX
    ```

    Archive if no longer relevant:

    ```bash theme={null}
    sudocode issue update ISSUE-XXX --archived true
    ```
  </Accordion>

  <Accordion title="Too many blocked issues, can't make progress">
    **Cause:** Over-use of blocking relationships

    **Solution:**
    Review relationships and remove unnecessary ones. Focus on true dependencies only.
  </Accordion>
</AccordionGroup>

## Related Commands

<CardGroup cols={3}>
  <Card title="ready" icon="circle-check" href="/cli/ready">
    Find ready work
  </Card>

  <Card title="status" icon="chart-simple" href="/cli/status">
    Project status overview
  </Card>

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

  <Card title="link" icon="link" href="/cli/link">
    Create blocking relationships
  </Card>

  <Card title="issue update" icon="pen-to-square" href="/cli/issue-update">
    Update issue status
  </Card>
</CardGroup>

## Next Steps

<Steps>
  <Step title="Find blocked issues">
    ```bash theme={null}
    sudocode blocked
    ```
  </Step>

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

  <Step title="Prioritize blockers">
    ```bash theme={null}
    sudocode issue update ISSUE-005 --priority 0
    ```
  </Step>

  <Step title="Complete blocker work">
    Work on and close blocking issues
  </Step>

  <Step title="Verify unblocked">
    ```bash theme={null}
    sudocode ready
    ```

    Previously blocked issues should now appear as ready
  </Step>
</Steps>

<Card title="Relationships Concept Guide" icon="book" href="/concepts/relationships">
  Learn more about dependency modeling and blocking relationships
</Card>