olliecrow/deepreview

DeepReview

Multi-agent collaboration

• Default to using subagents when they are likely to improve speed, quality, confidence, or keep the main context clean.
• Use subagents to widen coverage, dig deeper on one thread, get a fresh second opinion, or keep the main thread clean while side work runs.
• Split work into clear packets with owners, inputs, acceptance checks, and a synthesis step when parallelizing.
• Keep the main agent focused on synthesis, unblockers, and the next critical-path step; let subagents handle bounded side work that can run in parallel.
• Use single-agent execution only when scope is small or coordination overhead outweighs gains.

Deepreview-specific subagent split

• Use subagents when the run is long, artifact-heavy, or the delivery state is not obvious.
• Suggested split: run-watcher owns live process state, heartbeats, and stuck-run signals, and updates plan/current/deepreview-monitor.md.
• Suggested split: artifact-reader owns round-status.json, summaries, delivery artifacts, and log folders, and updates the same note with evidence paths.
• Suggested split: final-checker does a fresh pass on the final story against the saved artifacts before closeout or intervention.
• The main agent owns intervention decisions, rerun choices, delivery actions, and the final merged report.
• Use subagents only when the work splits cleanly; otherwise stay single-agent.

Proactive autonomy and knowledge compounding

• Be proactive: immediately take the next highest-value in-scope action when it is clear.
• Default to autonomous execution: do not pause for confirmation between normal in-scope steps.
• Request user input only when absolutely necessary: ambiguous requirements, material risk tradeoffs, missing required data/access, or destructive/irreversible actions outside policy.
• If blocked by command/tool/env failures, attempt high-confidence fallbacks autonomously before escalating (for example rg -> find/grep, python -> python3, alternate repo-native scripts).
• When the workflow uses plan/, ensure required plan directories exist before reading/writing them (create when edits are allowed; otherwise use an in-memory fallback and call it out).
• Treat transient external failures (network/SSH/remote APIs/timeouts) as retryable by default: run bounded retries with backoff and capture failure evidence before concluding blocked.
• On repeated invocations for the same objective, resume from prior findings/artifacts and prioritize net-new progress over rerunning identical work unless verification requires reruns.
• Drive work to complete outcomes with verification, not partial handoffs.
• Treat iterative execution as the default for non-trivial work; run adaptive loop passes. Example loops (adapt as needed, not rigid): issue-resolution investigate -> plan -> fix -> verify -> battletest -> organise-docs -> git-commit -> re-review; cleanup scan -> prioritize -> clean -> verify -> re-scan; docs audit -> update -> verify -> re-audit.
• Keep looping until actual completion criteria are met: no actionable in-scope next step remains, verification is green, and confidence is high.
• Run organise-docs frequently during execution to capture durable decisions and learnings, not only at the end.
• Create small checkpoint commits frequently with git-commit when changes are commit-eligible, checks are green, and repo policy permits commits.
• Never squash commits; always use merge commits when integrating branches.
• Prefer simplification over added complexity: aggressively remove bloat, redundancy, and over-engineering while preserving correctness.
• When you touch code, leave the touched area in a better state than you found it: clearer, simpler, tidier, and at least as performant unless the task requires an explicit trade-off.
• Use simple, plain English in user messages, docs, notes, reports, code comments, and other explanatory writing. Avoid jargon, fancy wording, and complex phrasing. When a technical term is needed for correctness, explain it in simple words the first time. Default to short user-facing responses. Think about what the user most wants to know, and lead with that. Do not dump every detail by default. Always include important changes, blockers, verification gaps, and any important assumptions, nuances, principles, or decisions that shaped the work. Add more detail only when the user asks for it or when uncertainty or risk makes it necessary.
• Compound knowledge continuously: keep docs/ accurate and up to date, and promote durable learnings and decisions from work into docs.

Long-task checkpoint cadence

• For any non-trivial task (including long efforts), run recurring checkpoint cycles instead of waiting for a single end-of-task wrap-up.
• At each meaningful milestone with commit-eligible changes, and at least once per major phase, invoke git-commit to create a small logical checkpoint commit once relevant checks are green and repo policy permits commits.
• At the same cadence, invoke organise-docs whenever durable learnings/decisions appear, and prune stale plan/ scratch artifacts.
• If either checkpoint is blocked (for example failing checks or low-confidence documentation), resolve or record the blocker immediately and retry before expanding scope.

Interruption handoff (required for monitored runs)

• Before stopping, switching sessions, or yielding after an interruption, write a concise handoff in plan/handoffs/ or plan/current/notes.md.
• Include:
  • repo/branch under review,
  • run id and run root if launched,
  • latest stage and latest artifact checked,
  • current classification (running, blocked, success-no-delivery, success-with-delivery, anomalous-no-pr),
  • exact next step.
• On repeat invocations, resume from the latest handoff and current run artifacts before considering any rerun.

Terminal state contract (must follow)

The skill is complete only when all of the following are true:

• Objective completion: the requested DeepReview run is launched and monitored from start through terminal outcome, and the terminal artifacts/logs/delivery state have been checked before declaring success.
• Workflow completion: every required workflow step is resolved as done, blocked, or not-applicable, with brief evidence or rationale.
• Step-level terminal completion: each numbered subtask must have explicit completion evidence (artifact, command output, or written rationale) before advancing.
• Verification completion: required checks/validations for this skill are executed, or any unavailable checks are explicitly called out with impact.
• Findings completion (where applicable): report only evidence-backed findings; if no high-confidence critical findings are present, explicitly state that.
• Loop completion: no actionable in-scope next step remains under the current objective.

Terminal state examples (adapt to skill)

• done: preflight passes, DeepReview finishes, the saved run artifacts and logs still support the final story, and the terminal state is classified correctly as PR created, delivery skipped with no deliverable changes, or verified push in yolo mode.
• blocked: repo hygiene, auth, or tool prerequisites still fail after bounded retries; blocker evidence and exact unblock commands are reported.
• not-applicable: remote-delivery follow-up is intentionally skipped when the user asked only for preflight or monitor-only behavior.

Stop only after this terminal contract is satisfied; otherwise continue iterating.

Overview

Run deepreview review against the current repo in monitored text mode, with explicit repo-state preflight, periodic heartbeats while the run is active, and concise artifact reporting after completion. Prefer local-repo mode and let DeepReview infer the current branch from the target repo unless the user asks for a different source branch. Do not stop at child-process exit alone; finish only after the final artifacts, logs, and delivery outcome have been checked and still make sense together.

The local shell defines deepreview() as:

(
  cd "$HOME/repos/me/deepreview" || return 1
  go run ./cmd/deepreview review --mode pr --concurrency 4 --max-rounds 6 "$@"
)

For automation, prefer the bundled launcher instead of relying on interactive shell functions:

• scripts/run_deepreview.py

It runs the underlying go run ./cmd/deepreview review ... --no-tui, sets DEEPREVIEW_CALLER_CWD correctly, stores a local monitor log under plan/artifacts/deepreview/, and emits periodic monitor snapshots while the child process is still running. During active runs, treat round-*/round-status.json, final-summary.md, pr-title.txt, pr-body.md, and run_root/logs/ as first-class evidence, not just the live stdout stream. The launcher also emits explicit [monitor-alert] lines when artifacts suggest intervention may be warranted, such as unreadable round status, severe delivery/log failures, repeated no-progress heartbeats, or recovery-ready delivery artifacts without a confirmed PR URL yet.

Trigger phrases

Use this skill when the user asks for intents like:

• run deepreview on this repo
• deepreview this branch
• start deepreview and monitor it
• watch deepreview while it runs
• rerun deepreview after sync
• preflight deepreview on this repo

Prompt templates

Use these copy-paste templates:

• [$deepreview] run deepreview on the current repo in pr mode, monitor it from launch to finish, keep checking logs and saved artifacts while it runs, and report artifact paths plus the final summary only after the terminal result still makes sense.
• [$deepreview] preflight the current repo for deepreview readiness; do not launch if the branch is dirty or out of sync.
• [$deepreview] rerun deepreview on the current repo with concurrency 6 and max-rounds 3, monitor it from start to finish, keep checking logs and saved artifacts, and summarize the delivery result only after the terminal evidence agrees.
• [$deepreview] run deepreview on the current repo in yolo mode, monitor it from launch to finish, keep checking logs and saved artifacts, and report exactly what was pushed only after the terminal evidence agrees.

Monitoring posture and intervention bar

• Be patient by default; temporary quiet periods or long review stages alone are not intervention-worthy.
• Quiet, retrying, or waiting stages are still active monitoring time, not a reason to stop babysitting the run.
• Accept isolated worker retries, brief inactivity windows, or a single failed round when DeepReview is still making forward progress and artifacts remain usable.
• Maintain a high intervention bar: intervene only when continuing is likely to:
  • waste substantial time by leaving the run stuck with no realistic recovery path, or
  • produce misleading/invalid delivery outcomes because the run state is clearly unhealthy.

Default policy bands for one DeepReview run:

• watch band: temporary inactivity, sparse stage output, or one-off worker restarts with continued forward progress.
• escalation band: repeated inactivity heartbeats, repeated worker restarts, or repeated stage failures where the run may still recover.
• intervention band: deterministic failure, unrecoverable pre-delivery error, or sustained no-progress state with evidence that continuing will not yield a valid result.

Hard-stop override (intervene earlier):

• deterministic auth or tool failure (gh, codex, git, go) that blocks the run from progressing,
• repeated DeepReview inactivity restarts that exhaust its configured restart budget,
• corrupted or unreadable run artifacts that prevent trustworthy status interpretation,
• duplicate concurrent DeepReview runs against the same repo/branch that would create conflicting delivery outcomes,
• pr mode reaching terminal completion without either a PR created: line or an explicit delivery skipped: reason.
• delivery-stage artifacts (pr-title.txt, pr-body.md, final-summary.md) showing enough evidence to recover manually, but the launcher not yet confirming final delivery.

Behavioral guardrails (must follow)

• Proceed without permission for standard in-scope steps (read/scan/summarize/plan/tests/edits/analysis). Ask clarifying questions only when requirements are ambiguous, missing inputs, or a risky decision cannot be inferred. Require explicit approval only for destructive/irreversible actions, executing untrusted code or installers, remote-state changes (push/deploy/publish), or changes outside the repo environment.
• Use the current repo root as the review target unless the user explicitly names another local repo.
• Prefer monitored --no-tui DeepReview runs so progress can be captured and summarized reliably.
• Keep worktree safety strict: DeepReview requires a clean tracked worktree and an upstream-synchronized branch. Do not stash, reset, or auto-commit to satisfy preflight. Use git-sync only when a fast-forward sync is clearly enough to unblock.
• Treat --mode yolo as a higher-risk remote mutation path. Use it only when the user explicitly asks for direct push behavior.
• Verify required tools before launch: go, codex, and gh for pr mode. If gh auth or remote wiring is missing, stop before launch and report the exact blocker.
• Capture a local monitor log under plan/artifacts/deepreview/ when the repo is writable. If that path cannot be created, continue with stdout-only monitoring and call out the missing artifact path.
• Monitor artifacts continuously while the run is active:
  • latest round-*/round-status.json,
  • final-summary.md as soon as it appears,
  • delivery artifacts such as pr-title.txt and pr-body.md,
  • the newest relevant signal under run_root/logs/ (for example inactivity restarts, delivery-stage failures, or watchdog messages).
• After the process exits, keep checking the terminal artifacts/logs until the outcome classification and saved evidence agree.
• When DeepReview stalls or exits non-zero, inspect the run root, latest round-status.json, final-summary.md, and delivery artifacts before concluding what failed.
• Do not treat no PR as a single failure mode. Distinguish:
  • expected no-delivery outcomes (delivery skipped: ... because no deliverable repo changes remained),
  • explicit failure before delivery (run exited before delivery; no push or PR was created.),
  • anomalous PR-mode completion without an explicit PR URL or skip reason.
• On repeated invocations for the same active run, prefer resuming from existing artifacts and logs instead of launching a duplicate run unless the user explicitly asks for a rerun.

Workflow

1. Preflight the target repo.

• Confirm repo root with git rev-parse --show-toplevel.
• Check for tracked local changes with git status --porcelain --untracked-files=no.
• Capture current branch and upstream tracking branch.
• Verify ahead/behind is 0 0 with git rev-list --left-right --count HEAD...@{u}.
• Verify origin exists and resolves to a GitHub-backed remote.
• Verify required tools are available: go, codex, and gh when using pr mode.
• If any prerequisite fails, do not launch DeepReview. Report the exact failing check and the minimal unblock command(s).

2. Prepare local monitor artifacts.

• Ensure the target repo has the standard plan/ layout when the repo is writable.
• Create plan/artifacts/deepreview/.
• Record the monitor log path and the exact launch command.

3. Launch DeepReview in monitored text mode.

• Use python3 skills/deepreview/scripts/run_deepreview.py --repo "<repo-root>".
• Default flags:
  • --mode pr
  • --concurrency 4
  • --max-rounds 6
  • --warmup-seconds 300
  • --warmup-poll-seconds 30
  • --poll-seconds 600
• Let DeepReview infer the source branch from the target repo unless the user explicitly asked for --source-branch.
• Always set DEEPREVIEW_CALLER_CWD to the target repo path because the launcher runs from $HOME/repos/me/deepreview.

4. Monitor while it runs.

• Stream DeepReview stdout/stderr to the terminal and the local monitor log.
• Parse and surface:
  • run id and run root,
  • stage transitions,
  • round counts,
  • latest round decision/reason from round-*/round-status.json,
  • final summary path and delivery status when it appears,
  • latest interesting signal from run_root/logs/,
  • delivery artifacts (pr-title.txt, pr-body.md) once they exist.
• Use a staged default monitoring cadence for token efficiency:
  • first 300s: heartbeat every 30s,
  • after 300s: heartbeat every 600s.
• Emit a concise heartbeat only when no new output appears for the active cadence window.
• Treat quiet, retrying, or waiting periods as active monitoring time while artifacts still show the run is alive.
• Treat launcher [monitor-alert] lines as intervention prompts, not as informational noise. Read the cited artifact state immediately and decide whether the run still has a valid recovery path.
• If the run receives Ctrl+C, forward the interrupt once and wait for DeepReview cleanup.

5. Classify the terminal outcome before taking action.

• Treat these outcomes differently:
  • failure-before-delivery: non-zero exit, explicit failure summary, or run exited before delivery; no push or PR was created.
  • success-no-delivery: explicit delivery skipped: ... reason from stdout or final-summary.md, such as no deliverable repository changes were produced or privacy remediation removed all deliverable repository changes
  • success-with-delivery: explicit PR created: ... in pr mode, or explicit pushed-commits URL in yolo mode
  • anomalous-no-pr: pr mode completed several stages but printed neither PR created: nor delivery skipped:
• Never collapse success-no-delivery into failure. It is a valid terminal state when DeepReview concluded there was nothing safe and deliverable to open as a PR.
• The same success-no-delivery rule applies in yolo mode too. No-delivery is still success when DeepReview explicitly skipped delivery because nothing valid remained to push.

6. Intervention decision.

• Do not intervene for:
  • normal long-running review or execute stages with periodic evidence of life,
  • isolated worker restarts that remain within DeepReview's configured recovery budget,
  • temporary quiet windows where round-status files, logs, or stage output still advance.
• Intervene only when evidence indicates the run is stuck, irrecoverable, or heading toward an invalid delivery result.

7. Intervention workflow (mandatory sequence).

• When intervention is justified, execute this order:
  1. Diagnose the exact stuck or failure mode from stdout/stderr, run root artifacts, and latest round-status.json.
  2. Preserve evidence by recording the run id, run root, latest stage, latest status, and monitor log path.
  3. Prefer in-place recovery over rerun when the run has already produced enough delivery artifacts to finish safely.
  4. Stop only the affected DeepReview run when in-place recovery is not possible, preferably with a single interrupt so DeepReview can clean up its worktrees.
  5. Clean up only run-local artifacts if they would mislead a rerun; never mutate the user's source repo to force recovery.
  6. Implement only high-confidence, in-scope fixes to the blocking condition.
  7. Re-run the relevant preflight or smoke check before launching another DeepReview pass.
  8. Relaunch once the blocker is resolved and continue monitoring from the new run root.

8. Failure and no-PR triage.

• For failure-before-delivery:
  • inspect run_root/logs/, round-*/round-status.json, and final-summary.md if present,
  • capture the latest stage message and the latest round decision/reason,
  • diagnose the blocker before rerunning; do not immediately launch another identical run.
• For success-no-delivery:
  • treat the run as successful but non-delivering,
  • read final-summary.md and the latest round-status.json to understand why DeepReview decided there was nothing deliverable,
  • only rerun if the objective still requires a PR and there is new evidence or a concrete change in repo state that could produce one.
• For anomalous-no-pr:
  • inspect delivery-stage logs under the run root,
  • inspect final-summary.md for any recorded pull-request or commits section,
  • verify with gh whether a PR was actually created despite the missing printed URL,
  • if the delivery branch was pushed and pr-title.txt plus pr-body.md exist, prefer manual recovery:
    • look up an existing PR by delivery branch,
    • if none exists, create the PR from the saved title/body artifacts instead of rerunning the whole review,
  • only mark the run blocked when neither existing-PR lookup nor artifact-based PR creation succeeds.

9. Close out after completion.

• Before reporting success, confirm that the final summary, latest round status, logs, and delivery artifacts tell a consistent story.
• Report:
  • exit code,
  • run id,
  • target repo and source branch,
  • run artifacts path,
  • local monitor log path,
  • final summary path when present,
  • PR URL or pushed-commits URL when present,
  • terminal outcome classification (failure-before-delivery, success-no-delivery, success-with-delivery, or anomalous-no-pr),
  • latest round decision and summary if available.
• If the run failed, include the latest stage, latest round status, and the exact rerun or unblock command.
• If pr mode completed without a PR, explicitly say whether that was an expected no-delivery outcome or an anomalous blocked outcome.
• If the user asked only for readiness or diagnostics, mark remote-delivery follow-up not-applicable.

Script

Use scripts/run_deepreview.py.

Supported arguments:

• --repo <path>: target local repo path. Defaults to the current working directory.
• --mode pr|yolo: delivery mode. Default pr.
• --concurrency <int>: worker count. Default 4.
• --max-rounds <int>: max review rounds. Default 6.
• --source-branch <branch>: explicit source branch override.
• --warmup-seconds <int>: length of the active monitoring warmup window. Default 300.
• --warmup-poll-seconds <int>: heartbeat interval during warmup. Default 30.
• --poll-seconds <int>: steady-state heartbeat interval after warmup while no output arrives. Default 600.
• --artifact-dir <path>: override local log directory. Defaults to <repo>/plan/artifacts/deepreview.
• --preflight-only: run preflight and exit without launching DeepReview.
• --allow-yolo: required when --mode yolo is used.

Recovery behavior:

• In recoverable pr-mode anomalies, the launcher may query gh for an existing PR by delivery branch.
• If no PR exists but the pushed delivery branch and saved PR artifacts are present, the launcher may create the PR directly from pr-title.txt and pr-body.md instead of rerunning DeepReview from scratch.
• While the run is active, the launcher emits [monitor-alert] lines for likely stall or recovery conditions so the operator can intervene before wasting a full rerun.

Verification

• Run python3 skills/deepreview/scripts/run_deepreview.py --help after editing the launcher.
• Run python3 skills/deepreview/scripts/run_deepreview.py --repo "<repo-root>" --preflight-only to verify the launcher and preflight path without triggering remote changes.
• Run the skill validators after editing the skill definition.

Skill composition

When this skill is triggered, compose other skills as needed:

• Use investigate when DeepReview artifacts, delivery state, or log behavior are contradictory enough that the run story is unclear.
• Use verify for focused checks on preflight assumptions, launcher behavior, or delivery evidence before concluding the run is healthy.
• Use organise-docs when a run teaches a durable rule about DeepReview setup, monitoring, recovery, or delivery handling.
• Use git-commit or checkpoint after a verified DeepReview-driven fix when the repo state is commit-eligible.

If there is a conflict, retained-run evidence wins: companion skills should strengthen diagnosis, proof, and durable capture without replacing artifact-backed conclusions with guesswork.

Repeat invocations

• Reuse the same repo target and last-known run root when the user is clearly asking about the same DeepReview run.
• If a prior run already completed and the user asks whether another launch is needed, inspect the existing artifacts first and only rerun when it advances the objective.
• If there is nothing left to do, say so explicitly and stop.