Multi CLI Review Action

Multi-CLI Review Action

Version History

• v2.4: Aligned paired intake wording with coordinator-assigned letter-based reviewer-id slots and CLI identity recorded separately in source-cli
• v2.3: Repositioned the skill as a workflow-agnostic action-side pair contract and moved reviewer-count defaults out of the core contract
• v2.2: Added an explicit no-new-problems adoption gate and aligned workflow wording around regression-safe fixes
• v2.1: Tightened report intake rules, safety gates, and skill-spec alignment for the shared paired contract

Purpose

multi-cli-review-action is the action-side skill paired with multi-cli-review.

The current CLI uses it to consume reviewer reports generated by that paired skill. It is intentionally workflow-agnostic: any workflow, command pack, or manual coordinator may use it, as long as the reviewer reports follow the paired contract.

It exists to do one job safely:

1. Collect reviewer reports
2. Deduplicate and classify findings
3. Re-check each candidate against local code and project rules
4. Ask for confirmation before edits
5. Apply only confirmed, in-scope fixes
6. Record decisions and verification results

When to Use

Use this skill when any of the following is true:

• Other CLI instances have already written one or more multi-cli-review reports
• The user asks to "汇总这些审查报告"
• The user asks to "处理 multi-cli-review 输出"
• The user asks to "按 reviewer 建议执行修复"
• The current CLI must reconcile multiple reviewer opinions before changing files

When Not to Use

• You only need to generate reviewer findings, not apply fixes: use multi-cli-review
• You are doing a normal implementation task without multi-reviewer handoff
• The reports are still unconfirmed hypotheses and the user has not yet agreed to a fix plan

Core Rules

1. Single fixer: reviewer CLIs only produce reports; this skill never delegates edits back to reviewers.
2. Reports are evidence, not truth: every finding must be re-checked against the local codebase, task scope, and project rules before adoption.
3. No surprise edits: after summary and decisioning, the current CLI must get user confirmation before making concrete file changes.
4. No scope expansion: only fix issues that belong to the current task; do not piggyback refactors, new features, or broad cleanups.
5. No automatic conflict resolution: mutually exclusive or high-risk suggestions require human judgment.
6. Coordinator-owned orchestration: reviewer-count defaults, round planning, and reviewer command packaging belong to the upstream coordinator, workflow, or command pack; this skill only consumes the resulting report set.
7. No fix-induced regressions: do not adopt a fix if the current CLI cannot explain why it is unlikely to introduce a new defect, regression, or broader risk than the original issue.
8. Verification is mandatory: after edits, run the relevant validation commands before claiming completion.
9. Project-root path resolution: relative paths are resolved against the active project root, never system /tmp or a tool install directory.

Protocols

Protocol Selection

1. If --task-dir is present, use action-v2.
2. If a single legacy report path is provided, use action-v1.
3. New work should prefer action-v2.

Inputs

action-v2

action-v1 Compatibility

Path Rules

Relative paths must resolve against the active project root.

Do not reinterpret relative paths as:

• the skill repository root
• the user home directory
• system /tmp
• a CLI installation directory

If project root detection is ambiguous, stop and ask for an absolute path instead of guessing.

Report Intake Contract

For action-v2, only consume files that satisfy all of the following:

1. The file lives under {task-dir}/review-round-{N}/
2. The basename is exactly <reviewer-id>.md
3. The frontmatter includes:
   • task-id
   • round
   • reviewer-id
   • source-cli
   • protocol: task-level
4. Frontmatter values match the directory and filename
5. The file is not one of:
   • summary-*.md
   • action.md
   • ad-hoc notes, scratch docs, or human decision memos

If a file is ambiguous, malformed, or inconsistent with the contract, stop and ask for cleanup instead of consuming it optimistically.

Report Set Rules

• This skill consumes the valid multi-cli-review reports present for the chosen round; it does not define how many reviewers should be launched by default.
• 0 valid reports is an error.
• If a coordinator, workflow, or command pack defines reviewer-count defaults or caps, treat those as upstream policy rather than redefining them here.
• In current task-level rounds, reviewer-id should be interpreted as the coordinator-assigned reviewer slot ID (a / b / c / d), while source-cli identifies the actual reviewer CLI.

Decision States

Each candidate finding must end in exactly one of these states:

• adopted: confirmed against code/spec/task boundary and approved for execution
• ignored: rejected with a concrete reason
• manual-decision: conflict, ambiguity, or risk requires human input
• blocked: execution or verification could not proceed

Workflow

Step 1: Resolve Mode and Inputs

1. Determine whether this is action-v2 or legacy compatibility mode.
2. Resolve all relative paths against the active project root.
3. Load .processed.json when present.

Step 2: Collect Candidate Reports

For action-v2:

1. Read only the target review-round-{N} directory.
2. Filter files using the report intake contract.
3. Reject malformed or mismatched files.
4. Skip previously consumed reports unless --force is set.

Stop conditions:

• no valid report files
• all valid reports already consumed and --force is not set

Step 3: Convert Reports into Candidate Findings

1. Merge findings by location and meaning, not by filename alone.
2. Preserve all source reviewers for each merged finding.
3. Preserve conflicting fix directions instead of flattening them away.

Step 4: Re-check Every Candidate Locally

Before any finding can be marked adopted, the current CLI must verify:

1. the issue still exists in the current code
2. the issue belongs to the active task boundary
3. the proposed fix does not contradict project rules or existing abstractions
4. the proposed fix is smaller than the damage it prevents
5. the planned change is unlikely to introduce a new bug, regression, or higher-cost side effect in nearby behavior

If any of those checks fail, mark the finding ignored or manual-decision; do not auto-adopt it.

Step 5: Decide

Use this decision policy:

• adopted: specific, in-scope, locally verified, safe to change
• ignored: stale, duplicate, incorrect, out-of-value, or already fixed
• manual-decision: conflicting suggestions, unclear ownership, risky side effects, unresolved boundary questions, or no clear low-regression fix path

Every non-adopted item must include a reason that is specific enough to avoid the same report being re-litigated next round.

Step 6: Write the Summary First

Write summary-round-{N}.md before any file edits.

The summary must record:

• reviewer files consumed
• total findings before and after deduplication
• conflicts
• the full decision list
• ignored reasons
• manual-decision items that still need user input

Step 7: Ask for Confirmation Before Edits

After the summary exists, present the fix plan and wait for user confirmation.

Do not edit files yet when:

• the user has not confirmed execution
• any manual-decision item blocks safe progress
• the remaining plan would expand scope
• the current CLI cannot justify that the planned fix will not create a new problem or regression

Step 8: Execute Only Confirmed Fixes

In normal mode:

1. modify files only for adopted items
2. keep changes inside the confirmed boundary
3. record what changed and why in action.md

In --dry-run mode:

1. do not modify source files
2. do not mark reports as consumed
3. write only decision artifacts that clearly say they are previews

Step 9: Verify Before Completion

After edits, run the smallest command set that can prove the fixes did not introduce new issues:

• lint or formatting checks if relevant
• typecheck if relevant
• tests or targeted regression commands if relevant

Record actual results only: pass, fail, or not run.

Step 10: Finalize State

1. Update action.md
2. Update .processed.json only for reports actually consumed in a non-dry-run execution
3. Leave blocked or manual items visible for the next human decision

Output Files

summary-round-{N}.md

Minimum contents:

• task id and round
• reviewer source list
• deduplicated findings table
• conflicts table
• decision summary
• ignored reasons
• pending manual decisions

action.md

Minimum contents:

• execution mode: normal or dry-run
• adopted edits actually applied
• ignored items and reasons
• blocked or manual-decision items
• verification commands and outcomes

.processed.json

Use this as internal consumption state only.

Rules:

• do not update it during --dry-run
• do not mark malformed or skipped reports as consumed
• do not use it as a substitute for action.md

Conflict Handling

Treat a finding as conflicted when reviewers disagree on any of these:

• whether a change is needed at all
• the file or location to change
• the implementation direction
• the risk or severity in a way that changes the recommended action

Conflict policy:

1. keep all alternatives visible
2. do not choose automatically
3. surface the exact conflict to the user

Example prompt:

⚠️ 需要人工介入

冲突问题：src/c.py:30
- reviewer-a：重构整个函数
- reviewer-b：仅修正返回值

请选择：
1. 采纳 reviewer-a
2. 采纳 reviewer-b
3. 自定义方案
4. 忽略该问题

Required Stop Conditions

Stop and ask for human input when any of the following is true:

• conflicting suggestions remain unresolved
• a finding crosses task scope
• a suggested fix would violate project conventions or security expectations
• a suggested fix cannot be reduced to a low-regression change with a defensible rationale
• verification fails
• the report set is malformed or incomplete
• the round already reached the agreed limit and unresolved items remain

Error Handling

Common Mistakes

• Treating reviewer output as ground truth: always re-check locally before adoption.
• Consuming every .md file in the round directory: only accept files that match the report contract.
• Redefining reviewer defaults inside this skill: the upstream coordinator or command surface decides the default count.
• Fixing beyond scope: do not smuggle in refactors or adjacent feature work.
• Closing one issue by opening another: if the planned fix has unclear regression or side-effect risk, stop and move it to manual-decision instead of forcing adoption.
• Skipping confirmation: summary first, confirmation second, edits third.
• Skipping verification: a changed file without validation can create a new problem while solving the old one.

Examples

Example 1: Current Protocol

用户：/multi-cli-review-action --task-dir tmp/multi-cli-review/skill-review --round 1

CLI：
1. 读取 round-1 下已有的 reviewer 报告
2. 校验 frontmatter 与文件名一致
3. 合并并去重
4. 对每个候选问题重新核对本地代码和任务边界
5. 排除会明显引入新问题或回归的修复方案
6. 输出 summary-round-1.md
7. 等待用户确认
8. 执行已确认修复
9. 运行验证命令
10. 写入 action.md 和 .processed.json

Example 2: Dry Run

用户：/multi-cli-review-action --task-dir tmp/multi-cli-review/skill-review --round 2 --dry-run

CLI：
1. 读取 round-2 报告
2. 输出决策和冲突
3. 生成预览版 summary / action
4. 不改源码
5. 不更新 .processed.json

Related Skills

• multi-cli-review: reviewer-side report generation
• verification-before-completion: post-change verification discipline
• brainstorm: boundary clarification before accepting risky fixes

Compatibility Notes

• Single-report legacy usage may still enter action-v1, but it must follow the same safety gates: re-check locally, ask before editing, and verify afterward.
• New task-level usage should always prefer action-v2 with explicit --task-dir.