Improvements overview

What improvements are for

Improvements turn current evidence into bounded follow-up work that can move one repository health area toward the green zone. They are the action side of Guard’s recurring loop: audit the current revision, select a useful problem, make or describe one safe change, let people review it, and audit the resulting revision again.

Guard does not treat an issue or pull request as the product outcome. Those are delivery artifacts. The outcome is a healthier codebase on which people and coding agents can build new features more safely.

Start from current evidence

Some improvement runbooks consume candidate context produced by a paired audit; others discover a narrow candidate from the current repository. In either case, audit-time evidence is not write permission or guaranteed current truth. Before acting, the run rechecks the repository revision, confirms that the problem still applies, and searches provider issues and review requests for duplicate work.

If the source is stale, already fixed, covered by existing work, too broad, or impossible to verify, the safe outcome is to stop or create a durable issue rather than force a patch.

One bounded improvement per run

Incremental work keeps diffs understandable and reversible. A run selects one useful candidate within its published scope, records why other candidates were skipped, and uses repository-native checks to define verification. Broad redesign, public API breaks, migrations, cross-service contracts, major upgrades, rollout-sensitive infrastructure, and product decisions remain issue-first or human-led work.

This boundary intentionally trades throughput for review quality. The next eligible run can address the next problem after the repository and provider state have changed.

Write modes and human control

Supported jobs expose an issue-only path and, where the runbook permits it, an issue-plus-review-request path. Issue-only does not edit repository files. Issue plus pull request or merge request creates or reuses a durable issue first, then opens one reviewable change only when the candidate is current, duplicate-free, small, safe, and credibly verifiable.

Guard never pushes directly to the default branch and never performs the final merge. Provider permissions, repository rules, code ownership, and a qualified reviewer remain authoritative.

Verification closes the loop

The run records baseline checks, targeted checks after the edit, limitations, and the exact provider artifacts it created or reused. Failed or unavailable verification can turn a potential pull request into issue-only, needs-human-review, or report-only output.

After a human merges a proposal, rerun the affected audit against the resulting commit. That new evidence establishes whether health improved and whether a different finding now has priority.

Choose the next task

• Configure an Improvement Job for cadence and write behavior.
• Autofix and human review for the full review boundary.
• Understand improvement outcomes when a run did not create the artifact you expected.
• Open a catalog page to learn the exact scope and maturity of one improvement.