gstack-review: Multi-Perspective Code Review

Review Framework

When asked to review code, follow this three-perspective framework. Run all steps systematically.

Step 0: Detect What to Review

Priority order for review scope:

1. 1. Uncommitted changes (git diff HEAD) — if working directory is dirty
2. Specific files mentioned by user
3. Branch diff vs main — if on a feature branch
4. Recent commits — if no clear scope

CODEBLOCK0

Step 1: Gather Context

Before reviewing, collect:

CODEBLOCK1

Step 2: Read Changed Files

For each changed file, read the full content to understand context. Don't just look at the diff — read the surrounding code.

CODEBLOCK2

Step 3: CEO / Product Perspective

Ask: Does this code serve the business and users?

Review from a product-thinking perspective:

• - Correctness: Does this actually solve the stated problem?
• Complexity: Is this 10x simpler than the previous approach? Or did we add an abstraction layer that solves nothing?
• Product signal: Is this a feature users asked for, or engineer-invented complexity?
• Scope creep: Did the diff grow beyond its original purpose?
• Tech vs business: Is this engineering for its own sake, or does it genuinely ship value?

Key question: "If I had to explain this change to the CEO in 30 seconds, would they be excited or confused?"

Step 4: Engineering Perspective

Ask: Is this code sound, maintainable, and safe?

• - Architecture: Does this fit the existing patterns? Or did we invent a new framework within a framework?
• Error handling: Are all failure modes handled? (network, disk, invalid input, timeouts)
• Resource management: Connections closed? Memory leaked? Background tasks cancelled?
• Dependencies: Did we add a new heavy dependency when a stdlib call would suffice?
• Security: SQL injection, XSS, auth bypass, secrets in code, overly permissive CORS?
• Performance: N+1 queries? Unindexed queries in loops? Memory-allocating operations in hot paths?
• API design: Are interfaces clean and composable, or did we leak internal state?

Code quality signals:

• - Functions under 30 lines? Exceptions are allowed but need strong justification.
• Meaningful variable/function names? No temp2_final_v3 patterns.
• Comments that explain why, not what? (the code shows what)
• Tests that test behavior, not implementation?

Step 5: QA / Testing Perspective

Ask: Would this pass a senior engineer's gut check for correctness?

• - Test coverage: Are the changed paths actually tested? Not just "tested" but validated?
• Edge cases: Empty input, max length, null bytes, unicode edge cases, concurrent access
• Happy path: Does the main user flow actually work end-to-end?
• Failure modes: What breaks when this code is wrong? Can a user detect it?
• Smoke tests: Does it at least import/parse/load without crashing?
• Test quality: Are tests asserting on behavior or mocking everything and asserting on internals?

Step 6: Assemble the Review

Present a structured review with three clearly labeled sections.

Review Output Template

CODEBLOCK3

Review Principles

1. 1. Be direct. Don't hedge. "This is wrong" is more useful than "this might be worth considering."
2. Distinguish severity. A missing test on a utility function ≠ a SQL injection vulnerability.
3. Context matters. Code that looks wrong in isolation might be the right solution for the system.
4. Praise good work. If the code is clean, simple, and well-tested, say so. Reinforce the pattern.
5. Actionable over academic. "Consider using a WeakMap" is less useful than "Replace new Map() with new WeakMap() on line 42 to avoid memory leaks in the closure."
6. No bikeshedding. Don't flag style preferences that a linter wouldn't flag. Focus on what matters.

When to Escalate (Don't Review Alone)

Escalate to human review for:

• - 🔴 Security vulnerabilities (auth bypass, injection, data exposure)
• 🔴 Breaking changes to external APIs or database schemas
• 🔴 Complex concurrency or distributed systems changes without expert review
• 🔴 Changes to payment, billing, or access control logic
• 🔴 Anything that would require a rollback plan