SuperAPI AI Directory

soia-dev-review-panel

General & other

View repository

Updated 10-16 09:28

About this skill

soia-dev-review-panel

A single reviewer has blind spots — that is the entire premise of this skill. It structures a review into independent lenses that each look for a different failure mode, then makes every candidate finding survive an adversarial "try to refute this" pass before it's allowed into the report. Findings that don't survive verification are dropped, not softened.

Do not use this for the mechanics of fetching a GitHub PR's diff or finding a target repo's own rule files — that's soia-dev-github-ops's Pre-Merge Rule Review. This skill is the review methodology that procedure calls into once it has a diff in hand; it also works standalone on a local diff or a skill package with no GitHub involvement at all.

Customer-readable explanation

What this skill can do

Customer wants Skill will do Customer can see
Review a code change from multiple angles without missing anything Break it into independent perspectives and go through them one by one (in parallel where possible); each candidate finding then goes through a round of adversarial re-verification, keeping only those that withstand rebuttal Tiered findings list (blocking/should-fix/informational) + evidence level for each item
Review a skill package (SKILL.md/scripts/references) Switch to a set of perspectives specific to skill packages (host-agnosticism, security gate completeness, cross-file description consistency, etc.) Same as above
Only wants to know which aspects were reviewed and whether anything was missed The report explicitly lists the parts that were "checked, no issues", not just the problems Coverage scope description

How customers use it

  1. Specify the review target: local uncommitted changes, a diff text already in hand, or a skill directory path (e.g. skills/<name>/)。
  2. If the target type is unclear (code change vs skill package vs both), ask first before proceeding; do not guess.
  3. If there are requirements about strictness (e.g. "be stricter" "this time be fast"), adjust the number of perspectives and verification rounds accordingly; the default is the base perspective set listed below.
  4. The report only contains findings that are "confirmed to hold after re-verification"; it does not automatically change code, commit, merge, or publish—these are the user's own next steps.

Dependencies and installation

Install this skill (single skill):

npx skills add soia-team/soia-open-dev-coding-skills -g -a '*' -s soia-dev-review-panel -y

Hard dependency on soia-dev-coding-protocol: this skill's "test coverage and anti-patterns" perspective directly reuses its Anti-Fake-Fix Gate and pre-commit self-review checklist, rather than maintaining a second copy. Installing this skill automatically brings in this dependency.

This skill does not require private configuration.

Private information and intermediate data

This skill does not persist any data and does not require credentials, cookies, or API keys. Review materials (diff content, skill directory content) are used only in the current conversation/subtask context and are not written to any file, log, or third-party service; if used in combination with soia-dev-github-ops , the credential and network request boundaries are that skill's responsibility and are outside this skill's scope.

Logging and completion receipt

完成:<一句话说明审了什么、结论是什么>。

发现清单:<按阻断/应改/提示分档,每条给位置和证据等级>
覆盖范围:<用了哪些视角,核实过没问题的部分>
决定权:<交还使用者——建议合并/建议先改/建议不合并,不代为执行>

Step 0 — Determine target type and perspective group

  • Target is a code diff (local git diff, a diff text someone else already has,soia-dev-github-ops a PR diff handed over) → use the "code perspective group".
  • Target is a skill package (skills/<name>/ directory, or the changes mainly fall in some skill's SKILL.md/scripts/references) → use the "skill package perspective group"; if the skill package also contains scripts/*.py and similar code, both groups must be used.
  • If the target type or scope boundary is uncertain, ask first; do not guess.

Step 1 — Perspective list

Each perspective is executed independently and reads the original materials independently, without sharing the previous perspective's conclusions—this avoids anchoring, which is the core value of multi-perspective review; skipping this means spending the cost without getting the benefit.

Code Perspective Group

Perspective Focus
Correctness and self-verification Whether the change actually does what it claims to do—go read the original text of the changed files to verify; do not just look at diff fragments (a diff only shows changed lines plus a small amount of context, making it easy to miss the full signature/branch)
Security Whether external input (URL/path/user data) is validated; whether there are hardcoded keys/tokens; whether credentials or private data have ended up in logs or commit history
Test coverage and anti-patterns Apply the soia-dev-coding-protocol Anti-Fake-Fix Gate and check item by item: whether there are tests but the assertions are too loose ("it runs without errors" does not count as verification); whether the numeric claims in the description ("N tests passed", "processed M records") have been independently reproduced—do not take them at face value
Scope and consistency Whether the change exceeds the scope claimed by the title/description; whether the documentation (README/SKILL.md/CHANGELOG) has been kept in sync with the behavior change; whether the dependency direction is reversed

Skill Package Perspective Group

Perspective Focus
Command/interface correctness Whether every command that appears in the skill body (gh CLI, script invocations, etc.) is actually syntactically correct—do not judge from experience whether field names and parameters exist. Verify only in ways that are side-effect-free and require no login (--help、--dry-run, pure query-type calls); if the command itself requires credentials or has side effects (create/merge/delete/send/authorization-change types), switch to checking the parameters against the official documentation and do not actually execute it—this hard restriction takes precedence over the "no credentials needed" statement in the "Private Information and Intermediate Data" section, and is its concrete implementation, not an exception
Security gate completeness Whether high-impact operations (delete, overwrite, send, publish, authorization change) all have corresponding explicit confirmation requirements; whether grant-type operations have symmetric verify/revoke verification steps
Host independence Whether it depends on a specific AI CLI's proprietary tools (such as Claude Code's computer/claude-in-chrome/built-in slash command); the body must be independently understandable and runnable by other hosts (Codex, Gemini CLI, etc.)
Consistency and synchronization frontmatter description / agents/openai.yaml / the corresponding line in the top-level README / the auto-generated table of contents—whether the descriptions of capabilities in these places are in sync with each other;version whether it is bumped along with this change; whether the skill name collides with an existing skill (especially across repositories)—on this machine ~/.agents/.skill-lock.json is stored under a single key by name, regardless of source repository, and a name collision will overwrite each other's installed files

When stricter review is needed, add perspectives as needed on top of the base perspectives (for example, add a "concurrency semantics" perspective for changes involving concurrency); do not force in irrelevant perspectives just to pad the count.

Step 2 — Dispatch

If the current environment supports spawning independent subtasks (such as Claude Code's Agent/Workflow tools, or equivalent parallel mechanisms provided by other hosts), assign the selected perspectives to independent subtasks for parallel execution, and give each subtask only the description for its own perspective and the raw materials—do not feed it the conclusions of other perspectives as well.

When the current environment does not support forking subtasks, go through each perspective sequentially in the same context: before switching to each perspective, explicitly state "for now, only look at this using the standards of perspective X, forget the conclusions from the previous perspective," write this sentence out in written form before continuing, to prevent perspectives from contaminating each other's judgments. The candidate findings produced by the two approaches have the same format; which one to choose depends on environment capabilities, not on strictness.

Step 3 — Format of candidate findings

Each candidate finding has four fixed elements:

  1. One-sentence title
  2. Specific location (file path + line number, or section name — do not just say "somewhere")
  3. Evidence level: seen (quote the original text) / inferred (provide the reasoning chain) / uncertain (state it explicitly and give a verification path)
  4. Severity candidate: blocking (violates hard rules/security issues/obvious bugs) / should fix (not blocking but worth addressing) / note (checked and no problem, or minor observation)

Step 4 — Adversarial review (cannot be omitted)

The dispatch method follows the same degradation rules as Step 2: if independent subtasks can be forked, fork them; if not, do it in the same context, but you must first write a written switch sentence (for example, "now I am only responsible for trying to refute this finding, ignoring my earlier judgment from the original perspective") before continuing — the anchoring risk faced by the review and the mutual contamination between perspectives in Step 2 are the same type of problem, handled by the same set of rules.

For each candidate finding at the "blocking" or "should fix" level, re-examine it from an independent perspective, specifically trying to refute it:

  • Go back and read the original material itself, not the paraphrase from the previous step — paraphrasing amplifies or dilutes the original information, so you must return to the source.
  • By default, lean toward "does not hold"; only after actually reproducing and verifying it should you judge it as "holds."
  • Check: whether the cited evidence really exists in the original text; whether the severity has been exaggerated or underestimated; whether there is a counterexample that can refute the conclusion; if during the review a more accurate problem description is found (for example, the line number reference in the original finding is off), use the corrected version, and do not discard the entire finding just because a detail is off.
  • "Note"-level candidates (checked and no problem) do not need adversarial review; they go directly into the coverage description of the final report.

Only findings judged as "holds" by the review enter the final report.

Step 5 — Output

The final reply must include:

  1. One-sentence conclusion: whether this change overall is one of "recommend approval," "recommend fixing first," or "recommend rejection," placed at the very front.
  2. Findings list: grouped by blocking/should fix, with location, evidence level, and brief explanation for each.
  3. Coverage: which perspectives were used, and the parts that were verified but where no problems were found (do not report only problems; let the reader know where the review boundary is).
  4. Explicitly return decision-making authority: this is a review recommendation, not automatic permission to execute — this skill does not modify code, commit, merge, or release; that is the user's own next step after reading the report.

Relationship with other skills

Skill Relationship
soia-dev-coding-protocol Strong dependency. The "test coverage and anti-patterns" perspective directly reuses its Anti-Fake-Fix Gate and pre-commit self-review checklist, avoiding duplicate maintenance
soia-dev-github-ops One-way dependency, with the direction opposite to the other rows in this table: its Pre-Merge Rule Review hard-depends on this skill (if it cannot be installed, it stops and will not degrade into maintaining its own checklist), and it is responsible for "pulling the PR diff + finding the target repository's own rule files," then handing the results to this skill for the Step 1-4 perspective review and adversarial re-review. This skill does not depend on it in reverse, and also does not know how to use gh CLI to pull PRs; that part is left to it
soia-private-skills of soia-dev-code-review is not the open-source version of the same skill; the two can be installed at the same time (different names, no conflict). That skill specifically serves governance reviews of proposals/Waves/fixes within a confirmed SOIA product workspace, binding specific models to specific dimensions across 6 dimensions based on the team's internal experience; this skill is a general methodology, contains no product/team-specific information, and does not assume a particular model division of labor. vault,soia-open-dev-coding-skills、soia-private-skills and ordinary repositories use this skill for review; confirmed SOIA product governance reviews use that one