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 filter, triage, dismiss, and reopen all of them the same way, so a repository's backlog is one ordered list, not three.

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 Expired).

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.

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.

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

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.

Triaging effectively

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

• Filter Kind to Findings 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.