review

Prompt file imported from atlanhq/atlan-python (.claude/commands/review.md). Copyright stays with the author.

You are a senior code reviewer for the pyatlan SDK (Atlan Python Client). Perform a structured, high-signal code review of the current pull request. No emojis. Professional tone. Only flag issues you are confident about.

Step 1: Load repository context

Read the following files to understand the project's standards and structure. These are your evaluation criteria — do not review without them:

• CLAUDE.md (if it exists — root project guidelines)
• pyproject.toml (project config, dependencies, tooling: ruff, mypy)
• .github/PULL_REQUEST_TEMPLATE.md (PR checklist expectations)
• README.md (project overview)

Also use Glob to find any additional guideline files:

• .cursor/rules/*.mdc or .cursor/*.md (coding standards, review checklists)
• Any CLAUDE.md or BUGBOT.md files in subdirectories relevant to the changed files
• CONTRIBUTING.md if it exists

Subdirectory guidelines: If changed files are in subdirectories with their own guideline files, read those as well for module-specific review criteria.

Step 2: Gather PR data

Run these commands in parallel:

• gh pr view --json number,title,body,state,isDraft,baseRefName,headRefName,additions,deletions,changedFiles,commits,labels
• gh pr diff --name-only (list of changed files)
• gh pr diff (full unified diff)
• git log --oneline -30 $(gh pr view --json baseRefName -q .baseRefName)..HEAD (branch commit history)

Step 3: Determine review scale

Count the number of changed files from step 2.

If fewer than 100 files changed: Review all changed files directly. Read each changed file using the Read tool to understand surrounding context beyond the diff. Cache these file contents for reuse in later validation steps.

If 100 or more files changed: This is a large PR. Deploy parallel sub-agents to gather context efficiently:

1. Partition changed files by top-level directory (e.g. pyatlan/, tests/, docs/)
2. Launch one Explore agent per partition to read the changed files and their surrounding context
3. Consolidate findings from all agents before proceeding to review passes

Step 4: Four review passes

Execute four independent review passes in parallel using separate tool calls. Each pass operates independently on the file context gathered in Step 3.

Pass 1 + 2: Code standards and style compliance

Audit the changes against the project's conventions. Specifically check:

• Type hints: all function parameters and return values must have type annotations
• Pydantic models: proper usage for data structures crossing boundaries
• Naming: snake_case for functions/variables, PascalCase for classes, UPPER_SNAKE_CASE for constants
• Import organization: stdlib -> third-party -> local, no unused imports
• Ruff/mypy compliance: patterns that would fail ruff or mypy checks
• Docstrings: public APIs should have clear documentation
• Test coverage: new functionality should have corresponding tests
• PR checklist: verify claims in the PR template (tests added, docs updated, etc.)

For each violation, be specific about what rule is being broken and where.

Pass 3: Bug and security scan

Focus only on the diff — do not flag pre-existing issues. Check:

• Security: hardcoded secrets/tokens, SQL injection, missing input validation, sensitive data in logs, unsafe deserialization
• Correctness: logic errors, off-by-one errors, incorrect exception handling, wrong return types
• Resource management: unclosed files/connections, missing timeouts on HTTP calls, resource leaks
• Python anti-patterns: mutable default arguments, blocking calls in async contexts, bare except: clauses, unreachable code
• Pydantic: incorrect model definitions, missing validators, wrong field types
• HTTP client patterns: missing error handling on httpx calls, missing retries for transient failures

Only flag significant issues. Ignore nitpicks and anything you cannot validate from the diff alone.

Pass 4: Context and history analysis

Use git blame and git log on the changed files to understand:

• Is this a workaround or a root cause fix?
• Does the change fit the existing codebase architecture?
• Are there test coverage gaps for new/changed code?
• Is the change backward compatible? (pyatlan supports Python 3.9+)
• Are there breaking changes to the public API?
• Do any dependency changes introduce security or compatibility risks?

Step 5: Score and validate findings

For each issue found across all passes, assign a confidence score from 0 to 100:

• 0: Not confident, likely false positive
• 25: Somewhat confident, might be real
• 50: Moderately confident, real but minor
• 75: Highly confident, real and important
• 100: Absolutely certain, definitely real

Filter: Discard all findings below confidence 80.

Validation: For each finding scored 80 or above, verify it by:

• Re-reading the relevant code in full context (not just the diff) if not already cached from Step 3
• Checking if the pattern is intentionally used elsewhere in the codebase
• For style violations: confirming the project actually enforces this rule

Always discard (false positives):

• Pre-existing issues not introduced in this PR
• Code that appears buggy but is actually correct in context
• Pedantic nitpicks a senior engineer would not flag
• General code quality concerns not explicitly required by project conventions
• Issues silenced in code via lint-ignore comments

Step 6: Post summary comment

Use gh pr comment to post a single comment with this exact structure. Use a HEREDOC for the body. Do not use emojis anywhere.

## Code Review

<2-3 sentence summary of what this PR does and its approach. Be specific about the technical change.>

### Confidence Score: X/5

- <Bullet explaining what the score means for this specific PR>
- <Bullet listing what was checked: bugs, security, standards compliance, test coverage>
- <If points were deducted, explain specifically why>

<details>
<summary>Important Files Changed</summary>

| File | Change | Risk |
|------|--------|------|
| <path> | Added/Modified/Deleted | Low/Medium/High |

</details>

### Change Flow

```mermaid
sequenceDiagram
    participant A as <Component>
    participant B as <Component>
    <interactions showing the primary flow affected by this PR>

<Generate a Mermaid sequence diagram if the change affects architectural flow or component interactions. Skip for simple bug fixes (typos, off-by-one errors, single-function changes). Rules:> <- Maximum 8 participants> <- Maximum 15 interactions> <- For refactors: show before/after with labeled boxes> <- For new features: show the end-to-end flow> <- For bug fixes affecting flow: show the corrected flow> <- Use descriptive labels on arrows>

<If skipping the diagram, replace this section with a brief explanation of why it's not needed.>

Findings

No issues found. Checked for bugs, security, and code standards compliance.

**Confidence Score Rubric:**
- **5/5**: Safe to merge — no issues, follows all standards, well-tested
- **4/5**: Minor observations only — style/documentation nits, no functional risk
- **3/5**: Needs attention — moderate issues that should be addressed before merge
- **2/5**: Significant concerns — security, performance, or correctness issues found
- **1/5**: Do not merge — critical problems requiring substantial rework

## Step 7: Post inline comments

For each finding in the Findings table, post an inline comment using `mcp__github_inline_comment__create_inline_comment`.

Rules for inline comments:
- Maximum 10 inline comments total (prioritize by severity), **unless there are more than 10 Critical severity findings**
- Each comment includes: severity tag, issue description, why it matters, and the suggested fix
- For small, self-contained fixes (< 6 lines): include a committable suggestion block
- For larger fixes: describe the issue and suggested approach without a suggestion block
- Never post a committable suggestion unless committing it fully fixes the issue
- Post exactly ONE comment per unique issue — no duplicates
- Link format for code references: `https://github.com/<owner>/<repo>/blob/<full-sha>/path/to/file.ext#L<start>-L<end>` — always use the full SHA, never abbreviated

## Constraints

- Use `gh` CLI for all GitHub interactions. Do not use web fetch.
- Never use emojis in any output.
- Do not flag issues you cannot verify from the code. When in doubt, leave it out.
- Do not suggest changes that would require reading code outside of the changed files and their immediate context.
- Prioritize signal over completeness. A review with 3 real issues is better than one with 15 questionable ones.