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 project (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). An audit never files issues on its own.

What an issue holds

Field	What it is
Title	One line on what needs doing.
Body	The what and why, in Markdown. An agent that picks up the issue reads it as written.
Project	The project it belongs to. Every issue has one.
Repo	The 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.
Priority	P0 Urgent, P1 High, P2 Normal (the default) or P3 Low.
Status	Where it is in its lifecycle (below).
Assignee	Who it's assigned to.
Labels	Up to 20 short tags, using lowercase letters, digits, - and _, up to 32 characters each.
Sub-issues	Smaller issues inside it, one level deep and in the same project.

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

Status	What it means
Needs triage	Filed by a machine and not yet reviewed. Accept it onto the worklist or drop it.
Open	On the worklist, not yet marked in progress.
In progress	Someone holds a claim on this and is working it.
Blocked	Parked on something else. It stays on the worklist but nothing is moving.
Done	Closed as done.
Dropped	Closed 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.

Finding your issues

• Issues in the rail lists every issue you can see at the level you're at, under 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.
• Triage holds what is waiting on a human verdict. Needs triage is issues a machine filed. Came back is closed issues a machine has found again since. A re-find never reopens an issue on its own: that call is yours.
• My work is the issues assigned to you, in every project 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:

• New issue on the Issues page, or New › Issue in the top bar. You pick the project, and optionally a repo and a priority.
• From findings, on a project's Code health page (below).
• From an agent, with the MCP server's file_issue tool, which takes the project's slug. See the MCP server.

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

From findings

On a project's Code health page, select findings and choose File as issue. Pick One issue for all of them, or One issue per finding. You can also file a single finding from its own page. The issues are filed in the project you're in.

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, project, repo or priority. Status has its own menu at the top of the issue. Changing the Project moves the issue: you need a role where it is now and where it's going, and the destination must be a project, not an Area or a Space.

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.

A mission can take an issue as its subject: choose it under Linked issue (optional) when you start the mission, and the issue is claimed for that mission. Its pull request closes the issue the same way when it merges.

Who can see an issue

Members and Admins can see issues by default. Viewers can't. 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, Projects and the Inbox.
• Findings: what audits find, and how to triage it.
• Missions: have Hyrax plan and carry out the work, ending in a pull request.