# Agent Work Reviewer Maintainer

> Use when reviewing Rudder agent work, Codex sessions, PRs, commits, UI, releases, regressions, proposals, or agent outcomes for product correctness, evidence quality, scope, architecture, and handoff trust.

- Skill: `undertone0809/agent-work-reviewer-maintainer-2` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add undertone0809/agent-work-reviewer-maintainer-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/undertone0809/agent-work-reviewer-maintainer-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: undertone0809 (https://skillmd.com/u/undertone0809)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/undertone0809/agent-work-reviewer-maintainer-2

---


# 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:

```bash
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:

```bash
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.

### 6. Trust And Validation

The user is often asking "can I trust this agent work?" Answer that directly.

Look for:

- validation mismatch: tests pass but do not cover the operator path
- regression risk: a refactor deleted a previous capability
- release mismatch: npm, GitHub Release, Desktop assets, tags, and public entry
  points disagree
- branch mismatch: work landed somewhere but not on `main`
- handoff mismatch: URL exists but screenshot or real flow evidence is missing
- hygiene mismatch: the implementation artifact is plausible, but unrelated
  dirty files, child-session duplication, or pending validation means it cannot
  be safely merged or handed off as complete

## Multi-Round Review

When reviewing a proposal, plan, or agent output across multiple rounds, keep a
blocker ledger instead of relying on memory or tone.

Use this shape when it is useful:

```markdown
Blocker ledger:
| blocker | severity | round-one evidence | revised answer | status |
| --- | --- | --- | --- | --- |
| ... | P1 | ... | ... | resolved / unresolved |
```

Second-round review must judge each prior blocker explicitly. An `accept`
verdict means no unresolved blockers remain for the requested scope; it does not
mean the proposal is fully implemented or validated.

For reviewer-loop orchestration, disclose whether the review used real spawned
reviewers or a serial two-role fallback when that distinction affects trust.

## Lens-Specific Checks

### UI/UX And Design

- Read `doc/engineering/DESIGN.md` before judging.
- Verify rendered states with Browser, screenshot, Desktop shell evidence, or
  Computer Use against the real packaged app when native behavior matters.
- For alignment, row rhythm, avatar/text/time centering, truncation, or
  column-layout reviews, require production-shaped fixture data and measurable
  proof when practical. Strong evidence includes real agent avatars, long labels
  or message text, timestamps/action controls, a screenshot, and DOM bounding
  boxes or centerline deltas for the elements being aligned.
- Treat visual hierarchy, density, interaction feedback, animation, native app
  affordances, and copy clarity as product quality, not nitpicks.
- Check whether menus, hover actions, dialogs, keyboard behavior, and icons match
  expected Rudder patterns.
- If no visual evidence exists, the verdict should usually be `needs more
  evidence` or `conditional accept`.
- If the claimed fix is "aligned" but the proof only uses placeholder data,
  isolated component tests, or screenshots that hide the relevant avatar,
  timestamp, action, or long-text state, the verdict should usually be
  `conditional accept` until the real row shape is verified.

### Functional Workflow Review

- Reconstruct the user's real scenario as a short workflow, then run it when
  the local app, preview, or packaged Desktop is available.
- Prefer scenario steps such as "open Messenger, send a message, approve the
  proposal, confirm the issue state" over isolated API calls when the behavior
  is operator-facing.
- Use API, logs, DB rows, and code paths to explain why the observed behavior
  happened after the UI behavior is known.
- If the scenario would mutate shared or production-like data, use a disposable
  dev record or ask before the risky step. State any mutation in the review
  packet.
- A functional verdict should separate observed user behavior from inferred
  internal correctness.

### Release And Desktop

- Confirm the relevant version, git tag, npm dist-tag, GitHub Release assets,
  Desktop portable assets, and install command.
- For Desktop startup, migrations, profile routing, installer assets, or
  prod-local paths, packaged verification is required before calling it done.
- A dry-run does not prove public install. Say exactly which platform and
  command were actually verified.

### Git, PR, Branch, And Worktree

- Confirm where the change landed and whether it was pushed.
- If the user expected `main`, verify `main` contains the commit.
- Distinguish the user's unrelated dirty work from the reviewed changes.
- Check commit hygiene: the changed files should match the requested product
  object, tests/docs for that object, and necessary contracts. Flag mixed
  unrelated edits, accidental skill renames, version bumps, generated artifacts,
  or broad dependency churn inside narrow fixes.
- When reviewing a Codex session, do not rely only on the final summary saying
  "committed and pushed"; verify the commit or diff when the local repo is
  available.
- For PR preview work, check whether the app was started in an isolated worktree
  and whether the user received a URL plus screenshots when UI changed.

### Agent Skill Or Operating Contract Work

- Check trigger description, expected workflow, bundled references/scripts, and
  eval prompts.
- Verify that repo-local development and maintenance skills use the
  `*-maintainer` suffix and live under `.agents/skills/maintainer/`.
- Check whether the skill preserves the user's actual repeated corrections
  rather than only encoding generic best practices.
- Prefer eval prompts drawn from real Rudder tasks.

## Output Shape

Keep the review compact. Lead with the verdict.

```markdown
结论：conditional accept。

评分：7/10。

证据基础：
- Session/commit/PR: ...
- Inspect: ...
- Validation: ...
- Gaps: ...

这次任务本质上是在解决：...

做对的地方：
- ...

关键缺口：
1. ...
2. ...

必须补的证据：
- ...

Blocker ledger:
- ...

下一步建议：...
```

Use `accept`, `conditional accept`, `reject`, or `needs more evidence`.

Only add line-anchored review findings when they are useful. In Codex app
contexts, use `::code-comment{...}` for concrete file/line findings and keep the
line range tight.

## Judgment Rules

- A task can be directionally correct and still not be done.
- A stage can pass while final handoff is still blocked.
- Passing typecheck/build does not prove product behavior.
- A visible UI task is not done without rendered-state evidence.
- A release task is not done until npm, tags, GitHub Release, Desktop assets,
  and public install entry points agree for the intended release surface.
- Multi-message sessions are not automatic failures; they may be intentional
  product iteration. Treat repeated corrections as evidence of where the review
  bar should be raised.
- "Implemented" means code or docs changed. "Accepted" means the right behavior
  was proven for the relevant user path.
- Prefer one pragmatic next move over a long wishlist.

## Validation Cases

### Case: Two-Round Proposal Review

Input:
"Review this proposal as Reviewer A. Do not implement." Then later: "Round 2
review. Judge whether this revised proposal resolves your round-one blockers."

Expected behavior:
Round one produces a verdict plus blocker ledger. Round two explicitly checks
each blocker against the revised proposal and marks it resolved or unresolved
before giving the final verdict.

Must not:
Edit files, skip the blocker ledger, or say `accept` without showing why prior
blockers were closed.

### Case: Functional Review Of A Shipped Workflow

Input:
"功能性上 review 一下 reviewer routing，现在是不是产品上对？"

Expected behavior:
The review starts from user intent and workflow semantics, then traces every
downstream consumer of the relevant object or field, such as attention, filters,
wakeups, UI state, and recovery paths. When Rudder is available locally, it also
uses Browser or Computer Use to exercise the real operator path or clearly names
why live scenario testing was skipped. The verdict separates observed semantic
behavior from schema/type correctness.

Must not:
Stop after checking schema, route validation, or the obvious happy-path test.

### Case: Functional Review With Computer Use

Input:
"review 一下最新版 Desktop update 为什么失败，功能上是不是已经好了."

Expected behavior:
The review inspects release and code evidence, then uses Computer Use or an
equivalent packaged Desktop run to exercise the actual update interaction when
safe. It reports the observed app version, update channel, prompt/toast state,
and any supporting health/API/log evidence before judging whether the function
is proven.

Must not:
Call the update flow accepted from release assets or code inspection alone when
the packaged Desktop scenario can be tested.

### Case: UI Review Without Rendered Evidence

Input:
"review 一下这个 UI 改动有没有问题." The diff is available, but no screenshot,
browser state, or Desktop state was captured.

Expected behavior:
The review can comment on code and likely risks, but the verdict is
`conditional accept` or `needs more evidence` if layout, dark/light behavior,
overflow, hover, dialog, or responsive state matters.

Must not:
Call a layout-sensitive UI change fully accepted from code review alone.

### Case: Alignment Review With Placeholder Proof

Input:
"这里行对齐没有做好. Review the fix." The submitted proof includes a component
test with placeholder icons but no real agent avatar, no timestamp, and no
browser geometry or screenshot of the production row.

Expected behavior:
The review treats the fix as directionally plausible but not fully proven. It
asks for production-shaped fixture proof, ideally a browser screenshot plus DOM
bounding boxes or centerline deltas for avatar, text, timestamp, and row
container.

Must not:
Accept the alignment fix as final from placeholder component tests or a cropped
screenshot that does not show the elements whose alignment was questioned.

### Case: Explicit Review-Only Guard

Input:
"Use agent-work-reviewer-maintainer. Review this proposal. Do not implement or
edit files."

Expected behavior:
The reviewer inspects evidence and returns a verdict, findings, blocker ledger
when useful, and next evidence/fix recommendations. It performs no write action.

Must not:
Patch files, stage changes, commit, push, or run destructive cleanup.

### Case: Author-Claimed UI Proof Is Not Reviewer Proof

Input:
"Review this UI workflow. The implementer says Playwright passed and a
screenshot was captured, but you have not opened the app or inspected the
screenshot yourself."

Expected behavior:
The review may use the claimed checks as supporting context, but it labels them
as author-claimed proof. If Browser, Computer Use, screenshot inspection, or a
current local preview is available, the reviewer either verifies the real UI
state or returns `conditional accept` / `needs more evidence` for final handoff.

Must not:
Give a final `accept` by repeating the implementer's claimed Playwright,
screenshot, or dev-server evidence as if the reviewer personally verified it.

### Case: Spawned Reviewer Full-History Contamination

Input:
"You are a spawned reviewer. The inherited transcript includes the author's
tests, screenshots, and edits before your assignment. Review the current diff."

Expected behavior:
The review treats inherited commands and prompt-provided validation as
author-claimed proof unless it reruns or re-inspects them after the review task
starts. The verdict says exactly which proof was reviewer-verified and which
was inherited.

Must not:
Count pre-assignment parent commands as reviewer-verified evidence or call a UI
workflow fully accepted from inherited proof alone.