Shepherd
Core principle
Keep an authorized PR or MR moving with evidence, not noise: poll, act on new
actionable items, batch each target's local fixes into one push, then resolve
addressed threads. After a code-related CI failure, use full local verification
as the repair loop and CI only as confirmation. Never merge without explicit
authority.
Do not start persistent polling for a one-off inspection, no open targets, or an action requiring human judgment; report the state and stop.
Procedure
- Detect the platform with
git remote get-url origin: use gh for GitHub and
glab for GitLab. If it is ambiguous or unavailable, stop and ask.
- Establish targets and a handled-ID snapshot. Every external comment, review,
or thread absent from that snapshot is new, including pre-session feedback.
After each poll record feedback IDs, CI state, and this controller's comments.
- Before repeated polling, use one lowest-cost read-only evidence helper when
available. Give it targets and the snapshot; require new feedback IDs, body,
location, review state, non-manual CI state, failed jobs, and log references.
It never mutates. Keep triage, repairs, replies, pushes, resolution, retries,
and merging with the authorized controller.
- Poll with the platform CLI using provider commands,
then compare complete review, comment, and CI state with the snapshot. Inspect
failed logs only when needed. Do not reprocess old feedback or post a status-only
update.
- Triage new evidence before remote mutation. Fix clear requests and narrow
formatting, lint, compile, or test failures; answer clear questions in-thread.
Escalate architectural or contradictory feedback, unfamiliar failures,
non-obvious fixes, and out-of-scope conflicts. GitLab manual jobs are
non-blocking unless instructed otherwise.
- Handle each target in its own head checkout and batch every known actionable
item. Until a code-related CI failure, validate proportionately. After one,
inspect its evidence, run every locally available CI-equivalent check, fix all
failures, and rerun the full local suite before one repair push. Report exact
checks unavailable locally instead of using CI as an iterative test runner.
Reply after an addressed change or answer; resolve its thread only after the reply and required push succeed.
Do not combine heads, push after every comment, resolve a local-only fix, or comment when nothing changed.
- Recheck CI after the verified repair push; return to step 6 on another
code-related failure. Retry a suspected flaky GitLab job once without code
changes; report a second failure. Poll pending checks every 2–5 minutes,
active repair every 30–60 seconds, and after three or more unchanged cycles
every 10+ minutes. Two unchanged cycles remain on the normal 2–5 minute
cadence.
- Merge only when requirements and CI are green, conflicts are absent, and the
user granted explicit or standing merge authority. Do not infer authority from
approval.
Finish or escalate
Continue until the user stops monitoring, every target is merged or closed, or an escalation is needed. Report the target, current CI/review state, actions taken, and the next required human decision. Escalate immediately for ambiguous platform/target selection, an unresolved conflict, material human judgment, conflicting reviewer direction, or a failure that remains after three repair cycles.
1---2name: shepherd3description: Use when asked to shepherd, babysit, monitor, or poll open pull requests or merge requests, including triaging review feedback, CI failures, and routine follow-up.4---5
6# Shepherd
7
8## Core principle
9
10Keep an authorized PR or MR moving with evidence, not noise: poll, act on new
11actionable items, batch each target's local fixes into one push, then resolve
12addressed threads. After a code-related CI failure, use full local verification
13as the repair loop and CI only as confirmation. Never merge without explicit
14authority.
15
16Do not start persistent polling for a one-off inspection, no open targets, or an action requiring human judgment; report the state and stop.
17
18## Procedure
19
201. Detect the platform with `git remote get-url origin`: use `gh` for GitHub and
21 `glab` for GitLab. If it is ambiguous or unavailable, stop and ask.
222. Establish targets and a handled-ID snapshot. Every external comment, review,
23 or thread absent from that snapshot is new, including pre-session feedback.
24 After each poll record feedback IDs, CI state, and this controller's comments.
253. Before repeated polling, use one lowest-cost read-only evidence helper when
26 available. Give it targets and the snapshot; require new feedback IDs, body,
27 location, review state, non-manual CI state, failed jobs, and log references.
28 It never mutates. Keep triage, repairs, replies, pushes, resolution, retries,
29 and merging with the authorized controller.
304. Poll with the platform CLI using [provider commands](references/provider-commands.md),
31 then compare complete review, comment, and CI state with the snapshot. Inspect
32 failed logs only when needed. Do not reprocess old feedback or post a status-only
33 update.
345. Triage new evidence before remote mutation. Fix clear requests and narrow
35 formatting, lint, compile, or test failures; answer clear questions in-thread.
36 Escalate architectural or contradictory feedback, unfamiliar failures,
37 non-obvious fixes, and out-of-scope conflicts. GitLab manual jobs are
38 non-blocking unless instructed otherwise.
396. Handle each target in its own head checkout and batch every known actionable
40 item. Until a code-related CI failure, validate proportionately. After one,
41 inspect its evidence, run every locally available CI-equivalent check, fix all
42 failures, and rerun the full local suite before one repair push. Report exact
43 checks unavailable locally instead of using CI as an iterative test runner.
44 Reply after an addressed change or answer; resolve its thread only after the reply and required push succeed.
45 Do not combine heads, push after every comment, resolve a local-only fix, or comment when nothing changed.
467. Recheck CI after the verified repair push; return to step 6 on another
47 code-related failure. Retry a suspected flaky GitLab job once without code
48 changes; report a second failure. Poll pending checks every 2–5 minutes,
49 active repair every 30–60 seconds, and after three or more unchanged cycles
50 every 10+ minutes. Two unchanged cycles remain on the normal 2–5 minute
51 cadence.
528. Merge only when requirements and CI are green, conflicts are absent, and the
53 user granted explicit or standing merge authority. Do not infer authority from
54 approval.
55
56## Finish or escalate
57
58Continue until the user stops monitoring, every target is merged or closed, or an escalation is needed. Report the target, current CI/review state, actions taken, and the next required human decision. Escalate immediately for ambiguous platform/target selection, an unresolved conflict, material human judgment, conflicting reviewer direction, or a failure that remains after three repair cycles.
chrisbanes