Self-describing issues
A self-describing issue carries enough context — goal, constraints, acceptance criteria, and links — for an agent to pick it up and complete it without further instruction.
A self-describing issue is written so that an agent can pick it up cold — no chat history, no clarifying conversation — and know exactly what to do, what the boundaries are, and when it is done.
Why self-description matters
AI agents have no persistent memory between sessions. When the agent opens an issue, the file is the entire briefing. If the goal is vague, the agent will either stall or make assumptions that may not match your intent.
A well-written issue is also durable: you can pause work, come back a week later, and both you and the agent can pick up exactly where things left off. It doubles as a decision log — acceptance criteria that are checked off show exactly what was verified before the task closed.
Self-describing issues are the difference between a desk that runs unattended overnight and one that emails you every thirty minutes asking for clarification.
Five elements of a self-describing issue
- 01Goal — one or two sentences stating the desired outcome, not the method.
- 02Context — relevant background the agent cannot infer from entity files alone (why now, what changed, related prior decisions).
- 03Constraints — hard limits the agent must not breach (risk bounds, holding-period rules, venue restrictions, cost budgets).
- 04Links — explicit references to entity files, prior issues, snapshots, or research notes the agent should read.
- 05Acceptance — a checklist the agent uses to verify it has finished; each item should be independently checkable.
Full self-describing issue example
---
id: 042
title: Initiate a starter position in META
status: open
priority: normal
symbols: [META]
opened: 2026-07-05
assigned_to: agent
context_files:
- entities/META.md
- research/social-media-q2-review.md
- snapshots/2026-07-04.json
---
## Goal
Open a 1 % NAV starter position in META ahead of Q2 earnings on
2026-07-30, using a limit order at or below the VWAP of the prior
session.
## Context
The desk has no current META exposure. The entity file (entities/META.md)
contains the thesis updated 2026-07-01. The Q2 review note
(research/social-media-q2-review.md) covers the advertising market
context. Yesterday's snapshot shows USD cash available: 48,320.
## Constraints
- Maximum order size: 1 % of portfolio NAV at time of submission.
- Limit price: do not pay more than prior-session VWAP + 0.10 USD.
- Do not submit if the 14-day ATR for META exceeds 8 USD (elevated
vol regime — escalate to review instead).
- Use venue alpaca-live only.
## Links
- Entity: entities/META.md
- Research: research/social-media-q2-review.md
- Prior snapshot: snapshots/2026-07-04.json
## Acceptance
- [ ] ATR check passed (ATR <= 8 USD).
- [ ] Order drafted in orders/proposed/ with correct size and limit.
- [ ] Order reviewed and status updated to approved.
- [ ] Fill recorded in inbox/ and entities/META.md updated with
entry price and position note.Frontmatter fields for agent context
The context_files array in the frontmatter is an explicit reading list. The agent loads these files before starting work, so it does not have to guess which entity, snapshot, or research note is relevant.
assigned_to: agent signals that the issue is ready for automated pickup. Change it to assigned_to: human when you need to review before the agent proceeds.
priority influences the order in which the agent processes open issues when multiple are queued. Supported values are critical, high, normal, and low.
Write constraints as negatives
Constraints are most useful when phrased as things the agent must NOT do. Positive instructions belong in the Goal. Constraints are guardrails: 'do not exceed', 'avoid', 'only use', 'escalate if'. The agent treats a violated constraint as a reason to move to blocked status and surface the issue to you.
Acceptance items must be independently checkable
Each acceptance item should be something the agent can verify with a concrete check — a file exists, a field has a specific value, a numeric condition holds. Vague items like 'position looks right' give the agent no signal for when it is done and can lead to premature or missed completion.
Templates speed up issue creation
Store reusable issue skeletons in research/templates/ and reference them in your schedules/ files with issue_template. Qoc instantiates the template with the current date and snapshot path filled in automatically on each run.