---
name: platform-issues
description: "Keep the issue that records one outcome: open or continue it, add evidence, ask a person, hand a pull request over for review, and close it. Use whenever a step opens, reads or changes an issue."
metadata:
  min-cli-version: "0.92.0"
  next: ""
---

# Platform: issues

An issue is the record of one outcome someone asked for: what was reported, the evidence, the questions asked and answered, and the pull requests. It belongs to the project, not a runtime, and keeps the Task that works on it for its whole life, after a turn ends or the sandbox expires. Every step that keeps an issue does it through the five actions below.

## The commands

Inside a Task, `get` and `update` act on the Task's own issue; outside one, name the issue (`get <issue-id>`, `update <issue-id>`). `comment` always names the issue.

- `introspection issues get` reads the issue. `--include attachments` adds its evidence, each item with its `kind` and `id`; `--include comments` adds its comments, newest first; `--include members` adds its assignee, reviewer and followers.
- `introspection issues create --title "..." --description "..." --priority <low|medium|high|urgent>` opens it. It starts open. Inside a Task it attaches to that Task; outside one it opens with no Task.
- `introspection issues update` applies the fields given; the last write wins: `--status <open|waiting|closed|cancelled>`, `--title`, `--description`, `--priority`, `--assignee <member-id>`, `--reviewer <member-id>`, `--follower <member-id>` (repeatable), and `--no-assignee`, `--no-reviewer`, `--no-followers`.
- `--links`, `--files`, `--events` and `--spans` take a JSON list and add its items to the issue's evidence; an item the issue already holds is skipped. The items: `{"url":"...","title":"..."}`, `{"file_id":"<id>","name":"..."}`, `{"event_id":"<id>"}`, `{"trace_id":"<32 hex>","span_id":"<16 hex>"}`. `--detach <attachment-id>` (repeatable) removes one.
- `introspection issues comment <issue-id> "<markdown>"` posts a comment. It doesn't change the issue, can't be edited or deleted, and may not appear on a read made straight after: don't post it again because a read doesn't show it yet.
- `introspection issues list --owner project --status open --status waiting` lists the project's Operator issues; `--relation assignee --relation reviewer` narrows it to the ones on you.

Never delete an issue: cancel it.

## 1. Open or continue

Continue the open issue that already covers the same outcome; otherwise create one, with a concise description and an explicit priority. One outcome is one issue.

## 2. Add evidence

Add what the issue rests on as you find it, one call per item or several items of a kind in one list. It adds to what the issue holds, and adding an item again changes nothing, so there is nothing to read first:

```sh
introspection issues update <issue-id> --links '[{"url":"<url>","title":"<title>"}]'
introspection issues update <issue-id> --files '[{"file_id":"<id>","name":"<name>"}]'
introspection issues update <issue-id> --events '[{"event_id":"<id>"}]'
introspection issues update <issue-id> --spans '[{"trace_id":"<32 hex>","span_id":"<16 hex>"}]'
```

To remove an item, read its `id` from the issue's attachments and detach it:

```sh
introspection issues get <issue-id> --include attachments
introspection issues update <issue-id> --detach <attachment-id>
```

Evidence is pull requests and other pages as links, stored files by id, telemetry events by id, and spans as `{trace_id, span_id}`. Never invent an id or attach a saved filter as an event. A reference doesn't preserve the event's content or extend its retention or who can read it: keep durable proof in a file. Deliverables are stored files linked by their file id, since a local path isn't a reference another Task can follow.

## 3. Ask a person

Assign them, set the issue to waiting, and post the question as a comment. Set it back to open as soon as they answer, before you carry on. Ask one thing per comment, and keep the same assignee while the need is the same. There is no separate question to open or resolve: the comment is the question.

Ask in the thread too: assigning someone doesn't message them. A Slack message that directs someone to the issue may link `/p/<project-slug>/issues/<issue-id>`, the issue's page in the dashboard; an app reply carries no link to it. Then end the turn: never sleep or poll, since a reply resumes the Task.

## 4. Hand a pull request over for review

Add the pull request as a link, set the person who should review it as the reviewer (the project's owner when no one else is named), set the issue to waiting, and ask them in a comment what to review and how to try it. GitHub handles the pull request's own review and merging.

## 5. Close or cancel

Close an issue only when its goal is met and every question it asked is answered or withdrawn, with the outcome and its evidence in the description: two or three plain sentences, a commit as its first seven characters in backticks (`1bbb062`), and no run ids, full shas or statements of what wasn't done. A finished turn or a merged pull request doesn't close it by itself. Reopen closed work only for an explicit reason; a late reply can simply be acknowledged. A closing description reads like this:

> The agent now uses John Doe, Partner, and USD 110/hour, from one shared terms file, on branch `pr/improve-I-4` at `1bbb062`. Case C1 failed before the fix and passes after it; a fresh review accepted the change.

Before cancelling another worker's issue, stop its Task and check it stopped, account for what it was waiting on, and record why. A worker can cancel its own issue as it finishes its turn.

## What it holds

- **Title, description and priority.** The description is the living brief, concise and for a reader who isn't technical: what triggered it, the goal, the evidence, the blockers, the next steps and, once verified, the outcome. Detail goes in linked files or the Task's conversation.
- **Status:** open, waiting (for a person or an external blocker), closed or cancelled, always set explicitly. Assigning someone or commenting doesn't change it. Whether work is running is the Task's status, never the issue's.
- **People:** one assignee, the person whose answer the issue waits on (the project's owner when no expert is known); one reviewer, the person who reviews its result; and followers, who are kept informed. Each is the member id of an active member of the organization.

## Replies

A reply typed in the app arrives as the turn's message, with the issue's id and status, and changes nothing on the issue. Others come as a comment (read with `get --include comments`; each names the `member_id` who posted it) or in the thread. A reply is a contribution, not an answer to the question or an approval of a pull request: resolve only what was answered, record the decision and its basis in the description, then unassign or reassign and set the status the work now has.

A revised review is a new question: say in a comment that the earlier one is withdrawn, attach the new material and ask again. An answer to an old review doesn't approve its replacement.

Feedback on one conversation's spans is an annotation, not a question: `introspection annotations create`. Saving one never answers a question or changes an issue's status.

## Done when

The issue says what the step did: its evidence is attached, its status is set explicitly, and anyone it waits on is assigned and asked. Hand back to the step that kept it.
