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

# Creating Issues

> How to create and organize issues with the sudocode MCP tools.

Issues are actionable work items that agents claim and complete. They represent implementation tasks that turn specifications into working code.

<Frame>
  <img src="https://mintcdn.com/sudocode/Ik176kmcsPL91kj4/images/issue-example.png?fit=max&auto=format&n=Ik176kmcsPL91kj4&q=85&s=afcd83b89cfa9df5ec30ecf104f2fce4" alt="Example of a sudocode issue" width="2072" height="1316" data-path="images/issue-example.png" />
</Frame>

## When to Create an Issue

Create issues to track discrete, actionable work. Think of issues as your agent's work queue.

<CardGroup cols={2}>
  <Card title="Implement Specs" icon="code">
    Break down specifications into discrete implementation tasks that agents can execute
  </Card>

  <Card title="Manage Dependencies" icon="diagram-project">
    Use issues to capture the dependency of work items and enforce execution order
  </Card>

  <Card title="Enable Discovery" icon="magnifying-glass">
    Create discovery issues that leave behind other issues and specs as artifacts
  </Card>
</CardGroup>

**Don't create issues for:**

* Large, ambiguous goals without clear actionability
* Defining requirements for larger tasks (use specs instead)
* Temporary notes or reminders (use comments or external tools)

## How to Create an Issue

### Method 1: Spec-Driven Implementation

Create issues that implement specific sections or requirements from a spec.

<Steps>
  <Step title="Review the spec">
    ```
    > User: Could you take a look at spec [[s-abc123]] and break it down into issues?

    ⏺ Agent: I'll review the spec and create implementation issues.

    ⏺ plugin:sudocode:sudocode - show_spec (MCP)(spec_id: "s-abc123"...

    [Agent reviews spec structure and requirements]
    ```
  </Step>

  <Step title="Agent creates linked issues">
    ```
    ⏺ Agent: I've reviewed the spec. Let me break this into three focused issues:

    1. Detect token expiration and trigger refresh
    2. Implement refresh request flow with rotation
    3. Handle error scenarios and fallback logic

    Let me create these issues.

    ⏺ plugin:sudocode:sudocode - upsert_issue (MCP)(title: "Detect token
    expiration and trigger refresh", description: "Implements [[s-abc123]]
    section 2.1: Token Expiration Detection...", priority: 0...

    ⏺ Created i-xyz789. Now linking to spec...

    ⏺ plugin:sudocode:sudocode - link (MCP)(from_id: "i-xyz789",
    to_id: "s-abc123", type: "implements"...

    [Agent creates remaining issues and links them]
    ```
  </Step>

  <Step title="Verify relationships">
    ```
    > User: Show me i-xyz789 to confirm it's linked.

    ⏺ Agent: Let me show you the issue details.

    ⏺ plugin:sudocode:sudocode - show_issue (MCP)(issue_id: "i-xyz789"...

    ⏺ Issue i-xyz789 shows it implements s-abc123 and includes references
    to specific spec sections.
    ```

    <Note>
      **Agent doesn't always create dependencies:** If you notice that the agent hasn't established dependency relationships between related issues, you can prompt it directly:

      ```
      > User: Make sure that you capture the dependency between issues

      ⏺ plugin:sudocode:sudocode - link (MCP)(from_id: "i-7xqw",
      to_id: "i-yy9c", type: "depends-on")
        ⎿  {
             "from": "i-7xqw",
             "to": "i-yy9c",
           … +3 lines

      ⏺ Perfect! I've added all the dependency relationships between the
      issues. Here's the dependency graph:

        Dependency Structure

        i-7l9z (TypeScript types)
          ↓
          ├─→ i-yy9c (EditorService)
      ```
    </Note>
  </Step>
</Steps>

**Best for:** Implementing well-defined specifications with clear requirements.

### Method 2: Breaking Down Large Issues

Take a large or complex issue (epic) and split it into smaller, manageable sub-issues.

<Steps>
  <Step title="Identify the epic">
    ```
    > User: Issue i-big456 is too large to tackle at once. Can you break
    this down into smaller pieces?

    ⏺ Agent: I'll review the issue and break it into sub-issues.

    ⏺ plugin:sudocode:sudocode - show_issue (MCP)(issue_id: "i-big456"...

    [Agent analyzes the scope and complexity]
    ```
  </Step>

  <Step title="Create child issues">
    ```
    ⏺ Agent: I can break i-big456 into 4 focused subtasks:

    1. Database schema migration
    2. API endpoint implementation
    3. Frontend component updates
    4. Integration tests

    ⏺ plugin:sudocode:sudocode - upsert_issue (MCP)(title: "Database schema
    migration for user settings", parent: "i-big456", priority: 0...

    ⏺ Created i-sub001 as a child of i-big456.

    [Agent creates remaining child issues]
    ```
  </Step>

  <Step title="Set up dependencies">
    ```
    ⏺ Agent: The API work depends on the schema migration. Let me set up
    that dependency.

    ⏺ plugin:sudocode:sudocode - link (MCP)(from_id: "i-sub002",
    to_id: "i-sub001", type: "depends-on"...

    ⏺ Now i-sub002 won't show as ready until i-sub001 is closed.
    ```
  </Step>
</Steps>

**Best for:** Complex features that need to be broken into sequential or parallel work streams.

### Method 3: Discovery-Driven Issues

Create new issues when you discover unexpected work during implementation.

<Steps>
  <Step title="Discover new work">
    ```
    > User: While working on i-auth789, I noticed the password validation
    is inconsistent across endpoints. Should we fix this?

    ⏺ Agent: That's a good catch. Let me create an issue to track this
    improvement.

    ⏺ plugin:sudocode:sudocode - upsert_issue (MCP)(title: "Standardize
    password validation across all endpoints", description: "Discovered
    while implementing authentication...", priority: 2, tags: ["security",
    "refactoring"]...
    ```
  </Step>

  <Step title="Link to source">
    ```
    ⏺ Agent: I'll link this to the issue where we discovered it.

    ⏺ plugin:sudocode:sudocode - link (MCP)(from_id: "i-new999",
    to_id: "i-auth789", type: "discovered-from"...

    ⏺ Created i-new999 and linked it to i-auth789 to track provenance.
    ```
  </Step>

  <Step title="Decide priority">
    ```
    > User: This should be done before we ship authentication.

    ⏺ Agent: I'll mark it as blocking the authentication issue.

    ⏺ plugin:sudocode:sudocode - link (MCP)(from_id: "i-new999",
    to_id: "i-auth789", type: "blocks"...

    ⏺ Now i-auth789 won't show as ready until i-new999 is closed.
    ```
  </Step>
</Steps>

**Best for:** Capturing emergent work, technical debt, or issues discovered during code review.

### Method 4: Standalone Ad-Hoc Work

Create individual issues for bugs, quick features, or tasks that don't relate to a spec.

<Steps>
  <Step title="Create the issue">
    ```
    > User: Create an issue to fix the broken link in the README.

    ⏺ Agent: I'll create a quick fix issue.

    ⏺ plugin:sudocode:sudocode - upsert_issue (MCP)(title: "Fix broken
    documentation link in README", description: "Link to contributing guide
    returns 404", priority: 3, tags: ["documentation", "quick-fix"]...

    ⏺ Created i-doc555 with low priority.
    ```
  </Step>

  <Step title="Agent completes immediately">
    ```
    ⏺ Agent: This is a quick fix. Let me handle it right now.

    [Agent fixes the link]

    ⏺ plugin:sudocode:sudocode - upsert_issue (MCP)(issue_id: "i-doc555",
    status: "closed"...

    ⏺ Closed i-doc555. The README link is now fixed.
    ```
  </Step>
</Steps>

**Best for:** Small bugs, typos, quick improvements, and isolated tasks.

## Organizing Issues

### Priority Levels

Priority levels help agents decide what to work on first

Ask an agent to set priority when creating or updating issues.

### Issue Hierarchies

Use parent-child relationships for issue breakdown:

```
i-epic001: Implement user authentication (parent)
├── i-sub001: Add password hashing with bcrypt (child)
├── i-sub002: Create login endpoint with JWT (child)
└── i-sub003: Add session management (child)
```

Simply ask an agent to create child issues with the parent parameter.

### Dependency Management

Define execution order using relationship types:

**blocks**: Hard blocker (B blocks A means A can't start until B is done)

```
i-schema001 blocks i-api001
```

**depends-on**: General dependency (A depends on B means B should finish first)

```
i-integration001 depends-on i-unit-tests001
```

Ask an agent to link issues with these relationships.

### Tagging

Use tags for categorization and filtering:

```
["backend", "authentication", "security"]
["frontend", "ui", "react"]
["database", "migration", "postgres"]
```

Agents automatically suggest tags based on content, but you can also specify them explicitly.

## Best Practices

<AccordionGroup>
  <Accordion title="Keep Issues Focused">
    Each issue should represent a single, cohesive piece of work.

    **Good:**

    ```
    Title: "Add rate limiting to login endpoint"
    Description: Implement token bucket rate limiter on /api/login
    - 5 attempts per 15 minutes per IP
    - Return 429 with Retry-After header
    ```

    **Bad:**

    ```
    Title: "Improve API security"
    Description: Add rate limiting, input validation, CORS, and audit logging
    ```
  </Accordion>

  <Accordion title="Link Issues to Specs">
    Always use the `implements` relationship to connect issues to specs.

    **Why it matters:**

    * Agents can reference spec requirements during implementation
    * Agents can provide feedback on spec clarity
    * You can track which specs are implemented vs. pending

    **How:**
    Ask agents to link issues using: `from_id: "i-xyz", to_id: "s-abc", type: "implements"`
  </Accordion>

  <Accordion title="Use Dependencies Wisely">
    Only create blockers for true dependencies, not nice-to-haves.

    **Good dependency:**

    ```
    i-db-migration blocks i-api-endpoint
    (Can't use new schema until migration runs)
    ```

    **Bad dependency:**

    ```
    i-write-tests blocks i-deploy
    (Tests are important but technically not a blocker)
    ```

    Over-using blockers creates bottlenecks. Use priority instead when possible.
  </Accordion>

  <Accordion title="Archive Completed Work">
    Mark issues as archived when they're no longer relevant for context.

    ```
    > User: Archive all closed issues older than 30 days.

    ⏺ Agent: I'll update those issues.

    ⏺ plugin:sudocode:sudocode - upsert_issue (MCP)(issue_id: "i-old001",
    archived: true...

    [Agent archives obsolete issues]
    ```

    Archived issues are hidden from default queries but preserved for history.
  </Accordion>
</AccordionGroup>

## Issue Lifecycle

<Steps>
  <Step title="Create">
    Issue starts with status `open` and appears in the backlog.
  </Step>

  <Step title="Claim">
    Agent changes status to `in_progress` when starting work.
  </Step>

  <Step title="Complete">
    Agent changes status to `closed` when work is done.
  </Step>

  <Step title="Provide Feedback">
    If issue implements a spec, agent provides feedback on spec before closing.
  </Step>
</Steps>

## Related Documentation

<CardGroup cols={2}>
  <Card title="Spec Creation" icon="file-lines" href="/mcp/spec-creation">
    Creating specifications for requirements
  </Card>

  <Card title="Issue Execution" icon="play" href="/mcp/issue-execution">
    How agents claim and complete work
  </Card>

  <Card title="Agent Workflows" icon="route" href="/mcp/workflows">
    Practical workflow examples
  </Card>

  <Card title="Issues Concept" icon="list-check" href="/concepts/issues">
    Deep dive on issue management
  </Card>
</CardGroup>

## Next Steps

<Steps>
  <Step title="Choose a method">
    Pick the issue creation method that fits your needs:

    * **Spec-driven**: Implementing requirements
    * **Issue breakdown**: Breaking down epics
    * **Discovery-driven**: Capturing emergent work
    * **Ad-hoc**: Standalone bugs or quick tasks
  </Step>

  <Step title="Create your first issue">
    Try creating a spec-driven issue:

    ```
    You: "Create an issue to implement [[s-abc123]]"
    Agent: [Creates issue and links it to the spec]
    ```
  </Step>

  <Step title="Organize with relationships">
    Set up dependencies and hierarchies:

    * Use parent-child for epic breakdown
    * Use blocks/depends-on for execution order
    * Use discovered-from to track provenance
  </Step>

  <Step title="Let agents execute">
    Once issues are created, agents will:

    * Check `ready` to find unblocked work
    * Claim issues by setting status to `in_progress`
    * Provide feedback on specs during implementation
    * Close issues when complete
  </Step>
</Steps>