Skip to main content

​
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:
1

Active status

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

Not archived

The issue must not be archived (archived = 0)
3

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

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

No blocked issues

​
JSON Output

Get detailed information about blocked issues: 
sudocode --json blocked

{
  "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:
  1. Priority (descending) - Highest priority first
  2. Created date (descending) - Older issues first

​
Finding What Blocks an Issue

To see detailed blocker information: 
sudocode issue show ISSUE-007

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

1

Find blocked issues

sudocode blocked
2

Review each blocker

For each blocked issue, check details:
sudocode issue show ISSUE-007
Note the incoming “blocks” relationships
3

Prioritize blockers

Focus on completing the blocking issues:
sudocode issue update ISSUE-005 --priority 0
sudocode issue update ISSUE-006 --priority 0
4

Complete blockers

Work on and close the blocking issues
5

Verify unblocked

sudocode blocked
ISSUE-007 should no longer appear

​
Unblock High-Priority Work

1

Find blocked high-priority issues

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

Identify their blockers

sudocode issue show ISSUE-015
3

Complete blocker

sudocode issue close ISSUE-012
4

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

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
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
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
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:
1

Find the blockers

sudocode issue show ISSUE-007
Look for “Incoming Relationships” with type “blocks”
2

Complete each blocker

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

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

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: 
    # Currently no unlink command, would need database edit
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
Use issue show:
sudocode issue show ISSUE-007
Look for “Incoming Relationships” with type “blocks”
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.
The current blocked command only shows issues. Specs can have blocking relationships, but aren’t included in this command’s output.
The count shows issues with active blockers. Some blockers may have been closed recently, causing the counts to update.

​
Troubleshooting

Cause: Database inconsistencySolution:
sudocode sync
This should not happen - an issue should be either blocked OR ready, never both.
Cause: Other blockers still open, or database not refreshedSolution:
  1. Check all blockers: 
    sudocode issue show ISSUE-007
  2. Sync database: 
    sudocode sync
sudocode blocked
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
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

1

Find blocked issues

sudocode blocked
2

Review blockers

sudocode issue show ISSUE-007
3

Prioritize blockers

sudocode issue update ISSUE-005 --priority 0
4

Complete blocker work

Work on and close blocking issues
5

Verify unblocked

sudocode ready
Previously blocked issues should now appear as ready

Relationships Concept Guide

Learn more about dependency modeling and blocking relationships