macalbert/envilder/code-review-perspectives

Code Review Perspectives

Five parallel analysis perspectives for comprehensive code review. Run independently, then synthesize into a deduplicated prioritised report.

When to Use

• Reviewing PRs or commit ranges
• Auditing code quality before release
• Post-implementation review
• Any read-only code analysis task

Perspectives

1. Correctness

• Runtime errors, logic bugs, off-by-one mistakes
• Unhandled promises, null/undefined risks
• Missing error propagation
• Regressions from changed behavior

2. Architecture

• Hexagonal architecture boundary violations (domain importing infrastructure)
• Port/adapter misuse, DI wiring gaps
• Command/Handler pattern violations
• Layer dependency direction (domain → application → infrastructure)

3. Security

• OWASP Top 10 adapted to this stack (injection, secrets exposure, SSRF)
• Raw secret logging (must use EnvironmentVariable.maskedValue)
• Unsafe process.env access patterns
• Dependency-related CVE signals

4. Conventions

• Biome style (single quotes, semicolons, 2-space indent, trailing commas)
• Test naming: Should_<Expected>_When_<Condition>
• AAA markers: // Arrange, // Act, // Assert: each at most once per test
• InversifyJS decorator usage: @injectable(), @inject(TYPES.X)
• Conventional commits in PR title

5. Complexity (CRAP)

See code-quality-crap skill for formula and thresholds.

• Flag methods with cyclomatic complexity ≥ 4 lacking proportional coverage
• Flag methods with complexity ≥ 6: recommend extraction

Severity Model

Anti-Inflation Rules

• Not Critical unless the exact production failure is objectively demonstrable.
• Not High unless a concrete input or state produces incorrect behavior.
• Convention violations are Low unless they change runtime behavior.
• Missing guards for values guaranteed by the type system are not defects.

Synthesis Procedure

1. Run all 5 perspectives (can be parallel)
2. Merge findings, deduplicate overlaps
3. Assign severity per the model above
4. Order by severity descending
5. For each finding: severity, why it matters, file:line evidence, fix direction

Output Format

Use this standalone format when the caller does not define a workflow envelope:

## Findings
 
### [Critical/High/Medium/Low]: {title}
**File:** {path}:{line}
**Why:** {explanation}
**Fix:** {direction}
 
## Open Questions
- {assumptions or clarifications needed}
 
## Summary
{1-2 sentence overview: AFTER findings, not before}

When the caller requires the canonical ReviewResult envelope from common-verification-first, place these findings under Prioritized findings, preserve the same severity and anti-inflation rules, and map the remaining sections to the corresponding envelope fields. The envelope may add orchestration routing or contract assessment; it does not redefine review semantics.

Verification

After analysis, verify findings before reporting:

1. pnpm test: confirm test suite passes
2. biome check && tsc --noEmit: lint compliance (no modifications)
3. pnpm format:check: formatting (no modifications)
4. Browser checks for website/UI changes (Playwright)
5. Stack-specific: dotnet build/dotnet test, make check-sdk-python

Only report confirmed findings. Downgrade unverified suspicions.

Constraints

• Only report findings for code introduced or modified in the requested diff
• Do not report style-only nits unless they block quality gates
• State assumptions explicitly
• Never modify files during review: read-only analysis only