Issues
Issues are the desk's task queue — markdown files in issues/ that represent research questions, trade ideas, or operational tasks the agent is working through.
An issue is a task or question the desk is actively working — stored as a single markdown file in issues/, with a status field the agent updates as it makes progress.
What is an issue
Issues are how you assign work to the desk. A research question, a rebalancing task, a risk review, a data-quality check — any discrete piece of work becomes an issue file.
The file contains everything the agent needs to pick up the task without you being present: a goal, any constraints, links to relevant entities, and acceptance criteria. When the agent finishes, it updates status to done and writes a summary back into the file.
You can also open issues via the CLI or let the runtime surface them automatically from inbox alerts or schedule triggers.
Example issue file
---
id: 001
title: Rebalance tech sleeve to target weights
status: open
priority: high
symbols: [AAPL, MSFT, NVDA, GOOGL]
opened: 2026-07-05
assigned_to: agent
---
## Goal
Bring the tech sleeve back to target weights after yesterday's NVDA
earnings run-up pushed it 4 % over the 30 % cap.
## Constraints
- Do not sell more than 2 % of average daily volume per name.
- Avoid realising short-term gains if holding period < 30 days.
## Acceptance
- [ ] Proposed orders cover the delta to target weights.
- [ ] Orders reviewed and approved.
- [ ] Executed fills recorded and entities updated.Issue status lifecycle
| Status | Meaning |
|---|---|
draft | Being written; agent will not pick it up yet. |
open | Ready for the agent to work on the next run. |
in-progress | Agent is actively working the issue in the current run. |
blocked | Agent cannot continue without human input or an external event. |
review | Agent has proposed orders or decisions that require your approval. |
done | All acceptance criteria met; issue closed. |
cancelled | No longer relevant; archived without completion. |
Opening an issue
- 1
Via the CLI
Run
qoc run 'rebalance tech sleeve'and Qoc will create a structured issue file inissues/, then immediately assign it to the agent. - 2
By hand
Create a markdown file in
issues/with the required frontmatter (id,title,status: open). The agent picks it up on the next scheduled run. - 3
From an inbox alert
Configure
on_alert: open_issuein a schedule file. When a matching alert arrives ininbox/, Qoc automatically creates a linked issue. - 4
From a schedule
Add an
issue_templatepath to a schedule file. Qoc instantiates the template as a fresh issue on each scheduled run.
Check issue status
Run qoc status from the workspace directory to see all open and in-progress issues, their assigned agent, and last-updated timestamp.
Issues are append-only in practice
The agent appends progress notes and updates the status field but does not delete or overwrite your original goal and constraints. The full history of what was tried and decided stays in the file.