Findings & suggestions

An observation is something Hyrax surfaced for your attention — a SQL injection in a request handler, a missing index, a flaky test, or an architectural idea worth weighing. Observations are the primary unit of work in Hyrax: audits produce them, fixes resolve them, and tickets track them. They come in three kinds, and all share one model.

Three kinds, one model

A finding says "this is wrong, here's where." A suggestion says "this could be better, here's the shape of the change." An advisory says "this is worth doing, but it's bigger than one pull request."

Kind	What it represents	The action
Finding	A concrete problem worth fixing	Fix it
Suggestion	An architectural idea worth considering	Consider it
Advisory	Process, CI, or architectural guidance with no single code change	Acknowledge or mark addressed

Findings and suggestions point at code you can change, so each one 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 button; you acknowledge it, mark it addressed once your team has acted, or publish it to a ticket to track the work elsewhere.

All three share the same fields, lifecycle, and HYRAX-N reference space — the kind shows up as a badge and changes the recommended action. You triage, dismiss, and reopen all of them the same way, but each kind has its own page in a repository: Findings sits in the sidebar's Fix section, while Suggestions and Advisories sit under Improve — so problems to fix and ideas to weigh never crowd each other out.

Stable references

Every observation gets a sequential, per-workspace reference rendered as HYRAX-N — HYRAX-1, HYRAX-2, and so on. This is the identifier you use everywhere: it never changes across re-audits, fix PRs, or status transitions. Quote a ref in a commit message, a Linear ticket, or a chat with your AI coding tool, and anyone on the team can paste it back into Hyrax to pull up the exact observation.

What's in an observation

• 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.
• Priority — P0 through P3 (see below).
• Category — one of six (see below).
• Kind — finding, suggestion, or advisory.

Hyrax stores metadata, not your code

An observation records its title, description, priority, category, 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.

Priority

A single axis with four values, P0 being the most urgent:

Priority	Meaning	When to act
P0	Active risk or top-leverage opportunity	Now
P1	Significant defect or worthwhile change	This sprint or cycle
P2	Real, not urgent	When convenient
P3	Minor — nits, cosmetic, deferred	As cleanup

The interface may show familiar severity labels — "Critical", "High", and so on — but the value is always the P-number.

Categories

Every observation falls into exactly one of six categories, so you can triage one domain at a time.

Category	Covers
Security	Authentication and authorization, injection, secrets, data exposure, supply chain, privacy, compliance gaps
Correctness	Concurrency, edge cases, resilience, accessibility, internationalization, tests, AI-integration hygiene, resource and credit waste
Maintainability	Structure and naming, repeated patterns, dead code, deprecated APIs, error-handling experience, stalled migrations
Performance	Hot paths, memory and CPU, slow queries, frontend rendering, bundle size
Architecture	API contracts and layering, versioning, input-validation boundaries, database and schema design, tenant isolation
Operations	Observability, logging, configuration, deployment, dependencies, feature flags, monorepo health, docs drift

Each category maps to a set of focused audit tools — see Audit tools & languages.

Lifecycle

An observation is either new (actionable — freshly detected, or being worked while a fix job runs) or closed (terminal, with a reason of Fixed, Completed, Dismissed, or No longer reported).

Fixing

Starting a fix does not close the observation. It closes as fixed only when the resulting pull request is merged. Until then it stays open, so your backlog reflects reality — if the fix PR is abandoned or rejected, the observation is still there waiting.

Once Hyrax opens the fix PR, the finding is handed off: the PR is now the deliverable, and merging is your call. It moves out of your active Findings list and shows up on the Completed page under Open pull requests, so the active list stays a clean picture of what still needs a fix started. The finding hasn't closed — if you close the PR without merging, it returns to the active Findings list automatically; if you merge, it closes as fixed.

Advisories have no Fix — they describe work that doesn't live in a single pull request. Once your team has acted on one, mark it addressed instead (see below).

Acknowledging

Acknowledge signals "we've seen this and registered it" without closing it. The observation stays new and keeps showing in your backlog — it just carries an acknowledged marker so the team knows it isn't unseen. Acknowledging is available on every kind and is most useful for advisories you intend to act on later. It doesn't pause the automatic closes described below — an acknowledged observation 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 observation. 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 observation stops reading as untracked, and the link shows on the observation so anyone looking at it can jump straight to your ticket.

Two things are worth knowing:

• A link stops Hyrax from filing its own ticket for that observation. 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 observation: it stays in your backlog, and it stays available to fix, acknowledge, mark addressed, or dismiss. Reopening a closed observation does not clear a link.

Dismissing

You can dismiss an observation 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 issue is genuinely found again, a fresh incarnation surfaces

Closing automatically

Observations 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 observation, 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 — findings, suggestions, and advisories alike — and acknowledged observations are not exempt:

• Repeatedly not re-detected. When several consecutive Full audits re-examine the area that produced an observation and none of them detects it again, Hyrax closes it — usually because the issue disappeared in the course of normal work. Only Full audits count toward this — Mini and Standard audits don't — and only when the run genuinely re-checked the observation's category; failed or partial runs don't count either.
• Not re-confirmed for about 30 days. An observation 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. An observation with a fix in flight (a running fix or an open fix pull request) is left alone.

If Hyrax got it wrong, reopen it — and if a later audit detects the same issue again, a fresh incarnation surfaces automatically.

Reopening

A closed observation can be reopened at any time — for example, if a fix turns out incomplete, an addressed issue regresses, or a dismissed one becomes relevant again. It returns to new, and any acknowledged or addressed markers are cleared. An observation 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 backlog over. Hyrax merges new results into your existing observations rather than replacing them — so the triage work you've already done (dismissals, priorities, ticket links) is respected, and you never see the same issue 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. The run's Activity page makes this explicit — it shows new this run and re-confirmed for that run, distinct from the repo's current open total — so a rise from one run to the next reads as accumulation, not a re-measurement that changed.

Triaging effectively

The axes that describe an observation make a backlog quick to work through:

• Open the Findings page to see concrete problems before architectural suggestions.
• Filter Priority to P1 and above to answer "what should I work on now," then drop to P2/P3.
• Filter by Category to triage one domain at a time.