Work Chains

Learn how to batch-execute multiple issues in sequence using work chains -- create chains, use suggestedPrompts for precision execution, track progress, and manage sequential issue resolution.

6 min read

issueswork-chainsbatch-execution

Work chains are CodeCourier’s batch execution system for issues. Instead of running issues one at a time, you can group multiple issues into a work chain and execute them sequentially - each issue is resolved in order, with the next issue starting only after the previous one completes. This is ideal for related fixes that should be applied in a specific sequence, such as a series of security patches or a coordinated set of refactoring tasks.

What are Work Chains?

A work chain is an ordered list of issues linked to a single workflow and execution configuration. When you start a chain, CodeCourier processes each issue sequentially:

The first issue is picked up and a workflow run is launched
The run executes in a sandbox, applying code changes and creating a PR
Once the run completes, the next issue in the chain is processed
This continues until all issues are resolved or a failure occurs

Sequential Execution

Work chains execute issues one at a time in order. This ensures that code changes from earlier issues are committed before later issues begin, preventing merge conflicts and ensuring each fix builds on the previous one.

Work Chains vs. Sprint Chains

Work chains and sprint chains are distinct concepts in CodeCourier, though they share the idea of sequential execution:

	Work Chains	Sprint Chains
Input	Issues (discovered or manual)	Workflow runs from a sprint plan
Prompt source	Each issue’s `suggestedPrompt` or `description`	Sprint-level prompt and planning context
Use case	Batch-fixing discovered bugs or improvements	Executing a planned multi-feature sprint
PR strategy	One PR per issue	Configurable per sprint

Use work chains when you have a set of discrete, independently-fixable issues to resolve. Use sprint chains when you have a planned sequence of feature builds.

How Prompts are Selected

The prompt passed to each workflow run in a chain is determined by the issue’s suggestedPrompt field. This field is typically populated by the AI Issue Agent during scanning - it contains specific, targeted fix instructions written for that exact issue rather than a generic description.

The resolution order is:

If suggestedPrompt is set and non-empty, it is used as the run prompt. This gives the workflow run precise, AI-crafted instructions tailored to the specific fix required.
If suggestedPrompt is not set, the issue’s description is used as a fallback.

Why suggestedPrompt Matters

Issues discovered by an Issue Session carry a suggestedPrompt that was written by the same AI agent that identified the problem - it knows exactly what needs fixing and how. This is why AI-discovered issues in a work chain tend to produce higher-quality workflow runs than manually created issues with only a description. When creating issues manually for use in work chains, take the time to write a precise suggestedPrompt.

Creating a Work Chain

To create a work chain from the Issues page:

Select the issues you want to include using the checkboxes on the issues list.
Click the Create Work Chain button.
Configure the chain settings:
- Workflow - Select the workflow blueprint for all issues in the chain
- GitHub Repository URL (optional) - Target repository for PRs
- Branch Name (optional) - Base branch for the work
Submit to create the chain. The issues are assigned a workChainId and workChainOrder reflecting their position in the sequence.

Issue Order Matters

Arrange issues in the order you want them resolved. If issue B depends on changes from issue A, make sure issue A comes first in the chain. You can reorder issues during chain creation.

How Execution Works

Once a work chain is started, execution follows this pattern for each issue:

The issue’s suggestedPrompt (or description if no prompt is set) is used as the run prompt.
A workflow run is launched using the chain’s configured workflow, GitHub URL, and branch.
The issue is linked to the run and its status changes to running.
When the run completes, the issue status is updated to completed or failed.
If the run succeeded, the chain advances to the next issue. If it failed, the chain pauses for review.

Chain Status Tracking

Work chains have their own lifecycle status:

Status	Description
`pending`	The chain has been created but execution has not started.
`running`	One of the issues in the chain is currently being processed.
`completed`	All issues in the chain have been resolved successfully.
`failed`	An issue in the chain failed. The chain is paused at the failed issue.
`cancelled`	The chain was manually cancelled by the user.

Work Chain Fields

Field	Type	Description
`title`	string	Display name for the work chain
`description`	string (optional)	Description of the chain’s purpose
`issueIds`	array of IDs	Ordered list of issues in the chain
`workflowId`	ID	The workflow blueprint used for all runs
`githubRepoUrl`	string (optional)	Target GitHub repository URL
`branchName`	string (optional)	Base branch for code changes
`status`	enum	Current chain status: `pending`, `running`, `completed`, `failed`, `cancelled`

Monitoring Chain Progress

Work chain progress is displayed in real time on the Issues page. You can see:

The overall chain status and completion percentage
Which issue is currently being processed
Individual issue statuses within the chain
Links to the workflow runs created for each issue
Pull requests generated from completed issues

If an issue in the chain fails, you can review the failure, edit the issue’s suggested prompt, and retry the chain from the failed issue.

Next Steps

Issues Overview

Return to the Issues overview for a high-level understanding.

Answering Sessions

Refine questions and assumptions from issue sessions before running chains.

Monitoring

Learn about monitoring workflow runs and tracking execution.

Issue Sessions

Discover issues automatically with AI-powered scanning sessions.