sanity-review

PR Review Report Creation Procedure

Review a feature/bugfix/refactoring PR and create a review report. In addition to assisting with ordinary code review, it is also a self-review tool for implementers to review their own PRs. The goal is to finish it into a sane pull request that can be shown to human reviewers.

Out of Scope

• Library update PRs (dependabot/renovatebot, etc.) are the target of the library-update-review skill and are out of scope for this skill

Procedure

Step 0: Check the Situation

Check the Execution Environment

First, check the execution environment. If either of the following is not satisfied, do not perform the review, report the unsatisfied condition to the user, and stop:

1. Your own model is at the Claude Opus tier or above (Opus, Fable, Mythos, etc.). Lower tiers such as Sonnet and Haiku do not satisfy this even in newer generations, and non-Claude models such as Codex do not satisfy it either
2. If Codex CLI is available, its model is a flagship at the Sol level or above (Sol, Astra, etc.) and the reasoning effort is medium or higher. Use the Bash tool to run command -v codex to check for its presence, and if present, write a short prompt to a file outside the working tree, pass it tocodex exec --ephemeral via stdin, run it once, and read it from the output header. Lightweight tiers such as Luna and Terra, and models from generations before Sol, are insufficient as consultation partners

codex exec Running codex-consultation with the Skill tool. Obtaining the Codex execution environment and the back-and-forth of consultation are handled by codex-consultation.

Retrieve PR Information

If a PR number or URL is specified as an argument, target that PR. If not specified, automatically detect the PR associated with the current branch.

In either case, retrieve the PR information with the following command:

gh pr view {PR番号またはURL} --json number,title,body,url,author,comments,headRefName

In the case of automatic detection, omit {PR番号またはURL} .

If the PR is not found, report it to the user and exit.

Use the PR title, PR number, and branch name in the report header. For Reviewed at, enter the current date and time (YYYY-MM-DD HH:mm:ss); for Reviewer, enter your own Agent name and model name, and if an external Agent was used, also include the execution environment obtained by the consultation skill.

Retrieve the following information:

1. PR body (overview section)
2. PR comments: gh pr view の comments
3. Inline review comments: gh api repos/{owner}/{repo}/pulls/{number}/comments --paginate
4. PR reviews: gh api repos/{owner}/{repo}/pulls/{number}/reviews --paginate
5. Diff: gh pr diff {number}

Check the report output destination

Before starting review work, confirm the review report output destination with the AskUserQuestion tool:

• Chat and pull request(Recommended): Output the review report to the conversation and also post the same content as a comment on the PR
• Chat: Output the review report only to the conversation

If the user has explicitly specified the output destination, skip this confirmation and follow the specification.

Step 1: Loading the dialogue context

Look for the dialogue context in the following order:

1-1. Check the PR comments section

Check whether there is a comment containing the title "Dialogue Context" among the PR comments. If found, use its content as the dialogue context.

1-2. Check .dev/contexts/

Sanitize the branch name (/ \ : * ? " < > | を - replace with), and.dev/contexts/{サニタイズ済みブランチ名}.md look for. If found, read it with the Read tool.

1-3. If neither is found

Confirm the following with the AskUserQuestion tool:

• Continue without dialogue context: Skip Step 6 (checking for overlooked considerations)
• Abort: Ask the user to prepare the dialogue context

Step 2: Quality evaluation of the pull request description section

Perform this step before reading the code. This is to prevent being drawn into checking code consistency and overlooking structural problems in the description section.

The implementer may not be of sound mind. They may have written the PR description without really understanding it, or generated it with AI and pasted it as-is. In this step, read only the description section, and evaluate whether a reviewer reading this description can "judge the validity of the change."

PR description checklist

Evaluate the following 4 items all without exception and note the results. Evaluate all items before proceeding to the next step:

1. Is the behavior/problem before the change explained: To judge the validity of the change, the reviewer needs to know the state before the change. "What was done" alone leaves the question "Might the behavior before the change have been more correct?"
2. Is it written as a "problem→solution" or "current state→fix" pair: For new features, the purpose/motivation is also acceptable. However, a one-way explanation of only "what was done" is insufficient
3. Is the scope of the change clear: Can you tell what was changed and what was not changed
4. Is the implementer's own understanding visible: Does it convey what the implementer was thinking when making this change, rather than just pasting AI-generated text as-is

Common policy for consulting external Agents

In steps 3, 4, and 5, seek a second opinion from an external Agent (however, the "Consider naming and design from a long-term perspective" subsection of step 4 is excluded). In step 6, consult an external Agent only when there are suspicious points. Following the fallback order below,do not judge by guesswork; actually call and trythat:

1. Skill toolで codex-consultation Call. If it fails, proceed to 2
2. Skill toolで subagent-consultation Call. Start the subagent by specifying a model of Opus tier or higher. If it fails, proceed to 3
3. The main agent performs the work alone

If a fallback occurs, or if an external Agent could not be used, record it in the "Problems that occurred during review work" section of the report.

If it fell back to 3 (main agent executing alone)means that the chain of critical thinking (the protocol of examining and rebutting each other's claims to improve accuracy and comprehensiveness), which is the core of this skill, is not functioning. A review in a state lacking reciprocal verification does not have its original accuracy, so at the beginning of the "Problems that occurred during review work" section of the report, record the following wording verbatim as a bold paragraph:

⚠ Warning: The chain of critical thinking is not functioning; please suspect that the execution environment is sane

In each step, describe the contents of the Args passed to the external Agent and how the results are handled.

Step 3: Confirming consistency between the implementer's explanation and the implementation

The purpose of this step is to confirm whether the explanations in the PR title, overview section, and comments match the actual code,reading the documentation and code together is that.

Important: Pick up only the implementer's statements

Compare the author of the PR overview section with the author of each comment, andonly the implementer's own statementsare treated as explanations of the implementation. Supportive comments written by others, comments expressing expectations for the feature, questions, etc. are not explanations of the implementation. Confusing these with explanations of the implementation will lead to incorrect judgments of consistency.

Items to confirm

1. Whether the PR title and overview section each match the actual diff
2. Whether the implementer's explanations in inline review comments match the actual code
3. Whether the implementer's explanations in the PR review body (top-level review comment) match the implementation
4. Whether the contents of the conversation context match the implementation (if there is a conversation context)

If a discrepancy is found, record it specifically.

Consistency check by an external Agent

In addition to the Agent's own check, have an external Agent also check the consistency between the diff and the PR title/overview section. Because it reads the code from a different perspective, it may be able to find discrepancies that the Agent overlooked.

Following the "Common policy for consulting an external Agent", call it with the following Args:

Args: よく相談して。PR #{番号} のタイトルと概要欄のそれぞれについて、実際の差分との齟齬がないか確認してほしい。{タイトル、概要欄の要約、確認ポイント}

When you receive feedback from an external Agent, cross-check it against your own verification results and confirm whether anything was overlooked.

Step 4: Consistency of naming and design patterns

The purpose of this step is to confirm whether the implementation matches the conventions of the existing codebase,reading and understanding the codebase . By understanding the codebase before investigating bugs and vulnerabilities, the accuracy of subsequent investigations improves.

Items to confirm

1. Consistency of naming conventions

   • Whether file names, function names, variable names, and class names match the naming patterns of the existing code
   • Whether names that abbreviate the official name of a feature with letters missing have been introduced

2. Consistency of design patterns

   • Whether the structure, module division, and separation of responsibilities match existing similar features
   • Whether existing abstractions are being used, and whether duplicate implementations are being created

If a discrepancy is found, record it concretely.

Verification by an external Agent

In addition to the Agent's own verification, have an external Agent also verify the consistency of naming and design patterns.

Following the "Common Policy for External Agent Consultation", call it with the following Args:

Args: よく相談して。PR #{番号} で追加・変更された命名と設計パターンが、既存のコードベースの慣習と一致しているか確認してほしい。{変更概要}

When you receive feedback from an external Agent, cross-check it against your own verification results and confirm whether anything was overlooked.

Consider naming and design from a long-term perspective

Consider whether the current naming and design could become a source of trouble when the codebase is expanded in the future. Unlike consistency with existing code (a factual determination), this is work to provide material for discussion and stimulate human imagination.

If anything concerns you, write it out in a self-questioning-and-answering format that covers "concern, counterargument, conclusion or pending". Since this is the Agent's own view, write it as a normal paragraph. About 2 to 3 paragraphs per point is sufficient. There is no need to force a conclusion. If there is nothing of concern, write "None in particular". This consideration section is not delegated to an external Agent; the Agent that runs the skill thinks about it itself.

Output example:

「access-token」という名前は、現状はユーザーとサービス間のtokenしか指さないため問題はない。
ただ今後、外部サービスとの接続用のtokenが登場した場合は、概念衝突が起きる可能性がある。

そうなったら `user-access-token` のように主体を名前に含める必要が出るかもしれない。
もっとも、現時点で外部サービス連携を近い将来に追加する計画は見えていないため、今すぐ修正すべき問題ではないと判断する。

「member-metrics」という名前についても、将来 project member 以外の member 概念が増えた場合には曖昧になる余地がある。
一方で既存コードでは `Member` は project member を指す語として定着しており、短期的には大きな問題はなさそうである。

したがって現時点では問題なしと判断する。
ただし、将来 organization member など別種の member 概念を導入するなら、命名の見直しは必要になる。

Step 5: Investigation of bugs and vulnerabilities

Following the "Common Policy for External Agent Consultation", request a code review from an external Agent. Include the PR change overview, a summary of the diff, and the points you want checked in the arguments.

Include the depth specification in the arguments. If the depth is unspecified, consultation-type skills will ask the user back, interrupting the review flow:

Args: よく相談して。PR #{番号} のコードレビューをお願いします。{変更概要と確認ポイント}

Verification of results

Do not take the external Agent's feedback at face value. Do the following:

• Verify the points raised by the external Agent by reading the code yourself
• Consciously look for areas the external Agent may have overlooked
• If the external Agent's feedback and your own view conflict, record the reasons for both

Step 6: Re-reading the dialogue context and checking for omissions

If there is no dialogue context, skip this procedure.

Code review is not a double-check of the work result. Review the process, not the result.

What was done can be understood by reading the code. What was considered but not done is precisely the information needed for reviewing the design. Verify whether the "process" written in the dialogue context—design decisions, reasons for rejection, and intentional non-support—is correct.

Carefully re-read the dialogue context and verify the following:

6-1. Basis for design decisions

Whether the reasons for the design decisions written in the dialogue context match the actual state of the code.

6-2. Re-evaluation of rejected alternatives

From the "Rejected alternatives" section of the dialogue context, extract each alternative one by one and re-evaluate it:

• Is the reason for rejection valid? Was the comparison truly fair?
• Are there overlooked advantages or overestimated disadvantages?
• Are the preconditions used for comparing the adopted proposal and the rejected proposal correct?

6-3. Process verification of failed attempts

For things described as "tried but didn't work," question not only the result but alsothe way it was tried itself:

• Were the preconditions correct?
• Were there any oversights in the execution procedure?
• Was the judgment criterion (the basis for determining "didn't work") valid?
• Is there no possibility that the result would change if tried under different conditions?

6-4. Validity of intentionally unsupported items

For things decided as "won't do":

• Is the reason for "won't do" still valid given the current implementation?
• As a result of the implementation, have the preconditions changed such that it should become "should do"?

6-5. Accuracy of the stated facts

Verify by reading the code whether the "facts" written in the dialogue context are really correct.

If there are doubtful points, consult an external Agent as well in accordance with the "Common Policy for Consulting External Agents." Include "consult well" in Args.

Step 7: Creating the review report

In the same directory as this SKILL.md, TEMPLATE.md read it and create the report according to its format.

The report should beoutput to the conversation. If it was decided in Step 0 to post a comment on the PR, post the same content as a comment on the PR as well.

Guidelines for creating the report

• pull request overview section > Summary: Quote or excerpt the implementer's explanation and organize it as before-after. Do not supplement with imagination or write arbitrarily. If the implementer's explanation is insufficient, plainly point that out
• pull request overview section > Quality evaluation: Enter the checklist results from Step 2 as OK/NG/Not applicable. In the case of NG, specifically describe what is lacking
• Issues Encountered During Review Section: If review steps were skipped, distinguish and describe whether this was due to external factors (e.g., a tool was unavailable) or the Agent's judgment. If there are no issues, state "None in particular"
• Conclusion Section: Describe the overall comprehensive judgment and recommended actions
• Throughout, keep in mind to provide the material for the reviewer to judge "whether this change is appropriate"

Related Skills

• codex-consultation: A skill for consulting with Codex CLI. Used as the first candidate for an external Agent in Step 3, Step 4, Step 5, and Step 6
• subagent-consultation: A skill for consulting with the Agent tool (subagent). The fallback destination when codex-consultation is unavailable
• conversation-context-import: A skill for loading the dialogue context. Background knowledge for Step 1
• conversation-context-export: A skill for writing out the dialogue context. Background knowledge for the dialogue context format
• library-update-review: A review skill for library update PRs. A type of PR that is outside the scope of this skill