Findings & Code health
A finding is something Hyrax saw in your code that deserves attention: a SQL injection in a request handler, a missing index, a flaky test. Audits produce findings, and Code health is where you read them and decide what each one deserves.
A finding is evidence, not a task. When you decide to act on one, you either fix it right away or file it as an issue in a project, where the work gets an assignee and a status. Findings and issues stay linked, so a finding shows when an issue already tracks it.
Three kinds, one model
Hyrax reports three kinds of result. All share the same fields, lifecycle, and HYRAX-N reference space; the kind changes the recommended action.
| Kind | What it represents | The action |
|---|---|---|
| Finding | A concrete problem worth fixing | Fix it, or file it as an issue |
| Advisory | Process, CI, or architectural guidance with no single code change | Acknowledge it, mark it addressed, or file it as an issue |
| Suggestion | An architectural idea worth considering | Consider it, or file it as an issue |
A finding points at code you can change, so it offers a one-click Fix. An advisory is guidance that doesn't map to a single pull request (a CI gate to add, a dependency policy to adopt, an architectural direction to set), so it has no Fix. Audits produce suggestions only for workspaces where Hyrax support has turned them on; suggestions have no Fix either, and any you have stay readable and close on their own like any other result.
On Code health, the Findings · Suggestions · Advisories switch shows one kind at a time.
Code health
Code health is in the rail inside every project, and at the workspace. Inside a project, it lists the findings in the repositories that project works on; at the workspace, the findings in every repository you can see. A repository's own Overview shows its Top findings, with a link to All in Code health.
It opens on what needs a decision: open Critical and High findings that no issue tracks, nobody keeps, and no fix is working on. Each of those conditions shows as a filter chip you can remove, and Show the rest of the findings widens the list to everything open. When nothing needs a decision, the page says No critical or high findings need a decision.
Filters narrow the list further: state (Open or Resolved), Fixed by a Hyrax PR, Severity, Tracked, Kept, Fix running, Easy wins only, Repository, and Domain. When Hyrax's fix attempts on some findings ran out, a callout above the list says so; Review shows them.
Run a new audit from the Run audit button beside the page title. See Running audits.
Stable references
Every result gets a sequential, per-workspace reference rendered as HYRAX-N: HYRAX-1, HYRAX-2, and so on. It never changes across re-audits, fix PRs, or status changes. Quote a ref in a commit message, an issue, or a chat with your AI coding tool, and anyone on the team can paste it back into Hyrax to pull up the exact finding. (Issues have their own references, ISS-N.)
What's in a finding
- Title: one sentence stating what was found.
- Description: what's there, why it matters, and the product impact.
- Locations: one or more references to where it lives: a file path (relative to the repo root), an optional symbol (function, class, or method), and a line range. Paths live in the locations, not the prose, so tooling can jump straight to the right lines.
- Severity: Critical, High, Medium, or Low (see below).
- Domain: one of seven (see below).
- Kind: finding, advisory, or suggestion.
A finding records its title, description, severity, domain, and location references (path + symbol + line range), not the source code at those lines. Hyrax does not keep your source files long-term. See Security.
Severity
A single axis with four values. The app shows the name; the REST API and MCP server carry the matching priority, P0 through P3.
| Severity | Priority | Meaning | When to act |
|---|---|---|---|
| Critical | P0 | Active risk or top-leverage opportunity | Now |
| High | P1 | Significant defect or worthwhile change | This sprint or cycle |
| Medium | P2 | Real, not urgent | When convenient |
| Low | P3 | Minor: nits, cosmetic, deferred | As cleanup |
Domains
Every finding belongs to one of seven domains, so you can work through one area of concern at a time with the Domain filter.
| Domain | Covers |
|---|---|
| Security | Vulnerabilities, hardening, authentication and authorization, privacy, compliance gaps |
| Code Quality | Code structure, cleanup and dead code, refactoring, modernizing deprecated APIs, stalled migrations, AI-integration hygiene |
| Reliability | Performance hot paths, concurrency, resilience, wasted resources and spend |
| Data & APIs | API layering and contracts, schema and database design, input validation, versioning, data isolation between your own customers |
| Testing | Test coverage and test quality |
| DevOps | Dependencies, configuration, docs drift, observability and logging, monorepo health, bundle size, API documentation, feature flags, deployment |
| UX | Accessibility, internationalization, error experience, frontend performance, state management, unhandled states and inconsistent behavior across similar features |
A finding's page also shows the audit category that produced it (Security, Correctness, Maintainability, Performance, Architecture, or Operations). The categories describe how the audit is organized; see Audit tools & languages.
Lifecycle
A finding is either open (freshly detected, or being worked while a fix runs) or closed, with a reason of Fixed, Completed, Dismissed, or No longer reported.
Fixing
Starting a fix does not close the finding. It closes as fixed only when the resulting pull request is merged. Until then it stays open, so your list reflects reality: if the fix PR is abandoned or rejected, the finding is still there waiting.
While a fix is running or its pull request is open, the finding counts as Fix running, so it leaves Code health's default list: the PR is now the deliverable, and merging is your call. If you close the PR without merging, the finding is back on the list automatically; if you merge, it closes as fixed and shows under Resolved with Fixed by a Hyrax PR.
Advisories and suggestions have no Fix. Once your team has acted on one, mark it addressed instead (see below).
Filing as an issue
Inside a project, select one or more findings on Code health and click File as issue, or use File as issue on a finding's own page. With several selected, choose One issue for all of them or One issue per finding. The issue lands in that project; see Issues.
From then on the finding shows Tracked · ISS-N, with the project's name, wherever it appears. A finding an open issue already tracks isn't filed twice. Filing is offered only inside a project, so the issue has a project to land in; any kind of result can be filed.
Keeping
Keep… is for a finding that is real but not for now. You own it, you can leave a note (Why not now?), and you pick a look-again date, up to a year out (30 days unless you choose otherwise). A kept finding stays open, leaves Code health's default list, and shows in My work under Kept by you. On the look-again date it needs a decision again. A teammate can take it over, and Un-keep clears it.
A kept finding never closes on its own: the automatic closes below skip it, because keeping it is a person's decision that it is real.
Acknowledging
Acknowledge signals "we've seen this and registered it" without closing it. The finding stays open and carries an acknowledged marker so the team knows it isn't unseen. It's most useful for advisories you intend to act on later. It doesn't pause the automatic closes described below: an acknowledged finding that stops being reported still closes as No longer reported.
Marking addressed
When you resolve something outside a Hyrax pull request (you fixed it by hand, adopted the recommended CI gate, or decided the guidance is now satisfied), mark it addressed. It closes with the reason completed, and you can optionally attach a link (to the commit or PR that did it) and a short note. This is available on every kind, and it's distinct from dismissing: marking addressed means "done", dismissing means "not doing this".
Publishing to a ticket
Publish to ticket creates a tracking ticket in your connected integration (Linear) for any kind of result. This needs a ticket integration configured for the repository; without one, the action is unavailable.
Linking an existing ticket
If your team already filed this in your own tracker, link an existing ticket and paste the URL. The link shows on the finding so anyone looking at it can jump straight to your ticket. (A linked ticket is separate from the Tracked filter, which counts Hyrax issues.)
Two things are worth knowing:
- A link stops Hyrax from filing its own ticket for that finding. That's the point of it: you already have one, and a second would just be noise. Publish to ticket becomes a no-op while the link is in place, and so does the automatic publish that a Fix would otherwise trigger. Unlink to undo that; Hyrax can file again immediately afterwards.
- A linked ticket gets no automatic updates from Hyrax. Hyrax records the URL and renders it, nothing more. It can't post to a ticket it doesn't own, so when a fix pull request opens, the PR link is not attached to your linked ticket (it is, for tickets Hyrax filed itself).
Any URL works as long as it's https: the tracker is your choice, and it doesn't have to be the integration configured for the repo. Pasting a new URL replaces the old one. Linking doesn't close or otherwise change the finding. Reopening a closed finding does not clear a link.
Dismissing
You can dismiss a finding you don't intend to act on, with a category that tells Hyrax how to treat it on the next audit:
| Dismiss category | Behavior on re-discovery |
|---|---|
| False positive, Won't fix, Out of scope | Stays closed: your decision sticks even if the audit re-detects the same thing |
| Stale, No longer found, Other | Can reappear: if the underlying problem is genuinely found again, a fresh incarnation surfaces |
Re-checking
Re-check findings (Revalidate) checks what's open against the repository's current code, of every kind. The ones it finds fixed close and move to Resolved; the rest stay open. It never adds anything new. Start it from Code health or from the audit menu on a repository's page.
Closing automatically
Findings that stop being reported also close on their own, in two independent ways, both with the reason No longer reported. The wording is deliberate: closing this way means nothing re-reported the finding, not that Hyrax searched and confirmed it was gone. In the second case below, no audit may have run at all. This applies to every kind:
- Not re-found by several Full audits. When, by default, three Full audits since a finding was last seen genuinely re-checked the area that produced it and none detected it again, Hyrax closes it, usually because the problem disappeared in the course of normal work. The audits don't need to be consecutive. Standard audits don't count, and neither do runs that failed or skipped that part of the check.
- Not re-confirmed for about 30 days. A finding that no audit of any depth has re-confirmed in roughly 30 days also closes on its own, including when no audits ran at all in that window.
A finding someone keeps is left alone by both. A finding with a fix in flight (a running fix or an open fix pull request) is left alone by the 30-day close only. Acknowledging a finding does not protect it.
If Hyrax got it wrong, reopen it, and if a later audit detects the same problem again, a fresh incarnation surfaces automatically.
Reopening
A closed finding can be reopened at any time: for example, if a fix turns out incomplete, an addressed problem regresses, or a dismissed one becomes relevant again. It returns to open, and any acknowledged, addressed, or kept markers are cleared. A finding you marked addressed will also resurface as a fresh incarnation if a later audit detects the same thing again.
Deduplication and re-discovery
Re-running an audit does not start your list over. Hyrax merges new results into your existing findings rather than replacing them, so the decisions you've already made (dismissals, keeps, tracking issues, ticket links) are respected, and you never see the same problem twice.
Because of that merge, the count on a repo is cumulative: it accumulates across runs rather than being replaced by the latest one. Each audit is a deep sampling pass. A re-run re-confirms most of what's already open and adds some genuinely new findings, so the per-run "new" number is normally smaller than the repo total, and two runs of the same depth won't match exactly. A run's page shows new this run and re-confirmed for that run, while Code health shows what's open across all runs, so a rise from one run to the next reads as accumulation, not a re-measurement that changed.
Working through findings
- Start from the default list. It holds only open Critical and High findings nobody has decided on yet.
- Decide each one: fix it, file it as an issue, keep it for later, or dismiss it.
- Filter by Domain to work through one area of concern at a time, then use Show the rest of the findings for Medium and Low.