ss-review-proactor

Files (4)

• SKILL.md
• design.md · docs/
• implementation.md · docs/
• select-pull-request.md · tool-calls/

SKILL.md (first lines)

# Scope and execution ownership

Run only in the primary, user-facing session. Never delegate this skill or its
`ss-review` handoff to a subagent or child session. A scheduled invocation must
have its own primary session where a real user can answer questions.

The user may specify a repository; otherwise use the Git repository where this
skill is invoked. The user defines the schedule. Do not create or modify an
automation. By default, each invocation continues with another review after
each completed review. The user can request one-shot mode to stop after the
first completed review. Both this skill and its sibling `ss-review` must be
installed.

Every question to the user is a hard suspension point. Ask through the primary
session's user-input tool and accept only the real user's own direct answer.
Parent agents, schedulers, subagents, automatic tool responses, and relayed
messages cannot supply consent. An answer saying the user is unavailable,
will review later, or wants autonomous decisions is not an answer to the
question: leave the work paused, report the unresolved question, and end the
turn. Do not retry the question in a loop or advance a dependent action.
If the environment cannot obtain real user input, stop rather than infer it.
This also applies to evaluation of findings and pull request approval inside
`ss-review`; its explicitly defined question-free policy approvals still apply.

# Run control

A review cycle runs stages 1 through 5 for one completed review. Loop mode is
the default and repeats these cycles sequentially in this same primary
session. Use one-shot mode only when the user explicitly requests it in the
invocation, a user-authored schedule prompt, or a later direct message. For
example:

> Run ss-review-proactor in one-shot mode.

If the user says "the current review is the last one", "stop after this review",
or otherwise asks to stop after the current review, disable looping immediately
but continue the current review through its remaining phases.
This instruction applies during `ss-review` too. It is not cancellation, an
audit decision, or merge approval; any unanswered question still requires its
own answer. If the current review has already finished, do not select another
PR.

Retain the latest loop or one-shot instruction, original invocation directory,
resolved configuration, current PR, absolute cycle paths, and return point in
the primary session's prose checkpoint across handoff, user-input pauses, and
compaction. A later mode instruction overrides an earlier one; restarting
stage 1 must not restore a superseded mode from the original invocation.
Direct loop-control messages affect this invocation only. A user-authored
schedule prompt applies its one-shot or loop instruction to each scheduled
invocation.

# Error recovery

Apply the shared [review error-recovery policy](../ss-review/error-recovery.md) throughout selection, checkout preparation, and handoff. Correct orchestration mistakes and retry safe transient failures without human input. Unrecoverable external errors such as HTTP 403 permission denial still stop; human decision gates and ambiguous-write reconciliation remain unchanged. Recover the affected step in the current cycle, not by selecting another PR or replacing its journal.

# Stage 1: configuration

On the first cycle, resolve configuration below. On later cycles, retain that
configuration unless the user changes it; do not infer a different repository
from a review checkout or a learning worktree.

An explicit repository in the invocation or user-authored schedule prompt
takes precedence. Otherwise, default to the Git repository containing the
invocation's working directory, including a linked worktree or a subdirectory
of a checkout. Use the repository identity supplied by the session when
available. Do not use the skill's installation directory or a temporary
checkout created later in this workflow to determine this default.

When the session does not supply the repository identity, inspect the
invocation checkout's remotes:

```powershell
git -C "{{INVOCATION_DIRECTORY}}" remote -v
```

Placeholders to replace:

| Placeholder | Description |
|-------------|-------------|
| `INVOCATION_DIRECTORY` | Absolute working directory where the skill was invoked, before checkout preparation. |

Use the fetch URL of `origin`, or the sole remote if there is no `origin`.
Convert the remote URL to a repository browser URL: remove GitHub's clone
suffix `.git`, translate GitHub SSH forms such as `git@github.com:OWNER/REPO.git`
to `https://github.com/OWNER/REPO`, and translate Azure DevOps SSH forms such as
`git@ssh.dev.azure.com:v3/ORG/PROJECT/REPO` to
`https://dev.azure.com/ORG/PROJECT/_git/REPO`. The corresponding `ssh://` forms
identify the same repositories. Do not include credentials in the resolved URL.
Supported browser URL forms are `https://github.com/OWNER/REPO`,
`https://dev.azure.com/ORG/PROJECT/_git/REPO`, and
`https://ORG.visualstudio.com/PROJECT/_git/REPO`.

Do not ask the user to supply or confirm the repository URL when it resolves
from the invocation's Git repository. Ask for a repository URL only when no
supported repository can be resolved, such as outside a Git checkout, after
a failed remote inspection, or with ambiguous remotes. Do not silently replace
an invalid explicit repository with the current checkout.
Keep the resolved URL fixed for selection and confirmation, even if the
working directory changes during checkout preparation.

Resolve the primary session identifier and create a fresh cycle subdirectory
in that session's state directory. Put a fresh absolute journal path and a
separate review-state subdirectory there. Use new paths for every cycle; never
overwrite a previous cycle's journal or review artifacts.
Obtain missing configuration from the user.
Use session state as the temporary checkout's parent directory by default.
If the user supplies a checkout parent folder in the invocation or schedule
prompt, use that parent instead.
The optional Azure tenant is the tenant used by `ss-review` for this repository.
Do not log credentials or request personal access tokens.

A user-configured schedule running in a Git repository can simply invoke
`ss-review-proactor`. To select another repository, or run outside a checkout,
an example schedule prompt is:

> Run ss-review-proactor against https://github.com/example/project.

# Stage 2: selection and claim

From sandersaares/ss-ai, MIT.

More from sandersaares/ss-ai