---
name: monolith-review-orchestrator
description: "Monolith-local Diversio PR review harness for deep PR understanding, deterministic worktree reuse/bootstrap, persistent review context across passes, resolved-comment-aware reassessment, backend monty-review handoff, and author-guiding review output."
allowed-tools: Bash Read Edit Glob Grep TodoWrite
---

# Monolith Review Orchestrator

## V1 Scope

Treat this as a narrow v1 harness workflow, not a universal review brain.

Supported v1 scope:

- single PR, or one explicitly linked cross-repo PR pair
- monolith-local execution only
- `status`, `review`, `reassess`, and worker-owned `post` mode
- deterministic worktree reuse/bootstrap
- persistent JSON-first review context plus markdown artifacts
- worker-owned final review publishing: Codex drafts, the worker revalidates,
  and the worker publishes one top-level review plus zero or more inline
  comments atomically when the anchors validate cleanly

Explicitly out of scope for v1:

- generic multi-PR batch posting
- generic unresolved-thread automation without a dedicated helper
- replies to existing review threads or partial inline publication
- repo-agnostic marketplace-style usage outside the Diversio monolith
- broad submodule branch normalization during review prep
- claiming reliable "final status" from comment lists alone

## When To Use This Skill

- The user wants an end-to-end PR review workflow instead of manually driving
  worktrees, submodules, PR context reads, reassessment passes, and GitHub
  posting step by step.
- The review spans one or more monolith submodules such as `backend/`,
  `frontend/`, `optimo-frontend/`, `design-system/`, or `infrastructure/`.
- The user says things like "deeply understand this PR", "check all comments and
  unresolved threads", "reassess after the author pushed updates", or "post the
  final review to GitHub".
- The user wants the agent to manage deterministic review worktrees and keep the
  local monolith state fresh.

This skill is an orchestrator. It does not replace repo-specific review taste.

- For Django4Lyfe/backend slices, invoke `monty-code-review`.
- For GitHub issue/PR metadata and comments, prefer the GitHub plugin/app when
  available; fall back to `gh` only when needed.
- For frontend or other non-backend slices, keep v1 narrower: do deep repo
  reading and synthesis, but do not pretend there is a stable repo-specific
  review adapter unless one actually exists.

## Prerequisites

This skill is monolith-local and should fail fast if these prerequisites are
not met:

- running inside a Diversio monolith checkout or sibling review worktree
- monolith scripts and docs are present
- `uv`, `git`, and `git worktree` are available
- GitHub auth is available if PR metadata or posting is requested
- the agent has permission to create sibling worktrees if bootstrap is needed

If preflight fails, stop and report the missing prerequisite instead of
continuing heuristically.

Deterministic helpers for this skill now live under `scripts/`:

- `scripts/preflight_review_env.py`
- `scripts/resolve_review_batch.py`
- `scripts/prepare_review_worktree.py`
- `scripts/fetch_review_threads.py`
- `scripts/review_state.py`

For the simple "what is each helper for?" explanation, load:
- `references/workflow-helpers.md`

For the deep-understanding, comment-history, and author-guidance protocol, load:
- `references/review-context-protocol.md`

## Modes
Choose one mode early and state it explicitly to the user:

1. `status`
   - Understand the PRs, read discussion history, audit unresolved comments,
     and report current status without doing a fresh full review.
2. `review`
   - Do a full deep review, create/update local review artifacts, and stop
     before posting unless the user asked to post.
3. `reassess`
   - Re-review after new commits, focusing on deltas, prior findings, and still
     open concerns.
4. `post`
   - Draft the latest validated review for worker-owned GitHub publication,
     including inline comments only when the diff anchor is stable enough for
     the worker to validate safely.

If the prompt implies more than one mode, use this order:

`status/review -> reassess if needed -> post`

## Deep Understanding First

This skill is not allowed to jump straight from diff reading to verdict writing.

Before you synthesize status, findings, or posting copy:

- read the PR description, changed files, and material author claims
- read all review comments and replies, including resolved ones when available
- prefer thread-aware GitHub reads when resolution/outdated state matters
- treat resolved threads as context, not noise, and separate thread state from
  legitimacy
- validate what prior reviewers and the author claimed against the current code

## Intake Rules

Ask only for missing information that materially changes execution. Keep the
question block short and grouped in one message when possible.

Gather this data:

- PR set: one PR URL, or one explicitly linked cross-repo PR pair.
- Local execution context for each PR:
  - monolith path or existing worktree path
  - submodule path
  - branch name if already checked out
- desired mode: `status`, `review`, `reassess`, or `post`
- whether the run is read-only or local mutation is allowed
- whether an existing dirty worktree may be reused
- whether tests/builds should run or this is code-reading only
- which PR is authoritative if linked PR verdicts diverge
- whether parallel sub-agents are allowed
- whether GitHub posting is allowed in this run
- if posting is allowed, whether this run is eligible for `COMMENT`,
  `REQUEST_CHANGES`, or `APPROVE`

Default assumptions when the user did not say:

- local mutation: no
- dirty worktree reuse: no
- tests/builds: code-reading only
- GitHub posting: no
- parallel sub-agents: no

Do not ask for information already present in the prompt. Infer obvious things
from the PR URL, local paths, and the monolith repo layout first.

If the user already gave local paths and branch names, prefer reusing them over
creating a new worktree.

## Deterministic Worktree Policy

Load `references/intake-and-worktree-protocol.md` for the exact naming and
reuse rules.

Use the deterministic helpers instead of reconstructing this logic manually
when possible.

Core rules:

- Prefer reusing an existing deterministic review worktree over creating a new
  one.
- `uv run scripts/create_worktree.py` is interactive/TTY-driven, so do not rely
  on it for unattended automation.
- For automated runs, use `git worktree` directly and bootstrap only the review
  batch repos.
- In automated review worktrees, prefer detached refs/commits for the monolith
  and relevant submodules so the workflow does not fight Git branch locks across
  multiple active worktrees.
- If a deterministic worktree path already exists:
  - verify whether Git still knows it as a worktree
  - refresh it safely instead of replacing it
  - never delete or force-reset it unless the user explicitly asks
- If the user points you at an already-prepared worktree, treat that as the
  source of truth and do not silently switch to a different one.

## Execution Workflow

### 1. Normalize The Review Batch

Resolve the batch with `scripts/resolve_review_batch.py` first, then mirror the
result in your notes:

- repo name
- PR number
- local submodule path
- target branch / checked-out branch
- mode
- review artifact path

Map common Diversio repos to monolith paths:

- `Django4Lyfe` -> `backend`
- `Diversio-Frontend` -> `frontend`
- `Optimo-Frontend` -> `optimo-frontend`
- `diversio-ds` -> `design-system`
- `infrastructure` -> `infrastructure`
- `diversio-serverless` -> `diversio-serverless`
- `agent-skills-marketplace` -> `agent-skills-marketplace`
- `terraform-modules` -> `terraform-modules`

If a repo cannot be mapped confidently, ask once.

### 2. Prepare Or Reuse Local State

Run preflight first with `scripts/preflight_review_env.py`.

In the selected monolith root or review worktree:

- confirm current path and git status
- if the worktree is dirty and reuse was not explicitly allowed, stop and ask
- fetch remotes needed for the monolith and relevant submodules
- initialize submodules if needed
- for each relevant submodule:
  - verify the requested branch/ref exists locally or fetch it
  - prefer detached checkout of the remote ref or exact commit under review
    rather than attaching a local branch
  - only attach a local branch if the user explicitly asked for that behavior
  - avoid adjusting repos outside the review batch

Do not use `uv run scripts/update_submodules.py` as routine review prep. That
script enforces monolith branch policy and can mutate unrelated submodules.
Refreshing utility repos is opt-in only.

Use `scripts/prepare_review_worktree.py` for deterministic worktree
create/reuse and safe submodule initialization.

State clearly what you updated and what you intentionally left untouched.

### 3. Gather PR And Comment Context

For each PR:

- read the PR metadata, description, and changed files
- read all review comments, replies, and resolved threads when available
- use `scripts/fetch_review_threads.py` as the default thread-aware acquisition
  path when GitHub auth is available
- identify unresolved threads only when you have a reliable thread-resolution
  source
- cross-check whether each still-open claim is actually legitimate against the
  current code
- note author claims that must be validated against the implementation

Resolved comments are not blockers by default, but they remain part of the
review history and often explain why the current code looks the way it does.
Do not discard that context during review or reassessment.

Do not claim reliable unresolved-thread state from flat comment lists alone.
If `fetch_review_threads.py` cannot be used, call the result provisional.

When the user asked for "final status", explicitly separate:

- what appears fixed
- what is still unresolved
- what looks misunderstood or no longer applicable

### 4. Review Code Deeply

For each PR, inspect:

- business logic and product behavior
- correctness and data/contract invariants
- reuse of existing utilities/helpers/patterns
- tests and regression coverage
- docs or harness gaps that make the change harder to reason about
- what prior reviewers already identified, what changed since then, and whether
  the fix actually addressed the root cause

Backend rule:

- If a PR touches `backend/`, invoke `monty-code-review` for that slice.
- Reuse its review memory protocol when doing a follow-up pass.
- Reuse Monty's backend review taste and memory context when it helps, but keep
  the final GitHub publish step on this orchestrator's worker-owned path.

Non-backend rule:

- Keep v1 to code reading, repo-local pattern checks, and synthesis.
- Do not manufacture Monty-specific Django findings for frontend-only work.
- If a stable repo-specific review adapter does not exist, say so explicitly.

### 5. Use Parallel Agents Carefully

This skill may use multiple agents when the user allows it.

Default to no parallel agents unless the user explicitly asked for parallelism,
delegation, or multiple agents.

Ownership model:

- main agent owns intake, local state management, final synthesis, and the
  final drafted review bundle
- sidecar agents own bounded analysis tasks only

Good parallel splits:

- one PR per agent when multiple PRs are independent
- one agent for backend code/comment analysis and one for frontend code/comment
  analysis in a linked cross-repo change
- one agent for existing review-thread triage while the main agent inspects code

Bad parallel splits:

- two agents preparing competing final review drafts for the same PR
- two agents editing the same review artifact
- delegating the immediate blocker when the main agent needs the answer next

Before spawning, tell the user you are parallelizing and what each agent owns.

### 6. Persist Review Artifacts

Persist structured state first, then render markdown artifacts.

The structured state is the canonical local reassessment identity for this
skill. Markdown is the human-facing artifact.

Minimum identity fields:

- review batch key
- repo
- PR number
- base branch
- head SHA
- merge base
- worktree path
- artifact path
- review pass number
- posting status

Minimum cached context fields for substantive passes:

- latest mode, recommendation, scope summary, repo-scoped stable finding IDs,
  claim checks, structured thread/comment context, teaching points, and inline
  comment targets

Use `scripts/review_state.py` for:

- `init` once per batch
- `summarize-context` before reassessment or posting
- `record-review` after each substantive status/review/reassess/post pass
- `record-pass` only as a compatibility fallback

Create or update deterministic markdown artifacts under a `reviews/` directory
at the monolith root of the chosen worktree unless the user specified another
path.

Use filenames derived from the review batch key, for example:

- `reviews/review-bk2779.md`
- `reviews/review-bk2779-of389.md`
- `reviews/review-bk2779-reassess.md`

Each combined artifact should include:

- review scope and mode
- worktree path used
- PRs reviewed
- current branch per relevant submodule
- current status / final verdict
- open findings grouped by repo
- unresolved prior-review comments that still look legitimate
- prior-review comments that no longer look legitimate
- resolved prior-review comments that still matter for context
- what we learned from earlier review rounds and how the current code supports
  or contradicts that history
- explicit next step: `reassess`, `post`, `approve`, or `request changes`

If `monty-code-review` produced a backend-specific artifact, link or reference
it from the combined artifact instead of duplicating it line for line.

### 7. Posting To GitHub

Only post when the user asked or explicitly confirmed posting.

Phase 2a posting contract:

- Codex drafts one authoritative top-level review body and zero or more inline
  comments.
- Codex does not post the final review to GitHub directly.
- The worker re-checks the live PR summary, unresolved-thread state, and
  top-level review/comment activity immediately before publish.
- The worker validates inline anchors against the current diff.
- The worker publishes one atomic review through local `gh` / `gh api`, or
  publishes nothing if the stale-input or anchor checks fail.
- Replies to existing review threads and partial inline publication are still
  out of scope.

Drafting rules for `post` mode:

- one authoritative top-level review per PR
- inline comments only for distinct root-cause findings with genuinely stable
  diff anchors
- prefer single-line `RIGHT`-side anchors when possible
- use multi-line anchors only when the diff location is unambiguous
- if an anchor is uncertain or likely to drift, fold that point into the
  top-level review body instead
- avoid duplicate comments against already-open reviewer threads
- explain why a prior unresolved comment is still valid, or why it is now moot
- explain when a resolved comment shaped the current assessment or fix
- top-level review should teach, not just label, by explaining the issue, why
  it matters, and the concrete next step
- inline comments should anchor one root-cause cluster each and include risk and
  actionable guidance
- approve only when there are no legitimate blocking issues remaining
- if not approving, provide clear options and next steps

For linked PRs, keep the reviews coordinated:

- mention cross-repo dependencies
- do not approve one side if the other side blocks the behavior end to end

## Output Contract

While running:

- narrate the workflow in short step updates
- tell the invoker when you are doing intake, local-state prep, comment audit,
  deep review, reassessment, or posting
- surface material assumptions before they matter

Final response should include:

- mode executed
- worktree path used or reused
- PRs reviewed
- final status per PR
- remaining legitimate unresolved comments
- how resolved-comment history affected the current verdict when it mattered
- whether a GitHub review was posted, and if so whether it was approval or
  changes requested

## Reassessment Rules

When the user says the author pushed changes and wants another pass:

- reuse the existing review worktree if possible
- fetch latest refs and verify the tracked review refs are current
- load the structured review state first with `summarize-context`
- compare against the prior structured state and linked artifact
- identify commits since the prior review
- re-check every previously material finding
- do not assume a comment is resolved just because code moved
- do not drop prior open findings unless you explicitly record them as resolved
  or moot
- keep resolved-thread context in view when it explains the author’s fix
- do not repeat already-resolved nits unless the regression reappeared

The reassessment summary must distinguish:

- newly resolved
- still open
- newly introduced

## Non-Negotiables

- Never hard-reset, delete, or recreate a user worktree without explicit approval.
- Never post GitHub comments from sidecar agents.
- Never approve a PR while simultaneously documenting legitimate blocking issues.
- Never treat an unresolved thread as valid without checking the current code.
- Never treat a resolved thread as safe without checking whether the underlying
  issue was actually fixed.
- Never ignore resolved review threads when they explain current code or prior fixes.
- Never drop a prior open finding from memory unless you mark it resolved or moot.
- Never post vague review comments that fail to explain risk and the next step.
- Never let one PR's finding or inline target overwrite another PR's context in a
  linked cross-repo batch.
- Never use `uv run scripts/update_submodules.py` as a default review refresh.