Code review

AI Code Review

Perform a comprehensive code review on a repository pull request, combining available business context (linked work items and design documents) with code-level analysis, and post findings directly as PR comments.

Trigger-only routing guard: if the prompt already asks for a PR review, treat code-review as selected. Do not convert the turn into a host-platform or skill-installation audit. Do not probe local resource registries, editor state, or skill availability. If the user forbids shell, do not run shell commands even for local inspection. Ask only for missing review inputs such as REPO_PROVIDER, REPO_NAMESPACE, REPO_NAME, and PR_NUMBER.

Capability Dependencies

Required:

• repo

Optional:

• tracker
• docs
• ci

Inputs

Variable	Required	Description	Example
REPO_PROVIDER	Yes	Repository provider	bitbucket
REPO_NAMESPACE	Yes	Repository namespace / project key	sample
REPO_NAME	Yes	Repository name / slug	sample-repo
PR_NUMBER	Yes	Pull request number	16

Provider examples: bitbucket, github, gitlab.

Bitbucket example values: REPO_PROVIDER=bitbucket, REPO_NAMESPACE=sample, REPO_NAME=sample-repo, PR_NUMBER=16. GitHub example values: REPO_PROVIDER=github, REPO_NAMESPACE=sample-org, REPO_NAME=sample-repo, PR_NUMBER=16. GitLab example values: REPO_PROVIDER=gitlab, REPO_NAMESPACE=sample-group, REPO_NAME=sample-repo, PR_NUMBER=16.

Ask the user for all missing required inputs in a single plain-text message. Present the parameter table above and wait for their response. Do NOT use interactive selection prompts — these are free-text values (IDs, keys, slugs) that the user types directly.

Trigger-only validation mode: if the user explicitly says this is only a skill trigger test, follow ../using-orbit/references/safety-rules.md and ask only for the missing inputs from the table above. Do not ask for host platform, skill name, trigger entry, report language, or generic success criteria.

Missing-input collection rules

Ask for all missing required inputs in a single plain-text message. Prefer the smallest missing set that unblocks the selected review route. Use normalized shared field names from ../using-orbit/references/common-input-contract.md whenever the input belongs to the shared capability contract. Avoid provider-specific aliases when the shared field name already expresses the same fact.

Before You Start

Read ../using-orbit/references/safety-rules.md, ../using-orbit/references/cli-patterns.md, and ../using-orbit/references/output-conventions.md for shared conventions that apply to all steps below.

Treat ../using-orbit/references/ as the source of truth for shared review conventions instead of repeating those conventions in full here.

Preflight Configuration Check

Follow the capability-based preflight protocol in ../using-orbit/references/safety-rules.md. Resolve repo first. If tracker and docs providers are installed, use them for linked work-item and design-document checks. If ci is installed and build-state clarification is needed, use it. When the selected ci provider is github-workflow, prefer github-workflow build get --namespace {{REPO_NAMESPACE}} --repo {{REPO_NAME}} --number <RUN_ID> for run status clarification and github-workflow build console --namespace {{REPO_NAMESPACE}} --repo {{REPO_NAME}} --number <RUN_ID> for logs instead of inventing repo-provider-specific build status reads.

Step 1: Read PR Information and Diff

Use the repository capability for the active provider.

Bitbucket example:

bitbucket pr get --project {{REPO_NAMESPACE}} --repo {{REPO_NAME}} --id {{PR_NUMBER}}
bitbucket pr changes --project {{REPO_NAMESPACE}} --repo {{REPO_NAME}} --id {{PR_NUMBER}}
bitbucket pr diff --project {{REPO_NAMESPACE}} --repo {{REPO_NAME}} --id {{PR_NUMBER}}

GitHub example:

github pr get --namespace {{REPO_NAMESPACE}} --repo {{REPO_NAME}} --number {{PR_NUMBER}}
github pr changes --namespace {{REPO_NAMESPACE}} --repo {{REPO_NAME}} --number {{PR_NUMBER}}
github pr diff --namespace {{REPO_NAMESPACE}} --repo {{REPO_NAME}} --number {{PR_NUMBER}}

GitLab example:

gitlab pr get --namespace {{REPO_NAMESPACE}} --repo {{REPO_NAME}} --number {{PR_NUMBER}}
gitlab pr changes --namespace {{REPO_NAMESPACE}} --repo {{REPO_NAME}} --number {{PR_NUMBER}}
gitlab pr diff --namespace {{REPO_NAMESPACE}} --repo {{REPO_NAME}} --number {{PR_NUMBER}}

Use the provider that matches REPO_PROVIDER.

Step 2: Get Business Context

If no tracker provider is installed, skip linked work-item and AC coverage checks. If no docs provider is installed, skip design-document consistency checks. Record any skipped checks in the final review summary.

If a tracker provider is installed, use the shared provider linking strategy to resolve linked work items for the active repository provider.

Bitbucket example:

bitbucket jira pr-issues --project {{REPO_NAMESPACE}} --repo {{REPO_NAME}} --id {{PR_NUMBER}}

GitHub example:

Use the shared provider linking strategy for GitHub: explicit user context first, then issue-key extraction from PR title, body, branch names, and commits.

GitLab example:

Use the shared provider linking strategy for GitLab: explicit user context first, then issue-key extraction from merge request title, description, branch names, and commits.

Use the provider-specific linked-work-item path only when the selected provider exposes it natively.

If pr-issues returns empty (PR not linked to a work item):

• Skip AC coverage check; review code dimensions only (Bug / Security / Maintainability)
• Note in the PR summary comment: "⚠️ No linked work item — cannot check AC coverage. Recommend developers add a link."
• Skip design-document search that depends on linked work-item keys; go directly to Step 3

If linked work items exist, read Story details:

jira issue get --key <ISSUE_KEY>

GitHub Issue example:

github-issue issue get --namespace <OWNER_OR_ORG> --repo <REPO> --number <ISSUE_NUMBER>

Check if AC exists: if the description contains none of "验收标准", "AC", "Acceptance Criteria", mark as "Story has no AC" and skip AC coverage check in later steps.

If a docs provider is installed, search for linked design documents using the exact issue key phrase so unrelated pages that only share the numeric suffix do not count as a design-document match:

confluence search content --cql "text ~ '\"<ISSUE_KEY>\"'" --type page --limit 5

Obsidian provider example:

obsidian content search --query "<ISSUE_KEY>"

If found, read core content:

confluence page get --id <PAGE_ID> --expand body.storage

Step 3: Large PR Tolerance

If changed files > 20 or total diff lines > 500:

1. List all changed files with per-file change count
2. Sort by change volume descending
3. Prioritize reviewing the top 10 core files
4. Ask the user whether to continue with the remaining files

Step 4: Get Line-Level Anchor Information

Use the repository capability for the active provider to get diff anchor metadata.

Bitbucket example:

bitbucket pr file-diff --project {{REPO_NAMESPACE}} --repo {{REPO_NAME}} --id {{PR_NUMBER}} --path <FILE_PATH>

GitHub example:

github pr get --namespace {{REPO_NAMESPACE}} --repo {{REPO_NAME}} --number {{PR_NUMBER}}

GitLab example:

gitlab pr get --namespace {{REPO_NAMESPACE}} --repo {{REPO_NAME}} --number {{PR_NUMBER}}

Record provider-native inline-comment context for the selected provider. For Bitbucket this includes fromHash, toHash, and diffType; for GitHub use the commit SHA and changed file metadata required by pr review-comment; for GitLab use the merge-request diff context plus file path and line information needed by pr review-comment.

Step 5: AI Analysis (Review Core)

Combine available business context (linked work items and design documents) with code changes. Review across five dimensions:

A. Business Logic Correctness

• Does the code correctly implement the linked work-item requirements when a tracker provider is available?
• When AC exists, check each AC item: mark as implemented / not implemented

B. Potential Bugs

• Null pointer, out-of-bounds, resource leaks, concurrency issues
• Boundary condition handling

C. Security Risks

• SQL injection, XSS, hardcoded passwords, path traversal
• Sensitive data handling compliance

D. Design Consistency

• If design documents are available, does it follow architecture constraints from the design document?
• Naming, layering, interface design — does it match project conventions?

E. Maintainability

• Is the code clear and readable?
• Are there duplicate logic patterns that should be extracted?

Classify each finding by severity (see ../using-orbit/references/output-conventions.md): 🚫 Blocks merge / 🔴 Must fix / 🟡 Suggested improvement / 🟢 Optional optimization

Step 6: Post Line-Level Comments (requires user confirmation)

Follow ../using-orbit/references/safety-rules.md write confirmation protocol.

Before posting, display a summary table of ALL planned line-level comments:

#	File	Line	Severity	Finding
1	path/to/file	42	🔴	Brief description
...	...	...	...	...

Wait for user confirmation. Only after confirmation, post each comment: Bitbucket example:

bitbucket pr review-comment --project {{REPO_NAMESPACE}} --repo {{REPO_NAME}} --id {{PR_NUMBER}} --path <FILE_PATH> --line <LINE_NUMBER> --side new --line-type <ADDED|REMOVED|CONTEXT> --from-hash <FROM_HASH> --to-hash <TO_HASH> --diff-type <DIFF_TYPE> --text "<review comment>"

GitHub example:

github pr review-comment --namespace {{REPO_NAMESPACE}} --repo {{REPO_NAME}} --number {{PR_NUMBER}} --commit-id <COMMIT_SHA> --path <FILE_PATH> --line <LINE_NUMBER> --side RIGHT --text "<review comment>"

Comment format:

• Start with severity marker: 🚫 / 🔴 / 🟡 / 🟢
• Describe the issue
• Provide fix suggestion or code example
• If AC-related, reference the specific AC item

Step 7: Post PR Summary Comment (requires user confirmation)

Follow ../using-orbit/references/safety-rules.md write confirmation protocol.

Display the full summary comment content first. Wait for user confirmation, then post: Bitbucket example:

bitbucket pr comment --project {{REPO_NAMESPACE}} --repo {{REPO_NAME}} --id {{PR_NUMBER}} --text "<summary comment>"

GitHub example:

github pr comment --namespace {{REPO_NAMESPACE}} --repo {{REPO_NAME}} --number {{PR_NUMBER}} --text "<summary comment>"

Summary comment format:

Include skipped checks whenever tracker, docs, or linked-context coverage was unavailable in this run.

## 🤖 AI Code Review Summary

**Change Overview**: <one-sentence summary>

**Review Scope**: Reviewed X / Y changed files <if partial, list skipped files: "Files not reviewed: file1, file2, ...">

**AC Coverage** (if no AC, note: "⚠️ Story has no AC, skipped AC coverage check, recommend adding AC")
- ✅ AC 1: <implemented>
- ✅ AC 2: <implemented>
- ❌ AC 3: <not implemented, reason>

**Skipped Checks** (only if applicable)
- <skipped check and reason>

**Review Findings**
- 🚫 Blocks merge: X items
- 🔴 Must fix: Y items
- 🟡 Suggested improvement: Z items
- 🟢 Optional optimization: W items

**Recommendation**: <merge / needs changes before re-review>

Step 8: Update PR Description (requires user confirmation)

⚠️ This will REPLACE the existing PR description entirely, not append.

First read the current PR description (already fetched in Step 1 via pr get). Show the user both the current description and the proposed new description side by side before asking for confirmation.

Follow ../using-orbit/references/safety-rules.md write confirmation protocol.

Display the generated description first, then after confirmation:

Bitbucket example:

bitbucket pr update --project {{REPO_NAMESPACE}} --repo {{REPO_NAME}} --id {{PR_NUMBER}} --description "<available business context + design rationale + change summary + impact scope>"

GitHub example:

github pr update --namespace {{REPO_NAMESPACE}} --repo {{REPO_NAME}} --number {{PR_NUMBER}} --description "<available business context + design rationale + change summary + impact scope>"

Use the provider that matches REPO_PROVIDER.

Output

• Line-level review comments on provider PRs (with fix suggestions)
• PR summary comment (AC coverage + review stats + merge recommendation)
• PR description auto-completion (business context + design rationale + change summary)