Code Review

Code Review Skill

Perform structured, objective code reviews for Flutter/Dart projects following a repeatable checklist.

When to Use

Use this skill when:

• Asked to review a pull request, merge request, or branch.
• Evaluating changed, added, or deleted files for correctness and quality.
• Auditing a diff before merging.
• Checking whether new code meets project standards.

---

Review Workflow

Step 1 — Validate branch and merge target

1. Confirm the current branch is a feature, bugfix, or PR/MR branch — not the project's primary branch (e.g. main, master, develop). 2. Verify the branch is up-to-date with the target branch (no unresolved conflicts). 3. Identify the target branch for the merge.

Checkpoint: If the branch is behind the target, flag it before proceeding.

Step 2 — Discover changes

1. List all changed, added, and deleted files. 2. For each change, look up the commit title and review how connected components are implemented. 3. Analyze the change: is it clear why the change was made? If not, dig into the connected methods and files until it is. When you report, name which connected files/methods you analyzed and why — this shows the change was understood, not assumed. 4. Never assume a change is correct without investigating the implementation. 5. If a change remains unclear after investigation, note this explicitly in the report.

Step 3 — Review each file

Iterate through each changed file. For every file, verify the following:

For generated files (e.g., *.g.dart, *.freezed.dart): confirm they are up-to-date and not manually modified.

Scope discipline: Your job is not to comment on every change — it's to find errors and concrete improvement areas and comment on those. Don't manufacture comments where the code is fine.

Flutter-specific checks

// BAD — rebuilds entire tree on every state change
BlocBuilder<MyCubit, MyState>(
  builder: (context, state) => EntireScreen(state: state),
);

// GOOD — scope rebuilds to the widget that actually changes
BlocSelector<MyCubit, MyState, String>(
  selector: (state) => state.title,
  builder: (context, title) => Text(title),
);

• Verify Key usage on dynamically generated widgets.
• Check that dispose() is called for controllers, streams, and animation controllers.
• Confirm const constructors are used where possible.

Code Smells Reference

For each file, check for common code smells. Use refactoring.guru/refactoring/smells for definitions and suggested refactorings.

Step 4 — Evaluate the overall change set

1. Verify the change set is focused and scoped to its stated purpose — no unrelated changes. 2. Check that the PR/MR description accurately reflects the changes.

Test coverage

Verify test coverage explicitly — this is easy to skip and easy to fake, so be deliberate:

• For any new logic or significant change, search for the corresponding test file(s) and confirm tests actually exist.
• Check that tests cover the changed functionality including edge cases, not just the happy path.
• Evaluate whether tests could actually fail against real code, or only verify mocked behavior (a test that asserts a mock returns what the mock was told to return proves nothing).
• If tests are missing or insufficient, comment on the lack of coverage — don't let it pass silently.

Step 5 — Verify CI and tests

1. Ensure all tests pass in CI. 2. Check for new analyzer warnings or lint violations. 3. Fetch official documentation when unsure about best practices for a package.

Checkpoint: If CI is red or tests are missing for new logic, flag as a blocking issue.

---

Wrap-Up

After the per-file pass, decide the outcome:

• If everything looks good and no changes are needed: post an overall conclusion comment summarizing what the MR is about (what was done) plus any observations, and approve the MR.
• If the new changes are clean but you spotted smells in existing code: include those as optional refactor suggestions rather than blockers.
• If issues were found: summarize the key concerns clearly so the author knows what to address first.

---

Feedback Standards

• Be objective and reasonable — avoid automatic praise or flattery.
• Take a devil's advocate approach: give honest, thoughtful feedback.
• Provide clear, constructive suggestions for every issue found.
• Include requests for clarification for anything unclear.
• Classify each finding by severity: suggestion, minor, or major.

---

Output Format

By default, provide the review as a chat response — a structured response covering each file:

1. Summary — what changed and why. 2. Issues — each with severity (suggestion / minor / major) and a concrete fix suggestion. 3. Questions — specific clarification requests per file. 4. Verdict — one of: Approved, Approved with suggestions, or Changes requested.

Posting comments online (opt-in only). After presenting the chat review, ask the user whether they'd prefer you to also post these comments online on the PR/MR — so the team can see them, review them, and reply. Only post online if the user explicitly says yes. Never post to the platform on your own initiative.

>

When the user does opt in, post issues as inline comments anchored to the right file and line (use proper position fields), with the conclusion/key-concerns as a top-level review comment and an approval when warranted. This requires a review-bot access token for the platform (GitHub/GitLab); if one isn't configured, let the user know and ask them to set it up before posting.

>

Token safety. The token is a secret. You may check whether it exists and report its length to confirm it's configured, but never read, echo, log, print, or otherwise reveal the token value — not in chat, not in a file, not in a commit. Pass it to curl only by referencing the env var (e.g. $GITLAB_TOKEN), never by inlining the literal value, and avoid curl -v/--verbose (it prints the auth header). This is enforced by a PreToolUse hook (scripts/protect-token.sh) that blocks any Bash command which would expose the value. See the "Handling the token safely" section in each reference file for the safe existence/length check.

>

The hook fires in both the Claude Code CLI and the Agent SDK. (SDK apps that set settingSources/setting_sources explicitly must include "project" for skill hooks to load; it's included by default.)

>

For platform-specific API details, curl formats, and approval steps, follow:

- GitLab → references/gitlab-posting.md (uses the GITLAB_TOKEN env var)

- GitHub → references/github-posting.md (uses the GITHUB_TOKEN env var)

GitHub Posting Reference

How to post review comments to a GitHub pull request via the REST API. Read this only when the user has explicitly opted in to posting comments online (see the Output Format section in SKILL.md).

Replace the placeholders below with your own values:

• <owner> — repository owner (user or org), e.g. your-org
• <repo> — repository name, e.g. your-repo
• <pull_number> — the pull request number (the number in the PR URL)
• Auth token comes from the GITHUB_TOKEN env var (a review-bot access token /

fine-grained PAT with "Pull requests: Read and write").

All requests use these headers:

Authorization: Bearer $GITHUB_TOKEN
Accept: application/vnd.github+json
X-GitHub-Api-Version: 2026-03-10

Handling the token safely

GITHUB_TOKEN is a secret that can act on the user's behalf. Treat it as write-only from your perspective: you may confirm it's present and report its length, but its value must never leave the process. This is enforced by the skill's PreToolUse hook (scripts/protect-token.sh), which blocks any Bash command that would expose the value.

Allowed — confirm it's configured without revealing it. This uses only the length form ${#GITHUB_TOKEN}, so presence is derived from length and the value is never expanded:

if [ "${#GITHUB_TOKEN}" -gt 0 ]; then
  echo "GITHUB_TOKEN is set (length: ${#GITHUB_TOKEN})"
else
  echo "GITHUB_TOKEN is not set"
fi

Never do any of these (the hook will deny them):

• echo "$GITHUB_TOKEN", printf it, or cat a file/heredoc containing it.
• Print it to chat, write it to a file, or include it in a commit.
• printenv GITHUB_TOKEN, or dump the environment (env, set, export -p).
• Inline the literal token in a command (it lands in shell history/logs) — always

reference $GITHUB_TOKEN.

• Use curl -v / --verbose / --trace*, which echo the Authorization header.

When sharing command output for debugging, redact the Authorization: header line.

Comment Format

• Line comments: [Flutter Code Review Bot]: <feedback>
• Summary (optional): [Flutter Code Review Bot] Summary: <overall feedback>

API Usage (Essentials)

GitHub distinguishes three kinds of comments:

A PR is also an issue, so the PR number is the issue number for general comments. Inline comments need commit_id (the head SHA), path, and line (the line in the file's diff). For added lines use side=RIGHT; for removed lines use side=LEFT. For multi-line comments add start_line (+ start_side).

Example (General PR Comment)

Issues / Comments API

curl --request POST \
  --header "Authorization: Bearer $GITHUB_TOKEN" \
  --header "Accept: application/vnd.github+json" \
  --header "X-GitHub-Api-Version: 2026-03-10" \
  --url "https://api.github.com/repos/<owner>/<repo>/issues/<pull_number>/comments" \
  --data '{"body":"[Flutter Code Review Bot]: This is a general comment on the PR."}'

Inline Diff Comment (Minimal Example)

Pulls / Review comments API

curl -s -X POST \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "Accept: application/vnd.github+json" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  "https://api.github.com/repos/<owner>/<repo>/pulls/<pull_number>/comments" \
  --data '{
    "body": "[Flutter Code Review Bot]: Feedback",
    "commit_id": "<head_sha>",
    "path": "lib/.../file.dart",
    "line": 42,
    "side": "RIGHT"
  }'

Fetch the head SHA (useful when running locally):

curl -s -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "Accept: application/vnd.github+json" \
  "https://api.github.com/repos/<owner>/<repo>/pulls/<pull_number>" \
  | grep -A 3 '"head"'

Fast Checklist

1. Get the head SHA (commit_id) from the PR JSON. 2. Confirm the line number exists in the diff for that file and side. 3. POST with commit_id, path, line, side; verify the response contains an "id" and "path".

Failure quick-fix: 422 Unprocessable => line not part of the diff or wrong side; 404 => wrong owner/repo/number or token lacks PR access; 401 => bad/expired token.

Batch Review + Approval

Prefer a single review when posting many inline comments plus a verdict — it groups them and sets approval in one call. Use event=APPROVE ONLY after verdict = APPROVED and: no blocking notes, all comments resolved/visible, bot not already approved, checks not failing. Other events: REQUEST_CHANGES, COMMENT.

curl -s -X POST \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "Accept: application/vnd.github+json" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  "https://api.github.com/repos/<owner>/<repo>/pulls/<pull_number>/reviews" \
  --data '{
    "commit_id": "<head_sha>",
    "body": "[Flutter Code Review Bot] Summary: Looks good.",
    "event": "APPROVE",
    "comments": [
      {"path": "lib/.../file.dart", "line": 42, "side": "RIGHT",
       "body": "[Flutter Code Review Bot]: Feedback"}
    ]
  }'

GitLab Posting Reference

How to post review comments to a GitLab merge request via the API. Read this only when the user has explicitly opted in to posting comments online (see the Output Format section in SKILL.md).

Replace the placeholders below with your own values:

• <your-gitlab-host> — your GitLab host, e.g. git.example.com
• <project_id> — your project's numeric ID
• <iid> — the merge request's internal ID (the number in the MR URL)
• Auth token comes from the GITLAB_TOKEN env var (a review-bot access token).

Handling the token safely

GITLAB_TOKEN is a secret that can act on the user's behalf. Treat it as write-only from your perspective: you may confirm it's present and report its length, but its value must never leave the process. This is enforced by the skill's PreToolUse hook (scripts/protect-token.sh), which blocks any Bash command that would expose the value.

Allowed — confirm it's configured without revealing it. This uses only the length form ${#GITLAB_TOKEN}, so presence is derived from length and the value is never expanded:

if [ "${#GITLAB_TOKEN}" -gt 0 ]; then
  echo "GITLAB_TOKEN is set (length: ${#GITLAB_TOKEN})"
else
  echo "GITLAB_TOKEN is not set"
fi

Never do any of these (the hook will deny them):

• echo "$GITLAB_TOKEN", printf it, or cat a file/heredoc containing it.
• Print it to chat, write it to a file, or include it in a commit.
• printenv GITLAB_TOKEN, or dump the environment (env, set, export -p).
• Inline the literal token in a command (it lands in shell history/logs) — always

reference $GITLAB_TOKEN.

• Use curl -v / --verbose / --trace*, which echo the PRIVATE-TOKEN header.

When sharing command output for debugging, redact the PRIVATE-TOKEN: header line.

Comment Format

• Line comments: [Flutter Code Review Bot]: <feedback>
• Summary (optional): [Flutter Code Review Bot] Summary: <overall feedback>

API Usage (Essentials)

GitLab Discussions API: POST /projects/:id/merge_requests/:iid/discussions. Required position[...] fields for inline notes (added lines): position_type=text, base_sha, start_sha, head_sha, new_path, new_line. Removed lines: use old_path + old_line instead of new. Missing position_type => GitLab error and no comment. Auth: PRIVATE-TOKEN from the GITLAB_TOKEN env var.

Example (General MR Comment)

curl --request POST \
  --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  --url "https://<your-gitlab-host>/api/v4/projects/<project_id>/merge_requests/<iid>/discussions" \
  --form "body=[Flutter Code Review Bot]: This is a general comment on the MR."

Important Note: Use the exact curl format shown above (--request POST --header ... --url ... --form ...) for posting comments to avoid 401 Unauthorized errors. Alternative formats like -X POST -H ... may not authenticate properly with the API.

Inline Diff Comment (Minimal Example)

curl -s -X POST \
  -H "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  "https://<your-gitlab-host>/api/v4/projects/<project_id>/merge_requests/<iid>/discussions" \
  --form "body=[Flutter Code Review Bot]: Feedback" \
  --form "position[position_type]=text" \
  --form "position[base_sha]=<base>" \
  --form "position[start_sha]=<start>" \
  --form "position[head_sha]=<head>" \
  --form "position[new_path]=lib/.../file.dart" \
  --form "position[new_line]=42"

Fetch diff_refs (useful when running locally):

curl -s -H "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  "https://<your-gitlab-host>/api/v4/projects/<project_id>/merge_requests/<iid>" \
  | grep -A 6 '"diff_refs"'

Fast Checklist

1. Get diff_refs (base/start/head) from MR JSON. 2. Confirm absolute line number in current file (nl -ba file | grep context). 3. POST with all required fields; verify response contains "type":"DiffNote".

Failure quick-fix: missing note => check position_type; invisible => wrong line; 400/error => refresh SHAs.

Automated Approval

Use ONLY after verdict = APPROVED and: no blocking notes, all inline comments visible, bot not already approved, pipeline not failing.

Approve:

curl -s -X POST -H "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  "https://<your-gitlab-host>/api/v4/projects/<project_id>/merge_requests/<iid>/approve"