> ## Documentation Index
> Fetch the complete documentation index at: https://docs.remyx.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Outrider run modes

> Understand scheduled, manual, pinned, and prepared-example Outrider runs.

Outrider can select a candidate for a repository or run against a change you specify.

## Automatic selection

Outrider reviews available candidates and repository context, then chooses whether a change is ready to implement.

## Pinned change

Use the documented input or command to request a specific method or research item.

## Prepared example

Studio's Quickstart can start from a prepared implementation branch. This demonstrates the review-and-refine workflow and can finish faster than an implementation from scratch.

## Outcomes

A run may produce a draft PR, Issue, branch, or a decision not to publish. Use the GitHub Actions log to inspect the outcome and checks.

## Exact inputs

The tables below define each supported run mode and its configuration.

***

## Ways to trigger a run

Four ways to say what Outrider should implement. The harness downstream (guardrails, tests, license scan, PR body) is the same for all of them; only where the "why" comes from differs.

| Trigger | Where the intent comes from | CLI | Action input |
| - | - | - | - |
| **Alerts** | The ranker picks from arXiv against your Research Interest on the workflow's cron | none (scheduled) | none; `interest-id` scopes the pool |
| **Search** | You supply a method-family query; the engine search returns the top arXiv hit | `--search-method "riemannian preconditioning LoRA"` | `search-method` |
| **Pin** | You name an exact arXiv id | `--pin-arxiv 2410.20305v2` | `pin-arxiv` |
| **Brief** | You write the design brief yourself: an issue body, a spec, a notebook. No arXiv anchor | `--brief "add exp backoff to the HTTP client"` or `--brief @design.md` | `mode: brief` + `lead-content` |

```bash theme={null}
# paper-anchored: exact arXiv id, or a method-family search
remyxai outrider trigger --repo owner/name --pin-arxiv 2410.20305v2
remyxai outrider trigger --repo owner/name --search-method "riemannian preconditioning LoRA optimizer"

# brief-anchored: a design brief you supply, inline or from disk
remyxai outrider trigger --repo owner/name --brief "add exponential backoff to the HTTP client"
remyxai outrider trigger --repo owner/name --brief @design.md
```

A pin does not have to be in the candidate pool: the action looks the id up in the Remyx catalog, then on arxiv.org, so any published arXiv paper works (`skipped_pin_arxiv_unresolvable` if neither resolves). An explicit pin or search also bypasses the don't-re-recommend throttle, so you can re-run a paper that already has an open artifact. The full flag list is in the [CLI reference](https://docs.remyx.ai/cli/outrider-trigger.md#trigger-a-one-shot-run).

### Run from a design brief

`mode: brief` is the paper-less path. The brief you pass as `lead-content` **is** the spec: no ranking, no selection pass, no paper preflight, and no refinement chain. The run clones the repo, writes the brief into the agent's spec bundle, implements it, runs the same post-session gates as a paper run (path policy, integration check, stub density, self-review, canary, secret scan), and opens a draft PR whose body carries the brief under **Design brief** instead of a paper attribution. GitHub, Hugging Face, and dataset links in the brief are license-scanned (the first five) and the result lands in the PR's License section.

`remyxai outrider trigger --brief` is shorthand for `--mode brief` with the brief as the lead content. `@path` reads the brief from a file. It can't be combined with `--pin-arxiv`, `--search-method`, `--lead-content` or `--lead-content-file`; it can be combined with `--start-from-ref` to build the brief on top of an existing branch, and with `--publish branch` to review the output before anything opens. If the installed workflow predates the `mode` and `lead-content` inputs, the CLI refuses rather than silently running a paper pass; re-provision with `remyxai outrider init --repo owner/name --force`. Brief mode is the one mode that runs without an `interest-id`; when one is configured it is read only for repo context.

| Status | Meaning |
| - | - |
| `pr_opened_brief` | A draft PR was opened from the brief |
| `branch_pushed_no_pr` | `publish: branch`: the branch was pushed, nothing opened |
| `brief_declined_open_as_issue` | The agent judged the brief too broad for a PR and wrote an Issue-shaped write-up instead. No Issue is opened yet: the branch is left unpushed for you to review the write-up in the run log |
| `issue_opened_canary_missing` / `branch_pushed_canary_missing` | The per-run canary was missing from the final commit; routed to an Issue (or kept as a branch) for a human to inspect |
| `skipped_brief_missing_lead_content` | `mode: brief` ran with an empty `lead-content` |
| `brief_failed` | The run threw (for example a rejected push). Exits red |

In the action directly:

```yaml theme={null}
- uses: remyxai/outrider@v1
  with:
    mode: brief
    lead-content: ${{ inputs.brief }}
    # pass a Linear issue URL as the brief and set linear-api-key to have its body fetched
```

***

## How it works

A run has two stages. The Remyx engine ranks a candidate pool server-side, then Outrider checks candidates against a clone of your repo and decides what to open.

**Ranking.** The pool is ranked from three inputs: your interest's context, your team's shipping history (extracted from the merge log), and a learned preference model. Candidates that match the direction your team has shipped rank above topically similar ones.

**Validation and decision.** A high relevance score does not mean a candidate is implementable; the top-ranked paper often has no call site in your repo. A selection pass checks each candidate against the codebase (code search and file reads) and picks the most implementable; if none fit, the run skips. Filters that do not call the model run first, so a run that cannot produce a useful result exits before any LLM cost. Each run ends in one of three outcomes: a draft PR, an Issue, or a skip.

![The Outrider pipeline: external sources and your repo feed the Remyx engine's ranking; the action fetches the candidate pool, gates it, selects the most implementable candidate, implements within guardrails, validates, and routes to a draft PR, an Issue, or a skip, with the refinement chain promoting PRs and run telemetry feeding back into ranking](https://mintcdn.com/remyxai/2lznviOD5A07VqzC/images/outrider/outrider-pipeline.png?fit=max\&auto=format\&n=2lznviOD5A07VqzC\&q=85\&s=489774aaa92c57bd77dc3ab43689e805)

> [card] Draft PR
>
> The candidate integrates into an existing call site and passes the validators (tests, stub density, reachability). Outrider opens a draft PR with code and tests.

> [card] Discussion Issue
>
> The candidate is relevant but not directly implementable (no call site, too many stubs, or unreachable code). Outrider opens an Issue with the attempted diff.

> [card] Skip
>
> No candidate cleared the confidence, dedup, or fit gates. No artifact is created; the run records a [status](#run-outcomes).

***

## Refinement-pass chain

When `chain` is `true` (the default), opening a draft PR isn't the end of the run. Outrider keeps going in the same run and walks the draft through three phases before it asks for review:

**1. Fidelity**

Diffs the draft against the paper's reference implementation and emits a **coverage matrix**: what the diff covers, what it defers, and where it deviates from the source. When no public reference exists, it anchors the audit against the arXiv abstract instead; that's lower precision and the PR body says so.

**2. Convention**

Rewrites the PR body to the repo's canonical PR template, folds Outrider's own scaffolding into a collapsible **Discovery context** block, and applies contributor conventions learned from recent merged PRs. Runs `ruff` auto-fix and force-pushes the result as the bot.

**3. Test**

Runs lint plus a focused `pytest` on the touched files. On a pass it flips the draft to **ready-for-review**; on failure the PR stays a draft, labelled `outrider:test-failed`, for you to take over.

The Issue path gets a convention pass too: `mode: issue-convention` folds an Issue body to the repo's `ISSUE_TEMPLATE` shape.

Set `chain: false` to stop after the first draft: Outrider opens the PR exactly as it first wrote it and runs none of the phases above. That's the cheaper recommend-only mode.

### Labels

The chain records its progress as labels on the PR, which is also how a separate-workflow chain is triggered.

| Label | Set when |
| - | - |
| `outrider:draft` | The draft PR opens (the fidelity phase's trigger) |
| `outrider:fidelity-done` | The fidelity audit posted its coverage matrix |
| `outrider:needs-judgment` | The audit flagged at least one item for human review |
| `outrider:convention-done` | The convention pass rewrote the body |
| `outrider:test-failed` | Lint or tests failed; the PR stays a draft |
| `outrider:issue-convention-done` | An Issue's body was folded to the repo template |
| `risky-surface` | The diff touched a dependency manifest, CI, hook, container or shell file (see [Guardrails](https://docs.remyx.ai/platform/agents/outrider-configuration.md#guardrails)) |

### Run the chain from separate workflows

Instead of the inline chain, you can drive each phase from a `pull_request: labeled` workflow with `pr-number` from the event payload. This is how a phase is re-run against an existing PR.

```yaml theme={null}
on:
  pull_request:
    types: [labeled]
jobs:
  fidelity:
    if: github.event.label.name == 'outrider:draft'
    runs-on: ubuntu-latest
    permissions: { contents: write, pull-requests: write }
    env:
      REMYX_API_KEY: ${{ secrets.REMYX_API_KEY }}
      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}   # or the secret of the provider you route at
    steps:
      - uses: remyxai/outrider@v1
        with:
          interest-id: ${{ vars.REMYX_INTEREST_ID }}
          mode: fidelity                      # convention / test take the same shape
          pr-number: ${{ github.event.pull_request.number }}
```

***

## Run outcomes

Every run ends in a `status` in the Action log and the `status` output. Statuses marked **red** make the workflow step exit non-zero; everything else, including Issues and skips, is a legitimate green outcome.

### Recommend mode

| Status | Meaning |
| - | - |
| `pr_opened` | PR opened ready for review (tests passed and `draft-mode` is not `always`) |
| `pr_opened_draft` | PR opened as a draft |
| `issue_opened` | The agent elected Issue mode (wrote a write-up instead of code) |
| `issue_opened_preflight` | The pre-flight pass routed to an Issue before implementation |
| `issue_opened_no_integration` | The diff adds code that nothing invokes |
| `issue_opened_stub_density` | The new module is at least 50% stubs |
| `issue_opened_no_test_integration` | New tests don't import from any pre-existing module |
| `issue_opened_self_review` | The self-review judged the new code an orphan; the Issue preserves the diff |
| `issue_opened_substitution` | A replacement or extension candidate that needs dependency changes the guardrails block, or has no call site to anchor on |
| `issue_opened_high_risk` | The diff-risk gate routed to a human-review Issue; the diff is preserved in the body |
| `issue_opened_canary_missing` | The canary trailer was missing from the final commit; the branch is kept for inspection |
| `skipped_low_confidence` | Best candidate below `min-confidence` |
| `skipped_open_artifact` | An open Remyx PR or Issue from a prior run still exists (`rate-limit-days`) |
| `skipped_by_selection_verification` | The selection pass checked every candidate against the repo and rejected all; the reasoning renders in the step summary |
| `skipped_pr_exists` / `skipped_issue_exists` | Every candidate already has an open PR, or a prior Issue (open or closed) referencing its arXiv id |
| `skipped_external_issue_exists` | The selection pass surfaced an out-of-pool candidate the team already has in an Issue |
| `skipped_arxiv_already_landed` | The pinned paper has already been merged on the target |
| `skipped_pin_arxiv_unresolvable` | `pin-arxiv` resolved neither in the Remyx catalog nor on arxiv.org |
| `skipped_no_method_match` | `search-method` returned no usable hit |
| `skipped_issues_disabled` | The Issue route was needed but Issues are disabled (the default on forks); enable them with `gh repo edit <repo> --enable-issues` |
| `skipped_fidelity_fabrication` / `skipped_fidelity_fabrication_after_patch` | The pre-PR fidelity gate (`fidelity-policy: block`) found the implementation did not match the reference, before or after its one patch attempt |
| `skipped_test_failure` | Tests failed and `draft-mode` is `never` |
| `rejected_path_violations` | The agent touched a blocked path; nothing was pushed |
| `aborted_secret_in_payload` | The outbound secret scanner matched a credential in the draft payload; nothing was opened. **Red** |
| `claude_failed` | The coding-agent CLI exited non-zero. **Red** |
| `error` | Unhandled exception. **Red** |

### Brief mode, branch mode, smoke, weekly summary

| Status | Meaning |
| - | - |
| `pr_opened_brief` / `brief_declined_open_as_issue` / `skipped_brief_missing_lead_content` | See [Run from a design brief](#run-from-a-design-brief) |
| `brief_failed` | A brief run threw. **Red** |
| `branch_pushed_no_pr` | `publish: branch`: the branch was pushed and nothing was opened |
| `branch_pushed_canary_missing` | Branch mode, with the canary missing; review before promoting |
| `lead_captured_no_issue` | Branch mode would have filed an Issue; the content is in the step summary instead |
| `smoke_ok` / `smoke_failed` | Whether the configured agent, provider and model reached the vendor (`mode: smoke`) |
| `weekly_summary_posted` / `weekly_summary_skipped_no_discussion_id` | The digest was posted, or ran with no `weekly-discussion-id` |
| `weekly_summary_failed` | Nothing was posted. **Red** |

### Chain phases

These appear in the `chain_*_status` outputs of an inline run, or as the run `status` when a phase runs standalone. The pre-PR gate's verdict (`pre_pr_fidelity_clean` / `pre_pr_fidelity_advisory` / `pre_pr_fidelity_needs_judgment` / `pre_pr_fidelity_skipped_*` / `pre_pr_fidelity_failed_*`) is recorded in the run summary and telemetry rather than as an output; a blocking verdict surfaces as `skipped_fidelity_fabrication*` above.

| Phase | Status | Meaning |
| - | - | - |
| Fidelity | `fidelity_audited`, `fidelity_audited_needs_judgment`, `fidelity_audited_paper_anchored`, `fidelity_audited_advisory` | Coverage matrix posted (reference-anchored, or abstract-anchored when no reference exists) |
| | `fidelity_skipped_no_reference` / `fidelity_skipped_not_bot` / `fidelity_skipped_no_pr` / `fidelity_skipped_reference_mismatch` | Nothing to audit against, or the PR isn't a `remyx-ai[bot]` draft |
| | `fidelity_failed_clone` / `fidelity_failed_claude` | **Red** |
| Convention | `convention_aligned` | Body rewritten and non-algorithmic alignment patches applied |
| | `convention_skipped_no_corpus` / `convention_skipped_no_pr` / `convention_skipped_not_bot` | No merged-PR corpus to learn from, or nothing to act on |
| | `convention_failed_extraction` / `convention_failed_misalignment` / `convention_failed_patch` / `convention_failed_push` | **Red** |
| Test | `test_passed` | Lint and tests passed; the draft was moved to ready for review |
| | `test_failed` | Lint or tests failed; `outrider:test-failed` applied, the PR stays a draft |
| | `test_skipped_no_pr` / `test_skipped_not_bot` | Nothing to test |
| | `test_failed_setup` | The test environment could not be set up. **Red** |
| Issue convention | `issue_convention_aligned` / `issue_convention_aligned_no_fitting_template` / `issue_convention_skipped_no_templates` | The Issue body was folded to the best template, or folded with scaffolding collapsed when none fit |
| | `issue_convention_skipped_no_issue` / `issue_convention_skipped_not_bot` | Nothing to act on |
| | `issue_convention_failed_claude` / `issue_convention_failed_patch` | The model call or the body PATCH failed (`_claude` is **red**) |

The same tables, kept in step with the action, are in the action repo's [`docs/configuration.md`](https://github.com/remyxai/outrider/blob/main/docs/configuration.md).

***

## Anatomy of an Outrider PR

As first opened, a PR body is built in a fixed order so you know where to look:

1. **Tests and self-review**: what the integration covers, what it left out, and the self-review's verdict on reachability.
2. **License & code availability**: the paper's reference code and any repos, models or datasets the implementation drew on, with their SPDX ids and a flag when one is copyleft, non-commercial, or missing.
3. An italic *Implements \[paper]* line linking the arXiv id. A brief-mode PR says it was drafted from a design brief instead, lists the Issues the brief referenced, and carries the brief itself in a collapsed **Design brief** block.
4. **Discovery context**, a collapsed `<details>` block with Outrider's scaffolding: the research interest, which agent implemented it, the selection reasoning, and the suggested experiment. Absent on a brief-mode PR, since there was no discovery.
5. A footer naming the Remyx orchestrator that opened it.
6. **Review before landing**, appended only when the diff touched a risky surface; lists the files.

The refinement chain then edits the body in place: the fidelity phase appends a **Coverage** matrix (covers / defers / deviates against the reference, with a note when the audit was anchored on the abstract only), and the convention phase rewrites the body to your repo's PR template and folds the scaffolding into the Discovery context block. The body's last line is a `Co-Authored-By: remyx-ai[bot]` trailer, kept last through every rewrite, so attribution survives a squash-merge.

Relevance scores and confidence lines are not in the body; they live in the run telemetry and the [agent report](https://docs.remyx.ai/platform/agents/overview.md#the-agent-report).

### Reviewing it

Treat it like a first-pass proposal from a teammate:

1. **Read the self-review and the coverage matrix** in the PR body: what the integration covers, what it deferred, and where it deviates from the source.
2. **Run the diff and tests** locally; the action runs `pytest` plus an integration check, but your full suite is the real bar.
3. **Decide**: merge, push follow-ups, or close. Your call feeds the agent's [Direction](https://docs.remyx.ai/platform/agents/overview.md#direction) either way, and the [Inbox](https://docs.remyx.ai/platform/review/inbox.md) card clears itself when GitHub records the merge or close.

Merged and closed PRs feed back into the agent's [Direction](https://docs.remyx.ai/platform/agents/overview.md#direction); every decision re-weights what it proposes next. To measure a PR's effect before deciding, mention `@remyx-ai validate` on it ([Validate](https://docs.remyx.ai/platform/agents/validate.md)).

## Next steps

[Run Outrider on a repository](https://docs.remyx.ai/tutorials/outrider-repository.md) · [Use the CLI](https://docs.remyx.ai/cli/outrider.md) · [Read the GitHub Action configuration](https://docs.remyx.ai/platform/agents/outrider-configuration.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.