sudocode blocked - sudocode

Syntax

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

Blocked issues cannot be started or progressed until their blocking dependencies are resolved. Use this command to understand what’s preventing progress.

How “Blocked” is Determined

An issue is considered blocked when:

Active status

The issue has status IN ('open', 'in_progress', 'blocked')Closed issues are excluded even if they have blocking relationships.

Not archived

The issue must not be archived (archived = 0)

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.

Blocked Issues View

The command queries the blocked_issues database view:

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:

sudocode blocked

Expected output

Blocked Issues (2):

ISSUE-007 Implement password reset flow
  Reason: blocked

ISSUE-015 Deploy authentication service to production
  Reason: open

No Blocked Issues

When all issues are unblocked:

sudocode blocked

Expected output

No blocked issues

JSON Output

Get detailed information about blocked issues:

sudocode --json blocked

JSON output

{
  "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"
    }
  ]
}

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:

Priority (descending) - Highest priority first
Created date (descending) - Older issues first

Finding What Blocks an Issue

To see detailed blocker information:

sudocode issue show ISSUE-007

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

The “Incoming Relationships” with type “blocks” show what’s blocking this issue.

Common Workflows

Identify Bottlenecks

Find blocked issues

sudocode blocked

Review each blocker

For each blocked issue, check details:

sudocode issue show ISSUE-007

Note the incoming “blocks” relationships

Prioritize blockers

Focus on completing the blocking issues:

sudocode issue update ISSUE-005 --priority 0
sudocode issue update ISSUE-006 --priority 0

Complete blockers

Work on and close the blocking issues

Verify unblocked

sudocode blocked

ISSUE-007 should no longer appear

Unblock High-Priority Work

Find blocked high-priority issues

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

Identify their blockers

sudocode issue show ISSUE-015

Complete blocker

sudocode issue close ISSUE-012

Update blocked issue

# Can now start work
sudocode issue update ISSUE-015 --status in_progress

Weekly Bottleneck Review

Regular review to prevent blocked work piling up:

#!/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

Explicit dependency

Scenario: ISSUE-007 depends on ISSUE-005 being completed firstSetup:

sudocode link ISSUE-005 ISSUE-007 blocks

Result: ISSUE-007 is blocked until ISSUE-005 is closed

Sequential work

Scenario: Testing can’t start until implementation is doneSetup:

# ISSUE-010: Implementation
# ISSUE-011: Testing
sudocode link ISSUE-010 ISSUE-011 blocks

Result: ISSUE-011 blocked until ISSUE-010 complete

Multiple blockers

Scenario: Deployment needs both testing and documentationSetup:

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

Cascading blocks

Scenario: Chain of dependenciesSetup:

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

Unblocking Issues

To unblock an issue, complete its blockers:

Find the blockers

sudocode issue show ISSUE-007

Look for “Incoming Relationships” with type “blocks”

Complete each blocker

sudocode issue close ISSUE-005
sudocode issue close ISSUE-006

Verify unblocked

sudocode blocked

ISSUE-007 should no longer appearCheck ready work:

sudocode ready

ISSUE-007 should now be ready if status is ‘open’

Blocked vs Ready

blocked

Cannot proceed

Has active blockers
Waiting on dependencies
May have status ‘blocked’
Shows bottlenecks

sudocode blocked

ready

Can start now

No active blockers
Status is ‘open’
Available for work
Shows opportunities

sudocode ready

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:

#!/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:

#!/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:

#!/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:

#!/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

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:

Consider if the blocker relationship is necessary

Remove the relationship if not needed:

# Currently no unlink command, would need database edit

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

How do I find what's blocking a specific issue?

Use issue show:

sudocode issue show ISSUE-007

Look for “Incoming Relationships” with type “blocks”

What if I have circular blocking relationships?

This creates a deadlock where nothing can proceed. To detect:

sudocode blocked

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

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.

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.

Troubleshooting

Issue appears in both blocked and ready

Cause: Database inconsistencySolution:

sudocode sync

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

Closed a blocker but issue still shows as blocked

Cause: Other blockers still open, or database not refreshedSolution:

Check all blockers:
```
sudocode issue show ISSUE-007
```
Sync database:
```
sudocode sync
sudocode blocked
```

Blocked list shows issues I don't recognize

Cause: May include archived or old issuesSolution: Check individual issues:

sudocode issue show ISSUE-XXX

Archive if no longer relevant:

sudocode issue update ISSUE-XXX --archived true

Too many blocked issues, can't make progress

Cause: Over-use of blocking relationshipsSolution: Review relationships and remove unnecessary ones. Focus on true dependencies only.

ready

Find ready work

status

Project status overview

issue show

View blocker details

link

Create blocking relationships

issue update

Update issue status

Next Steps

Find blocked issues

sudocode blocked

Review blockers

sudocode issue show ISSUE-007

Prioritize blockers

sudocode issue update ISSUE-005 --priority 0

Complete blocker work

Work on and close blocking issues

Verify unblocked

sudocode ready

Previously blocked issues should now appear as ready

Relationships Concept Guide

Learn more about dependency modeling and blocking relationships

CLI Reference

Spec Commands

Issue Commands

Relationship Commands

Feedback Commands

Query & Sync Commands

​Syntax

​Description

​How “Blocked” is Determined

​Blocked Issues View

​Examples

​Find Blocked Issues

​No Blocked Issues

​JSON Output

​Output Format

​Finding What Blocks an Issue

​Common Workflows

​Identify Bottlenecks

​Unblock High-Priority Work

​Weekly Bottleneck Review

​Understanding Blocker Relationships

​Why Issues Become Blocked

​Unblocking Issues

​Blocked vs Ready

blocked

ready

​Scripting Examples

​Find Critical Blocked Work

​Blocker Dependency Report

​Auto-prioritize Blockers

​Monitor Block Duration

​Common Questions

​Troubleshooting

​Related Commands

ready

status

issue show

link

issue update

​Next Steps

Relationships Concept Guide

Syntax

Description

How “Blocked” is Determined

Blocked Issues View

Examples

Find Blocked Issues

No Blocked Issues

JSON Output

Output Format

Finding What Blocks an Issue

Common Workflows

Identify Bottlenecks

Unblock High-Priority Work

Weekly Bottleneck Review

Understanding Blocker Relationships

Why Issues Become Blocked

Unblocking Issues

Blocked vs Ready

Scripting Examples

Find Critical Blocked Work

Blocker Dependency Report

Auto-prioritize Blockers

Monitor Block Duration

Common Questions

Troubleshooting

Related Commands

Next Steps