Skip to main content

Issues

An issue is a piece of work your team means to do: a bug to fix, a change to make, a decision to take. Issues are how you track work in Hyrax, for people and for agents alike. Every issue lives in a Space (see Organizing work) and has a stable reference like ISS-42, numbered across your whole workspace.

Issues are separate from findings. A finding is what an audit found in your code. It becomes work you track when you file it as an issue (see From findings). Hyrax does not file findings as issues on its own.

What an issue holds​

FieldWhat it is
TitleOne line on what needs doing.
BodyThe what and why, in Markdown. An agent that picks up the issue reads it as written.
SpaceThe Space it belongs to. Every issue has one.
PlanThe Plan it serves, if any. An issue belongs to at most one Plan.
RepoThe repository the work is in. Optional: leave it on no repo for workspace-wide work, like a process change or a decision that has no code yet.
PriorityP0 Urgent, P1 High, P2 Normal (the default) or P3 Low.
StatusWhere it is in its lifecycle (below).
AssigneeWho it's assigned to.
LabelsUp to 20 short tags, using lowercase letters, digits, - and _, up to 32 characters each.

Each issue also keeps an activity trail: who filed it, every edit and status change, notes, linked pull requests and the work started on it.

Status​

StatusWhat it means
Needs triageFiled by a machine and not yet reviewed. Accept it onto the worklist or drop it.
OpenOn the worklist, not yet marked in progress.
In progressSomeone holds a claim on this and is working it.
BlockedParked on something else. It stays on the worklist but nothing is moving.
DoneClosed as done.
DroppedClosed without being done.

An issue you file yourself skips triage and starts as Open. Issues that Hyrax files on its own start in Needs triage, so a person decides whether they're worth doing.

Closing asks for an outcome, Done or Dropped, and an optional reason, which is recorded on the issue. Reopening brings back the same issue: its ref, its history and every link it already had stay attached.

Claims​

A claim says who is working an issue right now, so two people or agents don't start the same work. Claiming an open issue moves it to In progress. A claim is a lease: it lasts until its holder releases it or lets it lapse, and nobody else can take it back in the meantime. The holder can extend or release it from the ⋯ menu at the top of the issue.

Claims are how agents coordinate too. An agent connected over the MCP server can claim an issue before it starts and release it when it's done.

An issue must be on a Plan to be worked. Until it is, neither you nor your AI tools can claim it, extend its claim, move it to In progress or Blocked, assign it to someone or start a mission on it. You can still edit it or close it. To work it, use Work on this on the issue: Just this fix makes a new Plan of this issue alone, and Plan it with more work opens New plan with the issue in. In a workspace with missions, an issue can be claimed only once its Plan has started and is marked as worked outside Hyrax; on any other Plan, Hyrax's missions do the work. The same rule holds for you and your AI tools.

Finding your issues​

  • Issues, a view of Activity in the rail, lists every issue you can see at the level you're at. Where you can also see runs, switch between Runs and Issues at the top of the page. The list is for reading: it has three tabs, Open, Triage and Done. Open groups what's in flight into Stuck, Assigned to you, In progress and Open. Use Filters to narrow the list, or search the issues. To change an issue, open it.
  • Triage holds what is waiting on a human verdict. Needs triage is issues a machine filed; open one to Accept it, or close it as Dropped. Came back is closed issues a machine has found again since. A finding found again never reopens an issue on its own: that call is yours.
  • What to do next, a button on the Plans page, lists the issues that are in no Plan yet, beside the plans Hyrax suggests.
  • My work is the issues assigned to you, in every Space you can see. Open it from For you in the top bar, which also shows your newest assigned issues, your notifications, and anything Waiting on you.

Filing an issue​

You can file an issue in any of these ways:

  • From a Plan's goals. Work starts as a goal (a done-when line) on a Plan. Once the Plan is started, Hyrax files the issues for its goals.
  • From findings, on a Space's Code health page (below).
  • From an agent, with the MCP server's file_issue tool, which takes the Space's slug. An agent can't put an issue on a Plan: Hyrax files a Plan's issues for its goals, so to put work on a Plan the agent adds or corrects one of its goals. See the MCP server.

Filing needs your workspace role to allow managing issues (Members and Admins do by default), and a role in the Space or its Area (workspace admins and the account owner don't need one). Every member belongs to the Default Space, so everyone can file there.

From findings​

In a workspace without Plans, select findings on a Space's Code health page and choose File as issue, or use it on a finding's own page. With several selected, pick One issue per finding, or One issue for all of them. The issues are filed in the Space you're in, on no Plan.

In a workspace with Plans, Code health doesn't file issues: to take findings on, start a draft Plan with New plan on the Plans page.

A finding that an open issue already tracks shows Tracked with that issue's ref, and filing it again points you to the existing issue instead of making a second one.

Moving and editing​

Edit an issue to change its title, body, Space or repo, and its priority while it's on no Plan. Status has its own menu at the top of the issue. Changing the Space moves the issue: you need a role where it is now and where it's going.

Pull requests close issues​

Link a pull request to an issue from its page, by pasting the pull request's own URL. When GitHub reports that pull request merged, Hyrax closes the issue as Done, unless it is already closed, still in triage, blocked, has unmet acceptance criteria, or is still waiting on other linked work. So link the pull request that does the work, not a related one.

Every mission works exactly one issue, and that issue must be on a Plan. The issue is claimed for that mission, and the mission's pull request closes it the same way when it merges.

Who can see an issue​

Members and Admins can see issues by default. Beyond that, what you see follows your repository access: if your access is limited to some repositories, you see the issues on those repositories. An issue with no repo is visible only to people who can see every repository, so if your access is limited, pick a repo when you file.

Where to go next​

  • Organizing work: Areas, Spaces and Plans.
  • Plans: group issues around a goal, and say when the work is done.
  • Findings: what audits find, and how to triage it.
  • Missions: have Hyrax plan and carry out the work, ending in a pull request.