Issues Overview
Learn how Issues in CodeCourier help you discover, track, and resolve codebase problems using AI-powered scanning sessions, answering sessions, and batch execution via work chains.
7 min read
issuestriageai-discovery
Issues are CodeCourier’s system for discovering, tracking, and resolving problems in your codebase. Whether identified by an AI-powered scanning session or created manually, each issue represents a discrete unit of work - a bug to fix, an improvement to make, or a task to complete. Issues can be executed individually through workflow runs or batched together into work chains for sequential resolution.
What are Issues?
An issue is a structured record that captures a problem or task along with enough context for an AI agent to resolve it. Every issue includes a title, description, priority level, and an optional suggestedPrompt that provides specific instructions for an AI agent. Issues can originate from two sources:
- AI Discovery - An issue session scans your codebase using an AI agent in a cloud sandbox and automatically extracts a list of issues.
- Manual Creation - You create issues directly through the UI, specifying the title, description, priority, and optional fix instructions.
Issue Lifecycle
Every issue moves through a simple, linear lifecycle tracked in real time:
| Status | Description |
|---|---|
new | The issue has been created (manually or extracted from a session) and is ready to be worked on. |
running | A workflow run has been launched to resolve this issue. The issue is linked to the active run. |
completed | The linked run finished successfully. The issue is resolved. |
failed | The linked run failed or could not be found. The issue may need manual attention or a retry. |
Automatic Status Sync
Issue statuses are kept in sync with their linked runs automatically. A background process checks running issues and updates their status when the associated run completes or fails.
How Issues Relate to Other Concepts
Issues sit at the intersection of several CodeCourier systems:
- Runs - When you execute an issue, a workflow run is created and linked to it. The run performs the actual work (code changes, PR creation) inside an E2B sandbox.
- Workflows- You select which workflow blueprint to use when running an issue. The workflow defines the multi-step agent pipeline (e.g., Designer → Checker).
- Personas- The personas configured in the workflow determine the AI agent’s behavior and system prompt when resolving the issue.
- Work Chains - Multiple issues can be grouped into a work chain for sequential batch execution, similar to a CI pipeline of fixes.
- Issue Sessions - AI-powered scanning sessions that analyze your codebase and produce a list of issues automatically.
- Answering Sessions - After an Issue Session completes, an Answering Session resolves the questions and assumptions generated during scanning, refining them into actionable context before implementation begins.
The Issue Discovery & Resolution Flow
The complete lifecycle from discovery to resolution follows this pattern:
- Issue Session - An AI Planner agent scans your codebase and generates a structured list of issues, along with questions and assumptions about requirements, scope, and architecture.
- Answering Session - An Answering Agent reviews the generated questions and assumptions, refines them, and produces approved answers that serve as context for implementation. You review each assumption and approve, decline, or correct it.
- Issue Resolution - Individual issues are run via workflow pipelines, using the approved assumptions as additional context. Issues can also be batched into a work chain for sequential automated execution.
Skipping the Answering Session
The Answering Session is optional. For straightforward scanning tasks where the issues are self-contained, you can skip directly from a completed Issue Session to running individual issues or launching a work chain.
When to Use Issues vs. Workflows
| Use Issues When... | Use Workflows Directly When... |
|---|---|
| You want AI to discover problems in your codebase | You already know exactly what to build |
| You have multiple discrete bugs or tasks to resolve | You have a single, well-defined task |
| You want to batch-execute fixes in sequence | You want a one-off run with a specific prompt |
| You want to track resolution status per problem | You only need to track a single run |
| You want to refine requirements before implementation | Requirements are already fully specified |
Key Features
- AI-Powered Discovery - Issue sessions use a cloud sandbox to scan your entire codebase and surface bugs, security vulnerabilities, performance issues, and improvement opportunities.
- Answering Sessions- A structured AI-driven Q&A flow that resolves questions and validates assumptions from issue scanning sessions before any implementation begins, ensuring the AI has the right context to produce accurate fixes.
- Priority-Based Organization - Every issue has a priority level (low, medium, high, critical) so you can focus on what matters most.
- Suggested Prompts - Each issue can carry an AI-generated
suggestedPromptwith specific fix instructions that is passed directly to the workflow run when the issue is executed. - Work Chain Execution - Group issues together and execute them sequentially, with each issue resolved in order before the next begins.
- Automatic PR Creation - When an issue run completes, a pull request is created on the configured GitHub repository.
- Real-Time Tracking - Issue statuses update in real time via reactive queries, so you always see the current state of every issue.
- Session Progress Tracking - Issue sessions track progress via
currentIterationandmaxIterationscounters, giving you visibility into how far through the scanning process the agent has progressed.
Issue Data Fields
| Field | Type | Description |
|---|---|---|
title | string (required) | Short summary of the issue |
description | string (required) | Detailed explanation of the problem or task |
status | enum | Current lifecycle state: new, running, completed, failed |
priority | enum | Importance level: low, medium, high, critical |
suggestedPrompt | string (optional) | AI-generated or user-provided fix instructions used as the run prompt when executing this issue |
runId | ID (optional) | Reference to the linked workflow run |
sessionId | ID (optional) | Reference to the issue session that discovered this issue |
workChainId | ID (optional) | Reference to the work chain this issue belongs to |
workChainOrder | number (optional) | Position of this issue within its work chain |