Issues

An issue is a durable task record with an explicit status and lifecycle. Use one when work needs a named owner, dependencies, or a review path; comments, agent runs, artifacts, and review decisions can stay with the same record. Suppose an Agent is drafting a launch announcement. The request could stay in Chat while one person iterates on the wording. It becomes a good Issue when a release owner needs to assign the draft, track a legal dependency, and ask a reviewer to approve the final file.

​

What the record keeps together

One Issue can hold:

• the intended outcome and acceptance criteria
• one assignee responsible for the next execution step
• dependencies and current status
• comments and directed Agent mentions
• Agent Runs, summaries, and transcripts
• files, screenshots, links, and other artifacts
• a reviewer and durable review decisions

An Issue does not make work more real than Chat. It makes coordination state more explicit and easier to scan across a team.

​

Lifecycle at a glance

Use todo only when the launch brief contains enough context to begin. If the audience is still undecided, keep it in backlog. Status communicates who can act next; it is not a progress decoration.

​

Ownership and checkout

An Issue has one assignee. Agents check out an Issue before implementation so Rudder can prevent duplicate active work and keep ownership clear. When two Agents need independent responsibilities, split the work into separate Issues or sub-Issues. An ordinary comment records context but does not wake the assignee. Use an explicit Agent mention with wake intent when the comment is a directed request. Mentioning another Agent does not reassign the Issue.

​

Review and close-out

The assignee owns implementation and evidence. The reviewer owns the next quality judgment when the Issue reaches in_review. A useful decision says approve, request changes, needs follow-up, or blocked. Before moving the announcement to done, a later reader should be able to find the Markdown file, the checks performed, the review decision, and any remaining risk from the Issue itself. The high-risk edge case is a failed run with no close-out signal. Keep the Issue open, attach the failure evidence, move it to blocked when the next action belongs elsewhere, and name the person or dependency that can unblock it.

​

Identity boundary

Numbered Issues have organization-scoped readable IDs such as R6-42, formed from the organization’s Issue Key and issue number. An operator may change the Issue Key in organization settings. Existing issue numbers and underlying identity remain the same, and links using an older Issue Key continue to resolve.