# Issue

URL: /business/nouns/issue · Id: `noun:issue`

> An Issue is a Task reporting a problem or request, such as a bug or a feature request, with a reporter and a triage step.

An Issue is a [Task](/business/nouns/task) reporting a problem or request, such as a bug or a feature request, with a reporter and a triage step.

## Properties
| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `kind` | `string` | No | One of `bug`, `request`, or `question`. |
| `severity` | `string` | No | Set by triage; a vulnerability takes `critical`, `high`, `medium` or `low`, which sets `due`. An Incident keeps its own scale. |
| `advisory` | `string` | No | For a vulnerability: the public advisory it matches, with the affected package and range. |

<details>
<summary>Inherited from [Task](/business/nouns/task): 3 properties</summary>

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `due` | `datetime` | No | When the Task is due. |
| `priority` | `integer` | No | Its rank in the inbox, highest first. |
| `recurrence` | `string` | No | The schedule a recurring duty repeats on. |

</details>

<details>
<summary>Inherited from [Action](/business/nouns/action): 11 properties</summary>

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | `string` | Yes | One of `pending`, `done`, `failed`, `canceled`, or `refused`. |
| `reason` | `string` | No | Why a pending Action waits: `queued`, `running`, `retrying`, `awaitingWorker`, `awaitingInput`, `awaitingSource`, `awaitingAction`, or `awaitingTime`. |
| `mode` | `string` | Yes | How the caller invoked it: `try`, `send`, or `do`. |
| `by` | [Worker](/business/nouns/worker) | No | The Worker that performed it. |
| `for` | [Party](/business/nouns/party) | No | The Party it was done on behalf of. |
| `via` | `string` | No | The Interface or request it arrived through. |
| `on` | `string` | No | The Action or Event that caused it, such as the failed attempt a retry follows. |
| `thing` | `string` | No | The record, at the Version the Action was decided against. |
| `input` | `json` | No | The input it was called with. |
| `createdAt` | `datetime` | No | When it was called. |
| `reserved` | `money` | No | The most this Action may cost, held against its Limits from the check until it settles, billed misses included. |

</details>

## Object
```json
{
  "$id": "https://api.sb/patentpad.com/issues/issue_1",
  "$type": "Issue",
  "status": "pending",
  "reason": "queued",
  "mode": "try",
  "by": "worker_1",
  "for": "party_1",
  "via": "API",
  "on": "Invoice.overdue",
  "thing": "invoice_1@v3",
  "input": {},
  "createdAt": "2026-10-22T12:00:00Z",
  "reserved": {
    "amount": 499,
    "currency": "USD"
  },
  "due": "2026-10-22T12:00:00Z",
  "priority": 1,
  "recurrence": "Weekly on Friday",
  "kind": "bug",
  "severity": "critical",
  "advisory": "GHSA-xxxx-xxxx-xxxx"
}
```

## Relationships
- <a id="rel-addresses"></a>An Issue **addresses** many [Problems](/business/nouns/problem): an Issue addresses the [Problems](/business/nouns/problem) its [Evidence](/business/nouns/evidence) came from, so the [Customers](/business/nouns/customer) behind that Evidence hear when it ships. `addresses`, inverse [`addressedBy`](/business/nouns/problem#rel-addressed-by).
- <a id="rel-conversations"></a>An Issue **has** many [Conversations](/business/nouns/conversation): the Issue or [Incident](/business/nouns/incident) a [Conversation](/business/nouns/conversation) reports; resolving it answers every linked Conversation. `conversations`, inverse [`reports`](/business/nouns/conversation#rel-reports).
- <a id="rel-reports"></a>An Issue **reports** one [Thing](/business/nouns/thing): an Issue is about one [Thing](/business/nouns/thing), such as a [Product](/business/nouns/product), a [Page](/business/nouns/page), or an [Order](/business/nouns/order). `reports`, inverse [`issues`](/business/nouns/thing#rel-issues).
- <a id="rel-resolved-by"></a>An Issue **is resolved by** many [Changes](/business/nouns/change): a [Change](/business/nouns/change) names the Issues it fixes; each resolves when the last open Change naming it reaches all traffic. `resolvedBy`, inverse [`resolves`](/business/nouns/change#rel-resolves).

## Verbs
| Verb | Description | Subject | Event | Class |
| --- | --- | --- | --- | --- |
| [Issue.estimate](/business/nouns/issue/estimate) | Estimate records the effort an Issue needs, in days, so a week holds only what fits. | [Engineering Lead](/agents/engineering/engineering-lead) | [`Issue.estimated`](/business/events/Issue.estimated) | Two-way: `try`, `send`, `do` |
| [Issue.reopen](/business/nouns/issue/reopen) | Reopen returns a resolved Issue to its owning Role when the fix does not hold. | [Product Lead](/agents/product/product-lead) | [`Issue.reopened`](/business/events/Issue.reopened) | None. |
| [Issue.resolve](/business/nouns/issue/resolve) | Resolve closes an Issue with its fix recorded and tells every Customer who reported it. | [Product Lead](/agents/product/product-lead) | [`Issue.resolved`](/business/events/Issue.resolved) | None. |
| [Issue.schedule](/business/nouns/issue/schedule) | Schedule commits an Issue to a week of work and records each scope change after the week starts. | [Product Lead](/agents/product/product-lead) | [`Issue.scheduled`](/business/events/Issue.scheduled) | Two-way: `try`, `send`, `do` |
| [Issue.triage](/business/nouns/issue/triage) | Triage sets an Issue’s severity and owning Role from its content and the Customer it affects. | [Product Lead](/agents/product/product-lead) | [`Issue.triaged`](/business/events/Issue.triaged) | None. |
| <a id="create"></a>[Issue.create](/business/nouns/issue/create) | Creates an Issue. Inherited from [Noun](/business/nouns/noun). | None. | `Issue.created` | Two-way: `try`, `send`, `do` |
| <a id="get"></a>[Issue.get](/business/nouns/issue/get) | Returns one Issue by id. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="list"></a>[Issue.list](/business/nouns/issue/list) | Returns Issues, newest first, one page at a time. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="update"></a>[Issue.update](/business/nouns/issue/update) | Changes the given properties of an Issue. Inherited from [Noun](/business/nouns/noun). | None. | `Issue.updated` | Two-way: `try`, `send`, `do` |
| <a id="delete"></a>[Issue.delete](/business/nouns/issue/delete) | Deletes an Issue; its history is kept. Inherited from [Noun](/business/nouns/noun). | None. | `Issue.deleted` | One-way: `send`, `do` |

## Permissions
Which Access level may call each Verb. One-way Verbs wait their delay window.

| Operation | `owner` | `admin` | `member` | `viewer` |
| --- | --- | --- | --- | --- |
| `Issue.create` | Yes | Yes | Yes | No |
| `Issue.get` | Yes | Yes | Yes | Yes |
| `Issue.list` | Yes | Yes | Yes | Yes |
| `Issue.update` | Yes | Yes | Yes | No |
| `Issue.delete` | Yes | Yes | Yes | No |
| `Issue.estimate` | Yes | Yes | Yes | No |
| `Issue.reopen` | Yes | Yes | Yes | No |
| `Issue.resolve` | Yes | Yes | Yes | No |
| `Issue.schedule` | Yes | Yes | Yes | No |
| `Issue.triage` | Yes | Yes | Yes | No |

## Call it

**Ask**

```text
Triage the latest issue.
```

**API**

```bash
curl -X POST https://api.sb/ledgerlark.com/issues/issue_1/triage \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY"
```

```json
{
  "api": "https://api.sb/ledgerlark.com",
  "issue": {
    "$id": "https://api.sb/ledgerlark.com/issues/issue_1",
    "$type": "Issue",
    "status": "pending",
    "mode": "try"
  },
  "action": {
    "$id": "https://api.sb/ledgerlark.com/actions/action_1",
    "operation": "Issue.triage",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/ledgerlark.com/actions/action_1"
  }
}
```

**SDK**

```ts
import { $ } from 'startup-builder'

const issue = await $.Issue.triage({ issue: 'issue_1' })
```

**CLI**

```bash
npx startup-builder do Issue.triage --json '{"issue":"issue_1"}'
```

**MCP**

```json
{
  "name": "do",
  "arguments": {
    "code": "return await $.Issue.triage({ issue: 'issue_1' })"
  }
}
```

## Example
A translator reports that the drafting [Agent](/business/nouns/agent) drops accents from proper names. The Issue records the reporter, a sample document, and its triage outcome: bug.