Agent Work Reviewer Maintainer

Agent Work Reviewer Maintainer

Review completed or in-progress Rudder agent work. This is a reviewer workflow, not an implementation workflow.

The core question is:

Did the agent solve the right product problem, with the right object model, complete behavior, credible validation, and a clean handoff?

Reviewer is not the same role as verifier. Reviewer may inspect the running product when that is needed for judgment, but its durable responsibility is to judge the diff, architecture, scope, test strategy, handoff safety, and the credibility of acceptance evidence. For black-box acceptance of final product behavior, use product-acceptance-verifier-maintainer.

Default to Chinese when the user asks in Chinese. Keep the verdict early and ground every judgment in evidence.

Use When

Use this skill when the user asks to review:

• a Codex session, Rudder agent run, task, or transcript
• a local branch, commit, diff, pull request, or implementation
• a product proposal, plan doc, feature spec, or UI direction
• a release verification, Desktop install path, npm publish, or canary/stable handoff
• a screenshot, browser state, visual interaction, or workflow that "feels wrong"

Common trigger phrases:

• "review 一下 codex session id ..."
• "as a 专业产品经理 review"
• "第一性原理思考一下"
• "作为 reviewer"
• "这个实现是不是产品上对"
• "这个 PR 本地跑起来看一下有没有问题"
• "这次 release 验证做完了吗"
• "我觉得这个功能之前有，现在没了"

Do Not Use When

Do not use this skill for:

• fixing the findings during the same reviewer pass, unless the user explicitly asks to implement fixes
• generic line-by-line code review where product judgment is irrelevant
• debugging a failed Rudder agent run root cause only; use the run transcript debugging workflow first, then return here for product/workflow judgment
• summarizing logs without verdict or acceptance criteria

If the user asks to fix findings after the review, switch to normal implementation mode and follow repository validation, commit, and push rules.

Read-Only Guard

Reviewer mode is read-only by default. Do not edit files, stage changes, restore files, commit, push, start destructive cleanup, or "just fix" findings while reviewing unless the user explicitly changes the task from review to implementation.

If the user says "do not implement", "review only", or assigns a reviewer role, that instruction is binding for the whole reviewer pass. Use tools only to inspect evidence.

Direct UI inspection with Browser, Desktop, or Computer Use is still reviewer work when it only observes or exercises low-risk local/dev flows. If a realistic scenario requires mutating Rudder data, prefer an isolated dev org, disposable test records, or an existing preview instance, and report what was created or changed. Do not delete data, publish, submit external communication, install software, change system settings, or perform other risky UI actions without the appropriate user confirmation.

Evidence Packet

Never start with opinion. Build the smallest evidence packet that can support a real judgment.

1. Identify The Target

Resolve what is being reviewed:

• Codex session id or prefix
• Rudder run id or transcript
• PR number or URL
• branch name, commit hash, staged/unstaged diff
• plan doc, proposal, screenshot, or browser URL
• release version, tag, workflow run, npm dist-tag, or Desktop asset set

If the user is vague, infer from current branch, recent commits, open browser state, or named files before asking.

2. Collect Task Intent

For Codex sessions, search:

rg "<session-id-or-prefix>" ~/.codex/session_index.jsonl ~/.codex/sessions ~/.codex/archived_sessions

Extract real user requests and corrections. Ignore injected AGENTS.md, environment context, skill bodies, and system/developer text.

For branches, PRs, commits, or diffs, inspect:

git status --short --branch
git log --oneline --decorate -12
git diff --stat
git diff
git show --stat <commit>
git show <commit>

For commit or session reviews, also compare the changed-file set against the stated task. Classify every surprising file as one of:

• required for the requested behavior
• test, docs, or contract evidence for the requested behavior
• pre-existing unrelated dirty work
• unrelated change mixed into the reviewed commit or handoff

Unrelated changes mixed into a product fix are review findings, not cleanup details. If they change skills, release state, generated files, dependencies, or broad runtime behavior outside the task, usually treat that as at least a conditional accept blocker until the scope is split or justified.

For PRs, read the PR description, changed files, review comments, and CI status when available.

3. Read Product Context

For most Rudder product work, read only the relevant sections of:

• doc/product/GOAL.md
• doc/product/PRODUCT.md
• doc/product/README.md plus relevant doc/product/domains/**
• doc/engineering/DESIGN.md for visible UI and interaction work
• the task's plan doc under doc/plans/ when one exists

For release/Desktop/package work, also use:

• doc/engineering/RELEASING.md
• doc/engineering/PUBLISHING.md
• doc/engineering/DESKTOP.md
• .github/workflows/release.yml
• .github/workflows/desktop-release.yml

For database/API behavior, check the cross-layer contract:

• packages/db
• packages/shared
• server
• ui

4. Verify What Was Proven

Separate "implemented" from "proven".

Also separate author-claimed proof from reviewer-verified proof.

author-claimed proof includes validation listed in the prompt, final handoff text, copied terminal output, screenshots the reviewer did not inspect, and test names the implementer says were run.

reviewer-verified proof includes commands, logs, screenshots, browser/Desktop state, API readbacks, git evidence, CI state, or release surfaces that this reviewer actually inspected during the review pass.

Do not convert author-claimed proof into reviewer-verified proof. It can support the review, but it cannot close a final handoff gap for UI, workflow, release, Desktop, runtime, or product behavior when the reviewer could cheaply verify the real surface.

Record which evidence exists:

• typecheck, unit tests, build
• E2E tests or release smoke tests
• browser or Desktop visual verification
• screenshots for visible UI
• packaged Desktop verification for startup, migrations, profile routing, or installer changes
• npm/GitHub Release/live workflow checks for release tasks
• commits, pushes, branch state, PR URL, and merge state

Treat timed-out, skipped, or attempted checks as unverified. Do not convert "looked plausible in code" into product proof.

For spawned child reviewers, full-history forks may include the parent agent's prior commands, screenshots, tests, or edits. Treat inherited history and prompt claims as author-claimed proof unless the child reviewer performs or explicitly re-inspects the evidence after the review assignment starts.

When reviewing in-progress work, spawned reviewer child sessions, or a branch with unrelated dirty feature groups, use a mixed-state verdict instead of a binary pass/fail. Examples:

• accept: no blocking product, behavior, validation, or handoff gaps remain for the requested scope and verdict level.
• conditional accept: the artifact direction is sound, but merge/handoff is blocked by missing proof, unrelated dirty work, or explicit reviewer follow-up.
• needs more evidence: the required scenario, diff, source data, or validation is not available enough to judge.
• reject: the artifact solves the wrong problem or introduces a blocking regression.

Every verdict must declare its level:

• stage verdict: judges whether the current requirements, proposal, design, implementation slice, or review artifact is good enough to proceed to the next stage.
• final handoff verdict: judges whether the requested work can be accepted as done, merged, released, or handed to the user with no blocking evidence gap.

Do not let a stage accept read like a final handoff. If terminal product proof, commit/push state, public release evidence, or reviewer follow-up is still missing, the final verdict cannot be accept even when the stage verdict is positive.

For child-reviewer outputs, preserve the parent task boundary. Do not turn the review into implementation and do not judge sibling or unrelated dirty work as part of the artifact unless it affects merge/handoff safety.

4.1 Evidence Freshness Guard

Before writing the verdict, state the evidence baseline being reviewed. This prevents repeated reviewer child sessions from re-judging stale or mismatched artifacts.

Include the relevant subset:

• target id: session, run, PR, commit, branch, diff, proposal, release, or screenshot
• git basis: current branch and commit SHA, plus whether the worktree is dirty
• diff basis: changed files or git diff --stat scope inspected
• artifact basis: plan/proposal/screenshot/log path and timestamp when relevant
• validation basis: checks, browser/Desktop evidence, CI, release workflow, or product proof actually inspected
• proof split: which evidence was author-claimed versus reviewer-verified
• review round: first pass, delta review, second round, or final review

If a prior reviewer already judged the same target, same git SHA, and same artifact basis, run a delta review against the changed evidence instead of repeating the full review. If there is no changed evidence, say that the prior verdict still applies and name the missing proof instead of producing a fresh confident verdict.

For spawned reviewer or sub-review work, explicitly say which artifact is being reviewed. Do not silently upgrade the scope from "this proposal" or "this diff" to the whole dirty worktree.

4.2 Run The Real Scenario When It Matters

For functional review, UI review, Desktop review, agent-visible workflow review, or workflow-regression review, prefer direct scenario verification over code-only inference:

• Use Browser for local web targets such as localhost, 127.0.0.1, or file previews when the browser can exercise the path.
• Use Computer Use for the packaged Rudder Desktop app, native dialogs, update prompts, menus, resident shell behavior, drag/drop, or any flow that is only visible in the local Mac UI.
• Use API/log/database checks as supporting evidence, not a replacement for the real operator path when the user's question is about behavior.
• For CLI or runtime-agent changes, ask whether the actor that will use the feature actually exercised it. A realistic proof usually includes a disposable org/issue/agent or equivalent fixture, the actor command or wakeup, persisted issue/run/comment readback, and the terminal app or CLI surface.
• If the app is not running, start the appropriate local or packaged Rudder path when that is safe and within the review scope. If startup would be expensive or risky, say exactly why the review is limited.
• When a real scenario is skipped, the verdict should usually be needs more evidence or conditional accept, and the missing scenario must be named.

For user-visible work, do not accept "tests pass" as enough proof when Computer Use or Browser could cheaply verify the actual Rudder interaction. The minimum credible evidence is the observed workflow state plus any relevant logs, API responses, screenshots, or failure messages.

If the reviewer does not personally inspect the rendered or interactive state for a layout-sensitive UI or functional workflow, the final handoff verdict cannot be accept. Use conditional accept for a sound implementation slice, or needs more evidence when the missing scenario is required to judge the change.

For agent-visible or Rudder work, do not accept direct database assertions, unit tests, or docs updates as the whole proof when a realistic actor-run-chain could cheaply exercise the behavior. Missing terminal product proof should usually make the verdict conditional accept or needs more evidence, even if the diff itself looks correct.

If the user explicitly says the reviewer can use Computer Use or Browser to test a real scenario, treat that as part of the review assignment. If direct scenario verification is skipped or blocked, the verdict should normally be conditional accept or needs more evidence, and the missing interaction must be named.

When the work is already in a routed lifecycle that requires acceptance verification, do not let reviewer scenario checks replace the verifier gate. The review should ask whether a distinct verifier result exists, whether it is PASS, FAIL, or QUESTION, and whether the verifier evidence actually matches the user's acceptance criteria. A reviewer can reject or qualify weak verifier evidence, but should not convert a missing or failing verifier pass into final acceptance.

5. Assemble The Review Packet

Before writing the verdict, make the review packet explicit. It should include the relevant subset:

• target: session, run, PR, branch, commit, diff, proposal, screenshot, release, or browser state
• evidence baseline: git SHA/branch, dirty state, diff scope, artifact timestamp, and review round when available
• user intent: original request plus important corrections or constraints
• changed object: the product/workflow/code object being reviewed
• evidence inspected: files, diffs, logs, screenshots, docs, plans, tests, CI, browser/Desktop state, release artifacts, or sub-reviewer notes
• proof split: author-claimed proof versus reviewer-verified proof
• verifier status: verifier result, evidence packet, and whether acceptance proof was distinct from code review when required
• validation status: what passed, what failed, what timed out, what was skipped, and what was only inferred
• product proof status: actor, trigger, system effect, terminal surface, and any seed/mutation records created for the review
• unresolved evidence gaps: missing screenshots, missing E2E, unchecked downstream consumers, branch/CI uncertainty, or unverified public surfaces

If any packet item needed for a trustworthy judgment is missing, use needs more evidence or conditional accept; do not fill the gap with confidence.

First-Principles Review Frame

Use this frame before writing the verdict.

1. User Job

What real operator or contributor problem was this task supposed to solve? Was the request a symptom of a deeper workflow issue?

Examples:

• "Move recent views" may really mean navigation history was modeled as content.
• "Where did my draft issue go" is a lifecycle and recovery problem, not just a sidebar rendering bug.
• "Calendar blocks are unreadable" is a time-density visualization problem, not a card styling problem.

2. Product Object Model

Identify the object being changed:

• view or navigation shortcut
• workflow state
• draft, issue, goal, project, run, or artifact
• external source
• preference or setting
• release/version/install surface
• agent memory, instruction, skill, or operating contract

Judge whether the implementation modeled it as the right kind of object. Many Rudder regressions come from treating a workflow state as a static view, a setting as content, or an external source as an imported local object too early.

3. Core Loop Impact

Ask how the work affects Rudder's north-star loop: real agent work completed end to end.

Good changes reduce operator friction, clarify agent state, preserve control, or make review and handoff easier. Weak changes add surface area without making the agent-work loop more controllable.

4. Scope Discipline

Check whether the work:

• preserved organization scoping and permissions
• reused existing product concepts instead of inventing new ones
• removed half-built surface area when deletion was the right product move
• preserved legacy paperclip* compatibility where required
• avoided hiding complexity behind vague copy or fake affordances
• respected the user's explicit corrections during the session

5. Behavioral Completeness

For user-visible work, inspect the important states:

• empty, normal, long, loading, error
• direct link, sidebar link, board card, detail page, and modal entry points
• cross-organization behavior
• mobile or constrained width when relevant
• legacy links and previously shipped features

For UI and functional reviews, ask whether the actual rendered or interactive state was seen. Code review alone is not enough for layout-sensitive work, native Desktop behavior, update flows, chat/issue workflows, or any path where the product claim depends on clicks, typing, selection, focus, async state, or cross-page navigation.