Quickstart

Use this guide to get useful RIPR feedback in the first hour without learning the full report topology. Pick one path, get one repairable Rust gap or a clear no-action state, and keep the receipt.

RIPR finds changed Rust code where the nearby tests may not actually catch the changed behavior. The static, draft-time question it answers is:

For the behavior changed in this diff, do the current tests include an
assertion or check that would catch the changed behavior?

It does not edit source, generate tests, run mutation testing, or prove test adequacy. The normal first-hour loop is:

inspect one change
-> select one named gap
-> start the repair transaction
-> write one focused test outside RIPR
-> finish the transaction
-> keep the advisory receipt

RIPR calls these locations "seams" in JSON, specs, and reports. First-hour docs use plain language first; Terminology bridges to the internal model when you need it.

The public command hierarchy keeps the first-hour roles distinct: check is ordinary first value, pilot is guided repo adoption, agent repair is the repair transaction, and first-pr composes PR evidence.

Each repair's before phase prints the exact --attempt command needed after the test edit. Retain it: the repair-attempt ID identifies the prepared transaction and differs from the seam ID used to select the gap. Repair attempt identity documents continuation and recovery.

The Rust gap-repair loop is usable alpha. Its package, editor, bounded packet, and before/after transaction paths are proved when RIPR emits a complete route; the governed real-repository corpus does not yet establish how often ordinary changes yield such a route or complete successfully. Treat a no-action or limited result as evidence, not as a failed product promise or a clean bill of health.

Choose Your Path

Most adopters should choose one of these first-hour paths:

Path	Use when	Start with	First success
CLI first	You want one local before/after proof.	ripr check --base origin/main	Top Rust gap or an honest no-action/limited state, followed by one bounded repair attempt.
PR first	You want reviewers to see advisory evidence in GitHub.	ripr init --ci github	Non-blocking summary, repair card, artifact packet.
Editor or agent first	You are repairing while coding, or handing work to an LLM.	VS Code ripr: Show Status or ripr agent repair --seam-id <id> --phase before	Current gap, related test, edit cage, verify route, and receipt.

For TypeScript, JavaScript, or broader Python static-fact evaluation, first read Language adapter preview workflow. Preview language evidence is syntax-first, visibly preview/advisory, and not a default gate input. The scoped Python repair-routing loop is usable alpha for selected pytest/unittest repair cards, packets, verify commands, and receipts; it remains advisory and does not run imports, execute tests, or generate tests by default.

ripr.toml is optional. ripr init materializes repo-local policy when a team wants to review, version, and tune it. It is not activation, and it is not required for first value.

VS Code First Hour

Use this path when you want saved-workspace feedback while writing or reviewing Rust.

1. Install EffortlessMetrics.ripr from VS Code Marketplace or Open VSX.
2. Open a Rust/Cargo workspace.
3. Check the ripr status bar item or run ripr: Show Status.
4. Open the Problems panel, hover a RIPR diagnostic, and inspect the gap.
5. Use ripr: Start Current Repair or the focused-test actions to copy the repair packet, open the related test, and copy the verify command.

The current editor command is the contextual shell for the same bounded before/edit/after idea. The explicit CLI/agent equivalent is:

ripr agent repair --root . --seam-id <id> --phase before
# edit one focused test outside RIPR
ripr agent repair --root . --attempt <repair-attempt-id> --phase after

Normal editor install should not require cargo install ripr. The extension resolves the server from ripr.server.path, bundled or cached assets, verified GitHub Release download, or PATH.

If no diagnostics appear, start with the status path:

ripr: Show Status
ripr: Show Output
ripr: Restart Server

The editor analyzes the saved workspace. Unsaved-buffer overlays are not enabled by default. Save the file or refresh analysis before trusting a stale diagnostic.

Deep links: Editor evidence workflow, Editor extension, Server provisioning.

CI First Hour

Use this path when you want PR-visible advisory evidence without asking every reviewer to download raw artifacts.

Generate the GitHub workflow:

ripr init --ci github

Or copy the workflow from CI strategy when adopting from the GitHub UI.

The generated workflow is advisory by default. On a PR, read the job summary first. It should show the first-run status, top repairable gap or no-action state, repair route, verify command, artifact links, and gate-authority boundary. The uploaded packet keeps the detailed pilot, workflow, agent, report, and review artifacts.

Do not make generated CI blocking until the repository has reviewed its first advisory baseline and explicitly opted into a policy gate.

Deep links: CI strategy, PR review guidance, Blocking readiness.

CLI First Hour

Use this path when you want the reproducible local proof loop.

Install:

cargo install ripr

From this repository, use:

cargo install --path crates/ripr

Inspect the current change:

ripr check --base origin/main

The bounded human output begins with one Start here: state. It either names the top repair-ready gap, reports an honest no-action state, or names the limitation that prevents current guidance. Use --format human-full for the complete evidence and --format json for machine data.

For a repair-ready gap, start the ordinary repair transaction:

ripr agent repair --root . --seam-id <id> --phase before

Make one focused test edit outside RIPR, then finish:

ripr agent repair --root . --attempt <repair-attempt-id> --phase after

The before phase writes the pre-edit snapshot and repair packet. The after phase writes the post-edit snapshot, persists static verification JSON, and emits a receipt. RIPR does not author or apply the test edit.

For guided repository adoption and materialized pilot reports, use:

ripr pilot --root .

pilot is broader than the ordinary one-change check. If it reports a partial result, use the retry command it prints rather than guessing at cache or timeout settings.

For explicit low-level before/after comparison, the underlying commands remain available:

ripr check --root . --mode ready --format repo-exposure-json > target/ripr/pilot/after.repo-exposure.json
ripr outcome \
  --before target/ripr/pilot/repo-exposure.json \
  --after target/ripr/pilot/after.repo-exposure.json

Those commands are useful for control and debugging; they are not required plumbing for the ordinary two-phase repair path.

To compose PR-facing evidence from existing artifacts, use:

ripr first-pr --root . --base origin/main --head HEAD

It writes target/ripr/reports/start-here.{json,md} and does not add analyzer truth or repair a gap. Inside this repo, cargo xtask first-pr is a compatibility wrapper over the same public command.

Read the front door with the same vocabulary across CLI, editor, and PR surfaces:

• start here: open target/ripr/reports/start-here.md first when it exists.
• safe next action: repair one named gap, regenerate missing evidence, or stop on no-action.
• missing artifact, stale evidence, wrong root, and malformed artifact: fail closed before repair work.
• preview-limited evidence: syntax-first and advisory, with static limits before repair language.
• verify command, receipt command, and receipt path: the static movement proof rail, not runtime adequacy or gate approval.

When a surface boundary is unclear, use the ownership table in First successful PR workflow. It names which surface owns start-here, generated CI, editor handoff, agent packets, badges, PR evidence, and gate authority.

Agent Or Reviewer First Hour

Use this path when a human or external coding agent needs a deterministic work packet for one focused test.

When a current finding supplies a seam ID, use the primary repair command:

ripr agent repair --root . --seam-id <seam_id> --phase before
# edit one focused test outside RIPR
ripr agent repair --root . --attempt <repair-attempt-id> --phase after

Ask RIPR what local artifacts already exist when resuming or diagnosing:

ripr agent status --root .

For explicit low-level control, ripr agent start, brief, packet, verify, receipt, and review-summary remain available. For example:

ripr agent start --root . --seam-id <seam_id> --out target/ripr/workflow

The generated target/ripr/workflow/commands.md exposes the task, context, repair route, verification command, stop conditions, and receipt path.

The repair, status, and workflow commands read or write artifacts. They do not edit source files, generate tests, call an LLM API, run mutation testing, refresh LSP state, or enable CI blocking.

See LLM operator guide.

Troubleshooting

Symptom	First check
VS Code shows no RIPR state, or shows no focused test gap.	Run ripr: Show Status, then ripr: Show Output. Confirm a Rust/Cargo workspace is open and saved.
VS Code cannot start the server.	Check Server provisioning for configured path, bundled or cached assets, GitHub Release download, and PATH fallback.
Diagnostics look stale.	Save the workspace file or run Refresh Analysis - Saved Workspace Check.
CI has no top recommendation.	Open the advisory job summary, then inspect the uploaded report packet.
Agent status says artifacts are missing.	Run the next_command printed by ripr agent status.
Local CLI behavior is surprising.	Run ripr doctor and inspect config precedence in Configuration.

Known Limits

RIPR reports static exposure evidence. It should not be read as runtime proof.

It does not:

• run mutants;
• report killed or survived outside supplied runtime calibration reports;
• prove test adequacy;
• generate tests;
• edit source files;
• replace coverage or execution-backed mutation testing;
• analyze unsaved editor buffers by default;
• make generated CI blocking by default.

Static classifications stay conservative: exposed, weakly_exposed, reachable_unrevealed, no_static_path, infection_unknown, propagation_unknown, and static_unknown.

When runtime mutation data already exists, import it as advisory calibration data through runtime calibration. Runtime vocabulary belongs in that calibration report, not in ordinary static RIPR findings.

Next Docs

• Public command hierarchy for the stable task roles.
• Terminology for the bridge between plain wording and the internal model (seam, discriminator, grip, canonical gap, etc.).
• First successful PR workflow for the one-PR path from a repairable Rust gap to a focused proof and receipt.
• Targeted test workflow for the deeper before/after evidence and optional calibration loop.
• Editor extension for VS Code install, commands, and saved-workspace refresh behavior.
• CI strategy for the generated advisory workflow and artifact packet.
• LLM operator guide for the source-edit-free agent loop.
• Configuration for ripr.toml, modes, severities, and editor settings.
• Language adapter preview workflow for opt-in TypeScript, JavaScript, and Python evidence.
• Output schema for JSON contracts.