Python Code Review Expert

⚠️ MANDATORY COMPLIANCE ⚠️

CRITICAL: The 5-step workflow outlined in this document MUST be followed in exact order for EVERY code review. Skipping steps or deviating from the procedure will result in incomplete and unreliable reviews. This is non-negotiable.

File Structure

SKILL.md (this file): Main instructions and MANDATORY workflow
examples.md: Review scenarios with before/after examples

Context: Python and security domain context loaded via

contextProvider.getDomainIndex("python")

and

contextProvider.getDomainIndex("security")

. See ContextProvider Interface.

context_detection.md

common_issues.md

{framework}_patterns.md

```
security_guidelines.md
```
,
```
owasp_python.md
```

Memory: Project-specific memory accessed via
```
memoryStore.getSkillMemory("python-code-review", "{project-name}")
```
. See MemoryStore Interface.

templates/:

report_template.md

inline_comment_template.md

Review Focus Areas

Deep reviews evaluate 8 critical dimensions in the changed code:

Production Quality: Correctness, edge cases, error recovery, resilience
Deep Bugs: Race conditions, memory leaks, resource exhaustion, subtle logic errors
Security: Injection flaws, auth bypasses, insecure deserialization, data exposure
Performance: Algorithmic complexity, N+1 queries, memory inefficiency, I/O blocking
Architecture: Tight coupling, missing abstractions, SOLID violations, circular deps
Reliability: Transaction safety, error handling, resource leaks, idempotency
Scalability: Concurrency issues, connection pooling, pagination, unbounded consumption
Testing: Missing critical tests, inadequate edge case coverage

Note: Focus on substantive issues requiring human judgment, not style/formatting details. Reviews are performed on changed code only, using the

get-git-diff

skill to identify modifications.

MANDATORY WORKFLOW (MUST FOLLOW EXACTLY)

⚠️ STEP 1: Identify Changed Files via Git Diff (REQUIRED)

YOU MUST:

Invoke the
get-git-diff
skill to identify changed Python files
Ask clarifying questions to determine comparison scope:
- Which commits/branches to compare? (e.g.,
```
HEAD^ vs HEAD
```
  ,
```
main vs feature-branch
```
  )
- If not specified, default to comparing current changes against the default branch
- Use the diff output to extract the list of modified Python files (
```
.py
```
  extension)
If no Python files were changed, inform the user and exit gracefully
Focus subsequent review ONLY on the files identified in the diff

DO NOT PROCEED WITHOUT GIT DIFF ANALYSIS

⚠️ STEP 2: Load Project Memory & Context Detection (REQUIRED)

YOU MUST:

CHECK PROJECT MEMORY FIRST:
- Identify the project name from the repository root or ask the user
- Use
```
memoryStore.getSkillMemory("python-code-review", "{project-name}")
```
  to load project-specific patterns
- Cross-skill discovery: Use
```
memoryStore.getByProject("{project-name}")
```
  to check for schema analysis results, test findings, or other skill insights
- If memory exists: Review previously learned patterns, frameworks, and project-specific context
- If no memory exists (empty result): Note this is first review, you will create memory later
USE CONTEXT INDEXES FOR EFFICIENT LOADING:
- Use
```
contextProvider.getDomainIndex("python")
```
  to understand Python context files and when to use each
- Use
```
contextProvider.getDomainIndex("security")
```
  to understand security context files

See ContextProvider and MemoryStore interfaces. 3. Analyze changed files' structure and imports 4. Use

context_detection.md

to identify framework (as guided by the python index) 5. Determine which specific context files to load based on the indexes (don't load all files) 6. Ask clarifying questions in Socratic format:

What is the purpose of these changes?
Specific concerns to focus on?
Deployment environment?
Any project-specific conventions or patterns to be aware of?

DO NOT PROCEED WITHOUT COMPLETING THIS STEP

⚠️ STEP 3: Read Relevant Context Files (REQUIRED)

YOU MUST use the indexes to load only relevant files:

Use the domain indexes from Step 2 to determine which context files to load:

ALWAYS: Use
```
contextProvider.getAlwaysLoadFiles("python")
```
to load universal anti-patterns and deep bugs (e.g.,
```
common_issues.md
```
)
Based on framework detected: Use
```
contextProvider.getConditionalContext("python", detection)
```
to load framework-specific patterns:
- If Django detected: Loads
```
django_patterns.md
```
- If Flask detected: Loads
```
flask_patterns.md
```
- If FastAPI detected: Loads
```
fastapi_patterns.md
```
- If data science detected: Loads
```
datascience_patterns.md
```
- If ML detected: Loads
```
ml_patterns.md
```
For security-sensitive code: Use
```
contextProvider.getCrossDomainContext("python", triggers)
```
where triggers include detected security concerns:
- Auth/authorization code: Loads both security files
- User input handling: Loads
```
security_guidelines.md
```
- Database queries: Loads
```
security_guidelines.md
```
- File operations: Loads
```
security_guidelines.md
```
- Comprehensive audit: Loads both
```
security_guidelines.md
```
  AND
```
owasp_python.md
```

Progressive loading: Only load files relevant to the detected framework and code type. The ContextProvider respects the 4-6 file token budget automatically.

DO NOT SKIP LOADING RELEVANT CONTEXT FILES

⚠️ STEP 4: Deep Manual Review of Changed Code (REQUIRED)

YOU MUST examine ONLY the changed code for ALL categories below:

Important: While reviewing changed lines, consider the surrounding context to understand:

How changes interact with existing code
Whether changes introduce regressions
Impact on callers and dependent code
Whether the change addresses the root cause or masks symptoms

Review Categories:

Production Readiness: Edge cases, input validation, error recovery, resource cleanup, timeouts Deep Bugs: Race conditions, memory leaks, off-by-one errors, unhandled exceptions, state corruption, infinite loops, integer overflow, timezone issues Architecture: Tight coupling, missing abstractions, SOLID violations, global state, circular dependencies Security: SQL/NoSQL/Command injection, auth bypasses, insecure deserialization, SSRF, XXE, crypto weaknesses, data exposure, missing rate limiting Performance: O(n²) complexity, N+1 queries, memory leaks, blocking I/O in async, missing indexes, inefficient data structures, cache stampede Scalability: Connection pool exhaustion, lock contention, deadlocks, missing pagination, unbounded consumption Reliability: Transaction boundaries, data races, resource leaks, missing idempotency

DO NOT SKIP ANY CATEGORY

⚠️ STEP 5: Generate Output & Update Project Memory (REQUIRED)

YOU MUST ask user for preferred output format:

Option A: Structured report (
```
templates/report_template.md
```
) → executive summary, categorized findings, action items → output to
```
claudedocs/
```
Option B: Inline comments (
```
templates/inline_comment_template.md
```
) → file:line feedback, PR-style
Option C (Default): Both formats

DO NOT CHOOSE FORMAT WITHOUT USER INPUT

For EVERY issue in the output, YOU MUST provide:

Severity: Critical / Important / Minor
Category: Security / Performance / Code Quality / Architecture / Reliability
Description: What is wrong and why it matters
Fix: Concrete code example with improvement
Reference: Link to PEP, OWASP, or framework docs
File:line: Exact location (e.g.,
```
auth.py:142
```
)

Format guidelines:

Explain WHY (not just what)
Show HOW to fix with examples
Be specific with file:line references
Be balanced (acknowledge good patterns)
Educate, don't criticize

DO NOT PROVIDE INCOMPLETE RECOMMENDATIONS

After completing the review, UPDATE PROJECT MEMORY:

Use

memoryStore.update("python-code-review", "{project-name}", ...)

to create or update memory files:

project_overview: Framework, architecture patterns, deployment info
common_patterns: Project-specific coding patterns and conventions discovered
known_issues: Recurring issues or anti-patterns found in this project
review_history: Summary of reviews performed with dates and key findings

Timestamps and staleness tracking are managed automatically by MemoryStore. See MemoryStore Interface for

update()

and

append()

method details.

Compliance Checklist

Before completing ANY review, verify:

Step 1: Git diff analyzed using
```
get-git-diff
```
skill and changed Python files identified
Step 2: Project memory loaded via
```
memoryStore.getSkillMemory()
```
and context detected via
```
contextProvider
```

Step 3: All relevant context files loaded via

contextProvider.getAlwaysLoadFiles()

getConditionalContext()

, and

getCrossDomainContext()

Step 4: Manual review completed for ALL categories on changed code only
Step 5: Output generated with all required fields AND project memory updated via
```
memoryStore.update()
```

FAILURE TO COMPLETE ALL STEPS INVALIDATES THE REVIEW

Version History

v2.2.0 (2026-02-10): Migrated to interface-based context and memory access
- Replaced hardcoded context paths with ContextProvider interface calls
- Replaced hardcoded memory paths with MemoryStore interface calls
- Added references to interface documentation
v2.1.0 (2025-11-14): Refactored to use centralized context and project-specific memory system
- Context files moved to
```
forge-plugin/context/python/
```
  and
```
forge-plugin/context/security/
```
- Project memory stored in
```
forge-plugin/memory/skills/python-code-review/{project-name}/
```
- Added project memory loading and persistence in workflow
v2.0.0 (2025-11-13): Changed to diff-based review using
```
get-git-diff
```
skill - reviews only changed code
v1.1.0 (2025-11-13): Removed automated analysis and linting/formatting tools
v1.0.0 (2025-11-13): Initial release

python-code-review

NPX Install

Tags

SKILL.md Content