monolith-review-orchestrator

What this skill does

# 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