undertone0809/rudder/advisor-review-loop-maintainer

Advisor Review Loop Maintainer

This skill chains existing Rudder maintainer practices:

• build-advisor: turn fuzzy dissatisfaction or a high-stakes request into a

grounded scenario analysis, requirement map, options, and recommended plan.

• agent-work-reviewer-maintainer: independently judge whether the result

solved the right product problem with sufficient behavior, evidence, and validation.

• product-acceptance-verifier-maintainer: when the loop evaluates delivered

product behavior rather than a proposal artifact, prove black-box acceptance before final review.

Use this skill when the work should not be accepted after one author pass. The goal is to create a reviewable proposal or implementation, expose it to independent pressure, revise it, and only hand off once the remaining risk is explicit.

When to Use

Use this skill for Rudder development tasks where the user asks for any of:

• Build Advisor followed by reviewer agents
• first-principles product, scenario, or requirement analysis that must pass

independent reviewers, repeated review rounds, or an explicit acceptance gate

• deep corner-case coverage before implementation or handoff
• two review iterations before the final answer
• "no pass, keep reworking" behavior
• review of a plan, skill, workflow, feature, UI, architecture, release

verification, or completed agent task where correctness depends on product judgment and an acceptance gate

Do not use this skill for a narrow bug fix, simple command, ordinary code review, direct release execution, or a generic first-principles advisory task where the correct specialized skill can execute directly.

If the user explicitly names this skill for a narrow screenshot-driven UI fix but does not ask for reviewer agents, repeated rounds, "no pass then rework", or an acceptance gate, use the lightweight route:

1. Do a short advisor check to confirm the UI problem and non-goals.
2. Hand the implementation to rudder-ui-polish-maintainer discipline.
3. Report that this was a lightweight advisor route, not a full reviewer loop.

Do not spend a full two-reviewer loop on small color, spacing, label, icon, badge, menu-position, or redundant-wrapper fixes unless the user explicitly asks for that review bar.

Inputs

Resolve these before starting:

• Target artifact: proposal, plan doc, skill, code diff, PR, commit, release,

UI state, transcript, or workflow.

• Requested mode: proposal-only, implementation, review-only, or

proposal-then-implementation. Treat "给你 new worktree", "自己做实验", "把这个问题解决", "try harder", or equivalent escalation after prior advice as experiment/implementation mode unless the user explicitly says proposal-only.

• Evidence source: repo files, docs, screenshots, logs, traces, commits,

branches, PRs, eval outputs, or user-provided artifacts.

• Review bar: what must be true before the result can be accepted.

If the user is explicit, infer reasonable defaults and proceed. Ask only when the target artifact or requested mode cannot be determined safely.

Respect review-only strictly. In review-only mode, produce the advisor frame, review findings, verdicts, and smallest changes needed, but do not edit files, rewrite the artifact, or continue into implementation unless the user explicitly asks for rework after seeing the findings.

When the user escalates from architecture discussion to a new worktree or asks the agent to experiment and solve the issue, stop repeating the advisory answer. Reclassify the loop as proposal-then-implementation or direct implementation:

• rebuild branch and dirty state in the provided worktree
• identify the falsifiable hypothesis from the advisor pass
• run the smallest experiment that can prove or disprove it
• implement the fix only after the experiment points to a concrete change
• review the actual diff and validation evidence, not the earlier proposal
• commit and push only scoped files for the solved task

When the conversation resumes after a turn_aborted, /goal, or a long-running implementation checkpoint, rebuild the current state before continuing:

• inspect branch and dirty state
• identify partial commits, merge/conflict state, and running verification
• restate the remaining task list and proof still missing

Do not assume the previous turn finished cleanly just because the next user message says to continue.

Default Workflow

1. Build the evidence packet

Collect the smallest set of evidence that can support real judgment:

• repo instructions and relevant docs
• current branch, dirty state, commits, PRs, or target files
• existing plans, specs, screenshots, traces, or eval results
• the two source skills when this workflow depends on their contracts:

.agents/skills/build-advisor/SKILL.md and .agents/skills/maintainer/agent-work-reviewer-maintainer/SKILL.md

• .agents/skills/maintainer/product-acceptance-verifier-maintainer/SKILL.md

when the artifact is delivered behavior that needs black-box acceptance

For Rudder product or workflow work, read the relevant subset of doc/product/GOAL.md, doc/product/PRODUCT.md, doc/product/README.md plus relevant doc/product/domains/**, and doc/engineering/DESIGN.md when UI is involved.

Keep the packet focused. Do not scan the whole repository just to look busy.

2. Run the advisor pass

Follow the build-advisor discipline before drafting or accepting the target:

• reframe what the user is actually trying to accomplish
• diagnose the primary layer of the problem
• map actors, lifecycle states, intents, and failure modes
• collapse scenarios into requirement classes
• identify non-goals and boundaries
• cover corner cases that could change the design
• define a concrete evaluation rubric
• compare realistic options
• expand the recommended option into a decision-ready artifact

Do not claim literal "100% certainty." Instead, state the coverage boundary: what scenarios were considered, what evidence supports them, and what new evidence would change the conclusion.

3. Choose reviewer lenses

Reviewer count follows risk, not habit.

Use three distinct reviewer lenses for consequential proposals, workflow changes, skills, agent-visible contracts, UI/product journeys, architecture, release readiness, Desktop/runtime/CLI decisions, prior failed handoffs, or any task where the user explicitly asks for adversarial or heuristic pressure:

• functional trust: contracts, evidence, validation, org scoping, Rudder

invariants, implementation feasibility, and handoff trust

• adversarial: hidden assumptions, wrong abstraction level, weak proof,

overfitting, conflicting docs, untested actor paths, and product-wrong outcomes

• heuristic/product-systems: whether this is the right problem, smallest

durable slice, missing actor journey, teachable contract, second-order consequences, and future maintenance shape

For narrow proposal review, mechanical skill/doc changes, or low-risk non-product artifacts, two reviewers are acceptable only when one owns functional trust and the other is explicitly adversarial or heuristic. Record which lens was omitted and why.

If the artifact is delivered product behavior rather than an advisory/proposal artifact, run or route black-box acceptance through product-acceptance-verifier-maintainer before final reviewer acceptance. A reviewer verdict does not convert missing acceptance proof into product proof.

4. Spawn independent reviewer agents

When subagents are available and the user asked for reviewer agents, spawn the selected reviewers in the same turn so they evaluate independently. Record the review execution mode as spawned reviewers.

Functional trust reviewer:

Use .agents/skills/maintainer/agent-work-reviewer-maintainer/SKILL.md.
 
Review this artifact as the functional trust reviewer. Focus on contracts,
evidence, validation, org scoping, product invariants, implementation
feasibility, rollback/recovery, and handoff trust. Separate author-claimed proof
from proof you inspected. Give accept / conditional accept / needs more
evidence / reject, blocking gaps, and the smallest changes needed to pass.

Adversarial reviewer:

Use .agents/skills/maintainer/agent-work-reviewer-maintainer/SKILL.md.
 
Review this artifact as the adversarial reviewer. Try to break the framing,
requirement map, evidence, and proposed execution. Focus on hidden assumptions,
wrong abstraction level, path dependence, weak proof, overfitting to examples,
conflicting docs, untested actor behavior, and product-wrong outcomes. Give
accept / conditional accept / needs more evidence / reject, blocking gaps, and
the smallest changes needed to pass.

Heuristic/product-systems reviewer:

Use .agents/skills/maintainer/agent-work-reviewer-maintainer/SKILL.md.
 
Review this artifact as the heuristic/product-systems reviewer. Judge whether
the work solves the right problem in the smallest durable way. Focus on missing
actor journeys, better questions, teachable contracts, future-proofing path,
second-order consequences, and whether a narrower or different slice would
better serve Rudder's agent-work loop. Give accept / conditional accept / needs
more evidence / reject, blocking gaps, and the smallest changes needed to pass.

Include the same evidence packet, target artifact, user request, and evaluation rubric in each prompt. Also include the target artifact basis, prior blockers, changed evidence since the last round, and whether this is a stage review or a final handoff review. Tell reviewers they are not implementers; they should judge and identify gaps.

If subagents are unavailable, distinguish two cases:

• When the user explicitly required spawned reviewer agents, repeated reviewer

rounds, or an acceptance gate, record blocked: spawned reviewers unavailable. You may still provide an advisor artifact and local validation evidence, but do not call the review gate passed unless the user explicitly lowers the bar for this turn.

• When the task only needs advisory pressure and the user did not require a

spawned-reviewer gate, you may run the selected lens reviews serially yourself. Record the review execution mode as serial lens fallback, do not claim that agents were spawned, and treat independence confidence as lower. Keep the lenses separate and label them so the author pass does not silently grade itself.

5. Merge findings into a rework list

After the lens reviews return:

• normalize verdicts into accept, conditional accept, reject, or

needs more evidence

• separate blocking gaps from non-blocking suggestions
• identify reviewer disagreements and decide which scenario, invariant, or

validation gap owns the tie

• revise the artifact only for gaps that improve correctness or evidence
• avoid overfitting to one reviewer phrasing when a more general skill,

workflow, or product rule is needed

In review-only mode, stop here with the merged findings and smallest rework list. Do not revise the artifact or run another round unless the user explicitly switches from review to rework.

If any selected reviewer rejects the artifact or names a blocking gap, do not hand off as final. Rework first.

6. Run a targeted next review round

For high-stakes tasks, skill creation, workflow changes, or when the user asks for two iterations, run a second reviewer round after the first revision.

The next-round prompt should include:

• the revised artifact
• round-one findings
• a short change log explaining what was changed
• explicit request to judge whether blockers were actually resolved
• unchanged blockers that should not trigger a broad new review fanout

If round two still produces a rejection or unresolved blocker, do another targeted rework and repeat the review loop until either: