Skip to main content

Improve

Audit asks "what's broken?" Improve asks "what could be better?"

Improve runs the same agent system as a standard audit, but the agents are looking for upgrades rather than defects: refactors that would simplify a tangled module, modernizations that would replace a deprecated dependency, performance wins, better-tested versions of currently fragile code, abstractions worth introducing, abstractions worth deleting.

The output is the same shape as audit's — rows in the unified findings table — but the kind is suggestion instead of finding, with an Implement action verb instead of Fix. Less "fix this", more "consider this."

Audit also emits a smaller cohort of architectural suggestions from its tail audit_synthesis stage. Improve is the heavier-thinking standalone surface — run it when you want a top-to-bottom pass focused on opportunities rather than defects.

When to run it​

Run improve once you've worked through the obvious audit findings and you want to know what could be better, not just what's broken. Good triggers:

  • A backlog of audit findings has been worked down.
  • You're scoping next quarter's investment in a service.
  • A team is about to adopt a codebase they didn't write.
  • You're evaluating "where does this codebase need love."

It is not a replacement for audit. Defects and security issues live in audit; deeper opportunity-shaped suggestions live in improve. Most teams run audit weekly (which surfaces a few synthesis suggestions for free) and improve quarterly or per planning cycle for a heavier focused pass.

What it costs​

Roughly $7–11 per run. Cheaper than a standard audit because the scanner pass is skipped — improve is agent-only.

Shipping a suggestion​

Click Implement on any suggestion and it goes through the same fix gauntlet as a finding's Fix — both buttons POST to the same /fix endpoint. Isolated worktree, agent edit, tests, reviewer, PR. The only difference is shape: suggestions tend to be larger, so the gauntlet's diff-size guard rejects more often. If a suggestion is too large to fit the gauntlet, break it into smaller tasks.

Refs​

Improve's suggestions get sequential HYRAX-N refs per tenant — same counter the audit findings draw from. Refs are stable across re-runs and PRs. Use them in commit messages, Linear tickets, and team chat — anyone on the team can paste the ref into Hyrax and pull up the finding.