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

# Issues

> Actionable work items for agent execution

## What Are Issues?

Issues are the second tier in sudocode's 4-tier abstraction structure. They capture **agent intent** - the HOW to implement what specs define. Think of issues as actionable work items scoped to what an AI agent (or human developer) can accomplish in a single focused session.

<Note>
  **Key Principle:** Issues capture how to implement. Specs (tier 1) capture what to build. Issues are derived from specs and linked back to the requirements they fulfill.
</Note>

An **issue** is a structured work item that represents a concrete, actionable task. Issues can be:

* **Implementation tasks** - "Implement login endpoint"
* **Bug fixes** - "Fix token expiration bug"
* **Feature work** - "Add password reset flow"
* **Epics** - "Build authentication system" (contains sub-issues)
* **Chores** - "Update dependency versions"

### Issues vs. Specs

<CardGroup cols={2}>
  <Card title="Specs" icon="file-lines">
    **User intent** (WHAT)

    * High-level requirements
    * Written primarily by humans
    * Long-lived, evolve over time
    * Multiple issues per spec
  </Card>

  <Card title="Issues" icon="list-check">
    **Agent tasks** (HOW)

    * Actionable implementation
    * Created by humans or agents
    * Closed when complete
    * One spec per issue (typically)
  </Card>
</CardGroup>

<Warning>
  **Rule of thumb:** If it can be completed in one agent session or represents a single unit of work, it's an issue. If it requires multiple independent tasks or is strategic/architectural, it's a spec.
</Warning>

## Issue Lifecycle

Issues progress through a well-defined lifecycle from creation to completion:

```mermaid theme={null}
graph LR
    A[open] --> B[in_progress]
    B --> C[needs_review]
    C --> D[closed]
    A --> E[blocked]
    E --> B
    D -.reopen.-> A
    style A fill:#6B9AFF
    style B fill:#A855F7
    style E fill:#EF4444
    style C fill:#F59E0B
    style D fill:#10B981
```

<AccordionGroup>
  <Accordion title="open - Ready to be worked on">
    Issues start as `open` when created. An open issue means:

    * Ready to be claimed by an agent or developer
    * No blocking dependencies (or blockers resolved)
    * Has sufficient detail to begin work
    * May be in the "ready" queue for execution
  </Accordion>

  <Accordion title="in_progress - Currently being worked on">
    When an agent or developer claims an issue:

    * Status changes to `in_progress`
    * Assignee is set to the agent/user
    * Other agents know this work is claimed
    * Implementation is actively happening
  </Accordion>

  <Accordion title="blocked - Waiting on dependencies">
    Issues can become blocked when:

    * Another issue must be completed first
    * External dependency is unavailable
    * Waiting for spec clarification
    * Blockers tracked via `blocks` relationships
  </Accordion>

  <Accordion title="needs_review - Implementation complete, awaiting review">
    After implementation is done but before closing:

    * Code changes awaiting review
    * Testing in progress
    * Validation needed
    * Feedback being incorporated
  </Accordion>

  <Accordion title="closed - Work completed">
    Issues are closed when:

    * Implementation is complete
    * Tests pass
    * Code reviewed and merged
    * Requirements fulfilled
    * Can be reopened if needed
  </Accordion>
</AccordionGroup>

## Issue Types

Issues are categorized by type to help with organization and filtering:

| Type        | Purpose                    | Example                       |
| ----------- | -------------------------- | ----------------------------- |
| **task**    | Implementation work        | "Create login endpoint"       |
| **bug**     | Fix defects                | "Fix token expiration bug"    |
| **feature** | New functionality          | "Add password reset flow"     |
| **epic**    | Large work with sub-issues | "Build authentication system" |
| **chore**   | Maintenance work           | "Update dependencies"         |

## Issue Structure

Issues are stored as **markdown files with YAML frontmatter** in `.sudocode/issues/`:

### File Format

<CodeGroup>
  ```markdown Example Issue theme={null}
  ---
  id: ISSUE-001
  title: Implement OAuth 2.0 token endpoint
  description: Create REST endpoint for OAuth token exchange
  status: in_progress
  priority: 1
  issue_type: task
  assignee: agent-backend-dev
  estimated_minutes: 120
  created_at: 2025-10-29T10:00:00Z
  updated_at: 2025-10-29T15:30:00Z
  closed_at: null
  created_by: agent-planner
  tags: [auth, backend, api]
  ---

  # Implement OAuth 2.0 token endpoint

  Create REST endpoint for OAuth token exchange following RFC 6749.

  ## Description

  Build the OAuth 2.0 token endpoint that handles authorization
  code exchange and refresh token flows. This implements the
  requirements from [[SPEC-001]].

  ## Design Notes

  ### Endpoint Details
  - **URL:** `POST /api/auth/token`
  - **Grant types:** `authorization_code`, `refresh_token`
  - **Response:** JWT access token + refresh token
  - **Expiration:** 1hr access, 30-day refresh

  ### Security
  - Validate client credentials
  - Verify authorization code hasn't been used
  - Rate limit: 10 requests/minute per client
  - Store refresh tokens securely hashed

  ## Acceptance Criteria

  - [ ] Endpoint accepts valid authorization codes
  - [ ] Returns valid JWT access tokens
  - [ ] Handles refresh token flow
  - [ ] Returns proper error codes for invalid requests
  - [ ] Unit tests with >90% coverage
  - [ ] Integration tests for both grant types

  ## Implementation Notes

  Depends on [[@ISSUE-002]] (database schema) being completed first.

  ## Related Specs

  This implements requirement #1 from [[SPEC-001]].
  ```

  ```yaml Frontmatter Schema theme={null}
  id: string                    # ISSUE-001, ISSUE-042, etc.
  title: string                 # Short description (max 500 chars)
  description: string           # Detailed problem statement
  status: enum                  # open | in_progress | blocked | needs_review | closed
  priority: int                 # 0-4 (0=highest, 2=default)
  issue_type: enum              # bug | feature | task | epic | chore
  assignee: string?             # Agent ID or username (null if unassigned)
  estimated_minutes: int?       # Estimated effort (optional)
  created_at: timestamp         # ISO 8601 format
  updated_at: timestamp         # ISO 8601 format
  closed_at: timestamp?         # When closed (null if open)
  created_by: string            # Who created (user or agent)
  tags: [string]                # Free-form labels for organization
  ```
</CodeGroup>

<Info>
  **Flexible Content:** The markdown body is completely flexible. Common sections include Description, Design Notes, Acceptance Criteria, and Implementation Notes, but you can structure it however makes sense.
</Info>

## Cross-References

Issues support bidirectional linking to specs and other issues:

### Link to Specs

Reference the spec(s) this issue implements:

```markdown theme={null}
This implements requirement #1 from [[SPEC-001]].

See also [[SPEC-010]] for API design patterns.
```

### Link to Other Issues

Reference related issues:

```markdown theme={null}
Depends on [[@ISSUE-002]] (database schema) being completed first.

Related to [[@ISSUE-005]] (session management).
```

<Check>
  **Automatic Backlinks:** sudocode tracks all references automatically, enabling graph-based planning and dependency resolution.
</Check>

## Relationships and Dependencies

Issues can have typed relationships to model dependencies and connections:

### Relationship Types

| Type                | Description                 | Example                               |
| ------------------- | --------------------------- | ------------------------------------- |
| **blocks**          | Hard blocker dependency     | "ISSUE-001 blocks ISSUE-002"          |
| **implements**      | Implements a spec           | "ISSUE-001 implements SPEC-001"       |
| **parent-child**    | Epic/subtask hierarchy      | "ISSUE-010 is parent of ISSUE-011"    |
| **related**         | Contextual connection       | "ISSUE-001 related to ISSUE-005"      |
| **discovered-from** | Found during implementation | "ISSUE-020 discovered from ISSUE-015" |

### Creating Dependencies

```bash theme={null}
# ISSUE-002 cannot start until ISSUE-001 is done
sudocode link ISSUE-002 ISSUE-001 --type blocks

# ISSUE-001 implements SPEC-001
sudocode link ISSUE-001 SPEC-001 --type implements

# ISSUE-012 is a subtask of epic ISSUE-010
sudocode link ISSUE-012 ISSUE-010 --type parent-child
```

<Card title="Relationships Documentation" icon="diagram-project" href="/concepts/relationships">
  Learn more about relationship types and graph-based planning
</Card>

## Hierarchical Organization

Issues can be organized hierarchically for complex work:

```bash theme={null}
# Create an epic
sudocode issue create "Build Authentication System" \
  --issue-type epic \
  --priority 0

# Create subtasks
sudocode issue create "Implement login endpoint" \
  --parent ISSUE-001 \
  --priority 1

sudocode issue create "Implement registration endpoint" \
  --parent ISSUE-001 \
  --priority 1

sudocode issue create "Add password reset" \
  --parent ISSUE-001 \
  --priority 2
```

This creates a hierarchy:

```
ISSUE-001: Build Authentication System (epic)
├── ISSUE-002: Implement login endpoint
├── ISSUE-003: Implement registration endpoint
└── ISSUE-004: Add password reset
```

Use hierarchies to:

* Break epics into manageable tasks
* Organize related work items
* Track progress on large features
* Enable agent handoffs between subtasks

## Priority Levels

Issues use a 0-4 priority scale (same as specs):

<Accordion title="Priority Levels">
  * **0** - Critical (highest priority)
  * **1** - High
  * **2** - Medium (default)
  * **3** - Low
  * **4** - Lowest

  Priority affects:

  * **Execution order** - Combined with topological ordering of dependencies
  * **Ready queue** - Higher priority issues surface first
  * **Agent selection** - Agents claim highest priority ready work
</Accordion>

## Storage and Versioning

Issues are stored in three synchronized layers:

```
.sudocode/
├── issues/
│   ├── issues.jsonl          # Source of truth (git-tracked)
│   ├── ISSUE-001.md          # Human-editable markdown
│   ├── ISSUE-002.md
│   └── ISSUE-003.md
└── cache.db                   # SQLite cache (gitignored)
```

<AccordionGroup>
  <Accordion title="Markdown Files (.md)">
    **Purpose:** Human-editable interface

    * Located in `.sudocode/issues/`
    * YAML frontmatter + markdown body
    * Edit directly or via CLI
    * Synced to JSONL automatically
  </Accordion>

  <Accordion title="JSONL File (issues.jsonl)">
    **Purpose:** Source of truth, git-tracked

    * One JSON object per line
    * Contains all issue data
    * Committed to version control
    * Used for distribution via git
  </Accordion>

  <Accordion title="SQLite Cache (cache.db)">
    **Purpose:** Fast queries and relationships

    * Rebuilt from JSONL after git pull
    * Enables efficient graph queries
    * Not committed to git
    * Auto-synced from JSONL
  </Accordion>
</AccordionGroup>

<Info>
  **Git-Native:** Issues are version-controlled alongside code. Track work history, see who did what, and understand evolution over time.
</Info>

## Best Practices

### When to Create an Issue

<AccordionGroup>
  <Accordion title="✅ Good candidates for issues">
    * Concrete implementation tasks
    * Bug fixes with clear reproduction steps
    * Work that can be completed in one session
    * Tasks scoped for a single agent or developer
    * Subtasks of a larger spec or epic
    * Actionable items with clear acceptance criteria
  </Accordion>

  <Accordion title="❌ Not good candidates for issues">
    * Strategic decisions (create a spec instead)
    * Vague ideas without clear implementation path
    * Work requiring multiple independent components
    * High-level requirements (should be specs)
  </Accordion>
</AccordionGroup>

### Writing Effective Issues

<Steps>
  <Step title="Clear, actionable title">
    Use verb phrases: "Implement X", "Fix Y", "Add Z"
  </Step>

  <Step title="Detailed description">
    Include enough context for someone to start work immediately
  </Step>

  <Step title="Concrete acceptance criteria">
    Use checkboxes for clear definition of "done"
  </Step>

  <Step title="Link to specs">
    Use `[[SPEC-XXX]]` to reference requirements
  </Step>

  <Step title="Specify dependencies">
    Use `blocks` relationships for hard dependencies
  </Step>

  <Step title="Estimate effort (optional)">
    Help with capacity planning and prioritization
  </Step>
</Steps>

### Scoping Issues for Agents

Issues should be scoped to what an agent can complete in one focused session:

<CardGroup cols={2}>
  <Card title="✅ Well-scoped" icon="check">
    * "Implement POST /api/auth/login endpoint"
    * "Fix token expiration validation bug"
    * "Add unit tests for user service"
    * "Update API documentation for auth endpoints"
  </Card>

  <Card title="❌ Too broad" icon="xmark">
    * "Build authentication system" (epic, not issue)
    * "Improve performance" (too vague)
    * "Refactor codebase" (too large)
    * "Add features" (not specific)
  </Card>
</CardGroup>

## CLI Commands

Quick reference for working with issues:

```bash theme={null}
# Create an issue
sudocode issue create "Feature Title" --type task --priority 1

# List all issues
sudocode issue list

# Filter by status or assignee
sudocode issue list --status in_progress --assignee agent-1

# View issue details
sudocode issue show ISSUE-001

# Update issue
sudocode issue update ISSUE-001 --status in_progress --assignee alice

# Close issue
sudocode issue close ISSUE-001

# Delete issue
sudocode issue delete ISSUE-001
```

<Card title="Complete CLI Reference" icon="terminal" href="/cli/overview">
  See full documentation for all issue commands and options
</Card>

## Agent Workflows

### Claiming and Executing Work

Agents use issues to coordinate work:

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

    Returns unblocked issues in priority order
  </Step>

  <Step title="Claim an issue">
    ```bash theme={null}
    sudocode issue update ISSUE-001 \
      --status in_progress \
      --assignee agent-backend-dev
    ```
  </Step>

  <Step title="Implement and commit">
    Agent implements the feature and commits code
  </Step>

  <Step title="Provide feedback (if needed)">
    ```bash theme={null}
    sudocode feedback add ISSUE-001 SPEC-001 \
      --content "Need token rotation policy specified" \
      --type request
    ```
  </Step>

  <Step title="Close the issue">
    ```bash theme={null}
    sudocode issue close ISSUE-001
    ```
  </Step>
</Steps>

### Handling Blocked Work

When an issue is blocked:

```bash theme={null}
# Mark as blocked
sudocode issue update ISSUE-003 --status blocked

# See what's blocking it
sudocode issue show ISSUE-003

# View all blocked issues
sudocode issue list --status blocked

# Or use the blocked command
sudocode blocked
```

## Common Workflows

### Creating Issues from a Spec

<Steps>
  <Step title="Review the spec">
    ```bash theme={null}
    sudocode spec show SPEC-001
    ```
  </Step>

  <Step title="Create implementation issues">
    ```bash theme={null}
    sudocode issue create "Implement login endpoint" --priority 1
    sudocode issue create "Implement registration endpoint" --priority 1
    sudocode issue create "Add password reset flow" --priority 2
    ```
  </Step>

  <Step title="Link issues to spec">
    ```bash theme={null}
    sudocode link ISSUE-001 SPEC-001 --type implements
    sudocode link ISSUE-002 SPEC-001 --type implements
    sudocode link ISSUE-003 SPEC-001 --type implements
    ```
  </Step>

  <Step title="Model dependencies">
    ```bash theme={null}
    # Registration depends on login being done first
    sudocode link ISSUE-002 ISSUE-001 --type blocks
    ```
  </Step>
</Steps>

### Converting a Bug Report to an Issue

<Steps>
  <Step title="Create bug issue">
    ```bash theme={null}
    sudocode issue create "Fix token expiration bug" \
      --type bug \
      --priority 0 \
      --description "Users report tokens expiring too early"
    ```
  </Step>

  <Step title="Add reproduction steps">
    Edit `.sudocode/issues/ISSUE-001.md` to add:

    * Steps to reproduce
    * Expected behavior
    * Actual behavior
    * System information
  </Step>

  <Step title="Link to related spec (if applicable)">
    ```bash theme={null}
    sudocode link ISSUE-001 SPEC-001 --type implements
    ```
  </Step>

  <Step title="Assign and track">
    ```bash theme={null}
    sudocode issue update ISSUE-001 --assignee alice --status in_progress
    ```
  </Step>
</Steps>

## Next Steps

<CardGroup cols={2}>
  <Card title="Specs" icon="file-lines" href="/concepts/specs">
    Learn about specs - the high-level requirements issues implement
  </Card>

  <Card title="Relationships" icon="diagram-project" href="/concepts/relationships">
    Understand how to model dependencies and connections
  </Card>

  <Card title="Feedback System" icon="comments" href="/concepts/feedback">
    See how to provide feedback on specs from issues
  </Card>

  <Card title="Issue Commands" icon="terminal" href="/cli/issue-create">
    Complete CLI reference for managing issues
  </Card>
</CardGroup>