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

> Find issues ready to work on with no blockers

## Syntax

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

## Description

The `ready` command identifies issues that are ready for immediate work. These are issues that:

* Have status `open` (not already in progress or closed)
* Are not archived
* Have no active blocking relationships (or all blockers are closed)

This command is essential for:

* Finding next work to start
* Agent task selection
* Daily planning and prioritization
* Identifying available work for team members

<Note>
  "Ready" means the issue has no dependencies blocking it. Use this to find work you can start immediately without waiting for other issues.
</Note>

## How "Ready" is Determined

An issue is considered ready when:

<Steps>
  <Step title="Status is open">
    The issue must have `status = 'open'`

    Issues that are `in_progress`, `needs_review`, or `closed` are excluded.
  </Step>

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

  <Step title="No active blockers">
    Either:

    * The issue has no "blocks" relationships pointing to it, OR
    * All issues blocking it have `status = 'closed'`

    If any blocker is still open, in\_progress, or blocked, the issue is not ready.
  </Step>
</Steps>

### Ready Issues View

The command queries the `ready_issues` database view:

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

This ensures only truly unblocked work is shown.

## Examples

### Find Ready Issues

List all issues ready to work on:

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

<Accordion title="Expected output">
  ```
  Ready Issues (3):

  ISSUE-005 Implement OAuth 2.0 authentication @alice
    Priority: 0

  ISSUE-008 Add rate limiting to API endpoints
    Priority: 1

  ISSUE-012 Write integration tests for auth flow @bob
    Priority: 2
  ```
</Accordion>

### No Ready Issues

When all issues are blocked or completed:

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

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

### JSON Output

Get machine-readable output for scripting:

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

<Accordion title="JSON output">
  ```json theme={null}
  {
    "issues": [
      {
        "id": "ISSUE-005",
        "uuid": "a1b2c3...",
        "title": "Implement OAuth 2.0 authentication",
        "content": "...",
        "status": "open",
        "priority": 0,
        "assignee": "alice",
        "archived": 0,
        "created_at": "2025-10-29T08:00:00Z",
        "updated_at": "2025-10-29T09:00:00Z",
        "closed_at": null,
        "parent_id": null
      },
      {
        "id": "ISSUE-008",
        "uuid": "d4e5f6...",
        "title": "Add rate limiting to API endpoints",
        "content": "...",
        "status": "open",
        "priority": 1,
        "assignee": null,
        "archived": 0,
        "created_at": "2025-10-28T14:00:00Z",
        "updated_at": "2025-10-28T14:00:00Z",
        "closed_at": null,
        "parent_id": null
      }
    ]
  }
  ```
</Accordion>

## Output Format

Ready issues are displayed with:

* **Issue ID** (cyan) - The unique identifier
* **Title** - Issue description
* **Assignee** (gray) - If assigned, shown as @username
* **Priority** - Lower number = higher priority (0 is highest)

Issues are sorted by:

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

## Common Workflows

### Daily Work Selection

<Steps>
  <Step title="Check ready work">
    ```bash theme={null}
    sudocode ready
    ```
  </Step>

  <Step title="Choose highest priority">
    Pick the first issue (highest priority)
  </Step>

  <Step title="Claim the work">
    ```bash theme={null}
    sudocode issue update ISSUE-005 --status in_progress --assignee alice
    ```
  </Step>

  <Step title="Start implementation">
    Begin working on the issue
  </Step>
</Steps>

### Agent Workflow

Automated agent claiming work:

```bash theme={null}
#!/bin/bash
# Agent script to claim and start work

# Get first ready issue
issue_id=$(sudocode --json ready | jq -r '.issues[0].id')

if [ -n "$issue_id" ] && [ "$issue_id" != "null" ]; then
  echo "Claiming $issue_id"

  # Update status and assignee
  sudocode issue update "$issue_id" \
    --status in_progress \
    --assignee "agent-01"

  # Read the issue details
  sudocode issue show "$issue_id"

  # Start implementation
  # ... agent implementation logic ...
else
  echo "No ready work available"
fi
```

### Filter by Priority

Find only high-priority ready work:

```bash theme={null}
# Get ready issues
sudocode --json ready | jq '.issues[] | select(.priority <= 1)'
```

This shows only issues with priority 0 or 1.

### Check for Specific Assignee

See what's ready for a specific person:

```bash theme={null}
# Get unassigned ready work
sudocode --json ready | jq '.issues[] | select(.assignee == null)'

# Get work assigned to alice
sudocode --json ready | jq '.issues[] | select(.assignee == "alice")'
```

## Understanding Blockers

### Why an Issue Might Not Be Ready

<AccordionGroup>
  <Accordion title="Blocked by another issue">
    **Scenario:** ISSUE-010 has `blocks` relationship to ISSUE-005

    **Result:** ISSUE-005 won't appear in ready list until ISSUE-010 is closed

    **Check blockers:**

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

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

  <Accordion title="Status is not open">
    **Scenario:** Issue is `in_progress` or `closed`

    **Result:** Only `open` issues appear in ready list

    **Check status:**

    ```bash theme={null}
    sudocode issue show ISSUE-005
    ```
  </Accordion>

  <Accordion title="Issue is archived">
    **Scenario:** Issue was archived

    **Result:** Archived issues are excluded from ready list

    **Check archive status:**

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

    Look for `archived: true`
  </Accordion>

  <Accordion title="Blocker was completed recently">
    **Scenario:** Blocker was just closed but database not synced

    **Result:** May not appear in ready list yet

    **Solution:**

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

### Making Issues Ready

To make a blocked issue ready:

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

    Check "Incoming Relationships" for blocks
  </Step>

  <Step title="Complete blocker issues">
    Work on and close the blocking issues:

    ```bash theme={null}
    sudocode issue close ISSUE-010
    ```
  </Step>

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

    ISSUE-005 should now appear
  </Step>
</Steps>

## Related Commands Comparison

<CardGroup cols={2}>
  <Card title="ready" icon="circle-check">
    **Find available work**

    * Shows open issues only
    * No active blockers
    * Sorted by priority
    * Ready to start immediately

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

  <Card title="blocked" icon="ban">
    **Find blocked work**

    * Shows blocked issues
    * Lists what blocks them
    * Identifies bottlenecks
    * Cannot start yet

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

<CardGroup cols={2}>
  <Card title="issue list --status open" icon="list">
    **All open issues**

    * Shows ALL open issues
    * Includes blocked ones
    * More filtering options
    * General issue browsing

    ```bash theme={null}
    sudocode issue list --status open
    ```
  </Card>

  <Card title="status" icon="chart-simple">
    **Project overview**

    * Shows ready count
    * Shows blocked count
    * Project-wide statistics
    * Quick health check

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

## Scripting Examples

### Auto-assign Ready Work

Automatically assign ready issues to agents:

```bash theme={null}
#!/bin/bash
agents=("agent-01" "agent-02" "agent-03")
agent_index=0

sudocode --json ready | jq -r '.issues[] | select(.assignee == null) | .id' | \
while read issue_id; do
  agent="${agents[$agent_index]}"
  echo "Assigning $issue_id to $agent"

  sudocode issue update "$issue_id" --assignee "$agent"

  agent_index=$(( (agent_index + 1) % ${#agents[@]} ))
done
```

### Ready Work Digest

Generate a daily ready work report:

```bash theme={null}
#!/bin/bash
echo "Ready Work Report - $(date)"
echo "============================"
echo ""

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

if [ "$count" -gt 0 ]; then
  echo "By Priority:"
  for p in 0 1 2 3 4; do
    p_count=$(sudocode --json ready | jq ".issues[] | select(.priority == $p)" | jq -s 'length')
    if [ "$p_count" -gt 0 ]; then
      echo "  Priority $p: $p_count issues"
    fi
  done

  echo ""
  echo "Unassigned: $(sudocode --json ready | jq '.issues[] | select(.assignee == null)' | jq -s 'length')"
fi
```

### Monitor Ready Work

Check if ready work becomes available:

```bash theme={null}
#!/bin/bash
# Run periodically to alert when work becomes ready

prev_count=0
while true; do
  count=$(sudocode --json ready | jq '.issues | length')

  if [ "$count" -gt "$prev_count" ]; then
    echo "$(date): New ready work available! ($count issues)"
    sudocode ready
  fi

  prev_count=$count
  sleep 300  # Check every 5 minutes
done
```

## Common Questions

<AccordionGroup>
  <Accordion title="Why doesn't my issue appear in ready list?">
    Check these conditions:

    1. Status must be `open`
    2. Must not be archived
    3. No open/in\_progress blockers

    Run:

    ```bash theme={null}
    sudocode issue show ISSUE-005
    sudocode blocked
    ```
  </Accordion>

  <Accordion title="Can I filter ready issues by assignee?">
    Not directly, but use JSON output with jq:

    ```bash theme={null}
    sudocode --json ready | jq '.issues[] | select(.assignee == "alice")'
    ```
  </Accordion>

  <Accordion title="What if ready shows issues I can't work on?">
    Some ready issues may require specific skills or context. Consider:

    * Adding assignee field to track who should work on it
    * Using priority to indicate difficulty
    * Adding tags for skill requirements
  </Accordion>

  <Accordion title="How do I prioritize within ready list?">
    The list is already sorted by priority (highest first), then by creation date (oldest first). To change priority:

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

  <Accordion title="Can agents automatically claim ready work?">
    Yes, use the JSON output to build automation:

    ```bash theme={null}
    issue_id=$(sudocode --json ready | jq -r '.issues[0].id')
    sudocode issue update "$issue_id" --status in_progress --assignee "agent-01"
    ```
  </Accordion>

  <Accordion title="What's the difference between ready and issue list --status open?">
    * **ready**: Only shows open issues with NO blockers
    * **issue list --status open**: Shows ALL open issues, including blocked ones

    Use `ready` when you want to find work you can start immediately.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Ready list is empty but I know there are open issues">
    **Cause:** All open issues are blocked

    **Solution:**
    Check blocked issues:

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

    Complete blocker issues to make them ready.
  </Accordion>

  <Accordion title="Issue appears ready but shows as blocked in issue show">
    **Cause:** Database may be out of sync

    **Solution:**
    Run sync:

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

  <Accordion title="Just closed a blocker but dependent issue not showing as ready">
    **Cause:** Database view not refreshed

    **Solution:**
    Views should update automatically. If not:

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

  <Accordion title="Too many ready issues, hard to choose">
    **Cause:** Need better prioritization

    **Solution:**
    Use priority field:

    ```bash theme={null}
    # Set high priority
    sudocode issue update ISSUE-005 --priority 0

    # Ready list automatically sorts by priority
    sudocode ready
    ```
  </Accordion>
</AccordionGroup>

## Related Commands

<CardGroup cols={3}>
  <Card title="blocked" icon="ban" href="/cli/blocked">
    Find blocked issues
  </Card>

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

  <Card title="issue list" icon="list" href="/cli/issue-list">
    List all issues with filters
  </Card>

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

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

## Next Steps

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

  <Step title="Choose an issue">
    Select based on priority and your skills
  </Step>

  <Step title="Claim the work">
    ```bash theme={null}
    sudocode issue update ISSUE-005 --status in_progress --assignee alice
    ```
  </Step>

  <Step title="View details">
    ```bash theme={null}
    sudocode issue show ISSUE-005
    ```
  </Step>

  <Step title="Start implementation">
    Begin working on the issue
  </Step>
</Steps>

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