First Successful PR Workflow

July 9, 2026 ยท View on GitHub

Use this when a team wants to try ripr on one real pull request and decide whether the recommendation is useful enough to adopt. Stable Rust gaps are the primary path; preview Python and TypeScript gaps can use the same workflow when an explicit gap ledger already supplies advisory repair records.

The success condition is intentionally small:

run ripr
-> read one repairable stable Rust gap or preview Python/TypeScript gap
-> add one focused test or output proof outside ripr
-> verify static movement
-> keep the receipt

This workflow is advisory. ripr does not edit source, generate tests, run mutation testing, call providers, or make merge decisions by default.

1. Pick One PR

Start with a normal PR where a reviewer can understand the intended behavior change. Avoid the first run on:

  • mechanical formatting-only changes;
  • broad refactors with many unrelated seams;
  • generated code;
  • changes that require runtime mutation calibration to interpret.

The first successful PR should answer one reviewer question:

Does the changed behavior have a meaningful test discriminator or checked
output proof?

2. Run The Pilot

From the PR checkout:

ripr pilot --root .

Read:

target/ripr/pilot/pilot-summary.md

The pilot summary is the first screen. It should name the top actionable gap, why it matters, the related test to inspect when available, and the command to capture after evidence.

If the pilot reports partial, use the retry command it prints. Do not guess at cache or timeout settings.

3. Prefer A Gap Record When Available

When a gap decision ledger already exists, use it as the repair source:

target/ripr/reports/gap-decision-ledger.json
target/ripr/reports/gap-decision-ledger.md

Gap records are the shared vocabulary behind PR repair cards, first-action reports, agent packets, optional gates, and repo badge targets. A useful first PR gap record should name:

  • the gap kind;
  • the scope;
  • the repair route;
  • the anchor;
  • the verification command;
  • whether it is eligible for PR comments, agent packets, gates, or badges.

If you only have repo exposure evidence, derive the conservative ledger:

ripr reports gap-ledger \
  --repo-exposure target/ripr/pilot/repo-exposure.json \
  --out target/ripr/reports/gap-decision-ledger.json \
  --out-md target/ripr/reports/gap-decision-ledger.md

For presentation/output-text changes or scoped Python/TypeScript repair-card findings, derive the PR-local route from the checked JSON output:

ripr check --root . --format json > target/ripr/reports/check.json
ripr reports gap-ledger \
  --check-output target/ripr/reports/check.json \
  --out target/ripr/reports/gap-decision-ledger.json \
  --out-md target/ripr/reports/gap-decision-ledger.md

For scoped Python or TypeScript repair-routing cards, the public first-PR front door can take the same saved check JSON directly and materialize the derived ledger before it selects the top repair:

ripr first-pr \
  --root . \
  --base origin/main \
  --head HEAD \
  --check-output target/ripr/reports/check.json

That path should produce MissingOutputContract with an AddOutputGolden repair route when user-facing output changed without checked output evidence, or a preview Python/TypeScript repair record with a verify command and check-output receipt command when the saved card is actionable. It should not turn generic static_unknown into an interruption.

4. Pick One Repairable Gap

Choose one actionable item. Prefer a gap that names a concrete repair:

  • missing equality-boundary assertion;
  • missing exact error variant assertion;
  • missing exact return value assertion;
  • missing field, object, side-effect, or mock expectation;
  • missing checked output or golden fixture.

Skip report-only static limitations for the first PR unless the task is to inspect an opaque helper, fixture, macro, or dynamic boundary.

5. Copy The Work Packet

For a gap-ledger-backed task, create the focused agent packet:

ripr agent packet \
  --root . \
  --gap-ledger target/ripr/reports/gap-decision-ledger.json \
  --gap-id <gap_id> \
  --json > target/ripr/agent/gap-packet.json

For older seam-backed flows, use the pilot packet or start a seam workflow:

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

Give a coding agent the bounded packet, not a broad instruction. It should know the owner, changed behavior, related test, missing discriminator or output proof, repair route, stop conditions, and verification command. When the packet comes from the gap ledger, llm_guidance.copyable_packet contains a pasteable Markdown work order with Task, Context, Repair, Verification, Stop Conditions, and Do Not Do sections.

6. Add One Focused Proof

Write the test or output fixture outside ripr. Keep the change narrow:

  • imitate the best related test when supplied;
  • exercise the missing value, branch, variant, field, object, side effect, or output text;
  • assert the behavior that would fail if the changed code were wrong;
  • add or update the output/golden fixture when the repair route is AddOutputGolden;
  • avoid unrelated refactors and production changes;
  • avoid smoke-only assertions when ripr asked for a stronger discriminator.

Run the project tests or golden checks that normally validate the PR. Static movement is not a replacement for the test suite.

7. Verify Movement

Capture the after snapshot with the command from the pilot, first-action report, or agent packet. The common shape is:

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

Then compare before and after:

ripr outcome \
  --before target/ripr/pilot/repo-exposure.json \
  --after target/ripr/pilot/after.repo-exposure.json

Read the result conservatively:

MovementMeaning
improvedStatic evidence got stronger for the selected behavior.
resolvedThe visible gap no longer appears under current evidence.
unchangedThe test may be misplaced, too broad, stale, or beyond current static limits.
regressedStatic evidence got weaker; inspect before continuing.
unknownRequired before or after evidence is missing or not comparable.

For output-contract repairs, run the verification command from the gap record, usually:

cargo xtask goldens check

8. Keep A Receipt

For a human-only pilot, attach the ripr outcome Markdown to the PR or upload it with the CI artifact packet.

For an agent or repeatable workflow, produce the focused receipt:

ripr agent verify \
  --root . \
  --before target/ripr/pilot/repo-exposure.json \
  --after target/ripr/pilot/after.repo-exposure.json \
  --json > target/ripr/agent/agent-verify.json

ripr agent receipt \
  --root . \
  --verify-json target/ripr/agent/agent-verify.json \
  --seam-id <seam_id> \
  --json \
  --out target/ripr/agent/agent-receipt.json

The receipt is the review trail. Without a receipt, do not infer improvement from the test diff alone.

If you are working from VS Code, run ripr: Show Status after the receipt and refresh. The editor can point to the validated first-pr packet, open the Markdown packet, and copy the bounded summary or repair packet when the packet matches the current workspace and diagnostic identity.

9. Add Advisory CI After One Manual Win

After one PR has a useful before/after receipt, add generated advisory CI:

ripr init --ci github

The generated workflow is advisory by default. It uploads pilot, agent, report, workflow, and review artifacts; writes a PR summary; and keeps gate authority separate. Do not make it blocking until the repository has reviewed its first advisory baseline and explicitly opted into policy gates.

What Success Looks Like

A successful first PR leaves this trail:

pilot-summary.md
gap-decision-ledger.md, when available
one focused test or output fixture
after.repo-exposure.json
ripr outcome Markdown
optional agent-verify.json
optional agent-receipt.json

The reviewer should be able to say:

ripr found one repairable stable Rust gap or preview Python/TypeScript gap.
We added one focused proof for that behavior.
The static evidence improved or resolved, or the checked output proof now exists.
The result is advisory, and runtime mutation testing remains optional follow-up.

Surface Ownership

The first-run loop composes existing surfaces. Do not add a new artifact when one of these already owns the job:

SurfaceOpens withOwnsDoes not own
First-run packettarget/ripr/reports/start-here.mdTop repairable stable Rust gap, preview Python/TypeScript gap, or no-action state, repair route, verify command, artifact links, advisory boundary.Analyzer truth, gate authority, PR comments, source edits, generated tests.
First successful PR workflowThis documentManual adoption path from one PR to one repair receipt.Output schema contracts or editor behavior.
QuickstartQuickstartFirst-hour path selection across CLI, PR, editor, and agent use.Full report topology.
Generated CICI strategyAdvisory PR summary, artifact upload, start-here projection, optional gate artifact links.Pass/fail authority unless an explicit gate-decision artifact owns it.
PR repair commentsPR review guidance and PR inline comment publisher workflowBounded repair cards from existing review-comment artifacts when explicitly configured.Free-form review, branch protection, default blocking.
Editor handoffEditor first-pr bridge workflowRead-only projection of existing first-pr packets into saved-workspace editor status and actions.Producing first-pr packets or PR/CI artifacts.
Agent packetLLM operator guideBounded work order with task, context, repair, verification, stop conditions, and non-goals.Provider calls, generated tests, or source edits.
Badge endpointsBadge policy and verification contractsRepo-scoped public trust markers.PR-local test adequacy or runtime mutation proof.
Gate decisionCalibrated gate policy and blocking readinessExplicit pass/fail authority when a repository opts into a gate mode.Start-here summaries, comments, or badges.

Implementation and cleanup follow-up lives in plans/adoption-integration-cleanup/.