Architecture Review

Table of Contents

• Quick Start
• When to Use
• Progressive Loading
• Required TodoWrite Items
• Workflow
• Step 1: Establish Context (`arch-review:context-established`))
• Step 2: ADR Audit (`arch-review:adr-audit`))
• Step 3: Interaction Mapping (`arch-review:interaction-mapping`))
• Step 4: Principle Checks (`arch-review:principle-checks`))
• Step 5: Risks and Actions (`arch-review:risks-actions`))
• Testing

Testing

Run pytest plugins/pensive/tests/skills/test_architecture_review.py to verify review logic.

• Architecture Principles Checklist
• Coupling
• Cohesion
• Layering
• Evolution

Architecture Review Workflow

Architecture assessment against ADRs and design principles.

Quick Start

/architecture-review

When To Use

• Approving reimplementations.
• Large-scale refactoring reviews.
• System design changes.
• New module/service introduction.
• Dependency restructuring.

When NOT To Use

• Selecting architecture paradigms - use archetypes

skills

• API surface review - use api-review
• Selecting architecture paradigms - use archetypes

skills

• API surface review - use api-review

Progressive Loading

Load modules based on review scope:

• `modules/adr-audit.md` (~400 tokens): ADR verification and documentation.
• `modules/coupling-analysis.md` (~450 tokens): Dependency analysis and boundary violations.
• `modules/principle-checks.md` (~500 tokens): Code quality, security, and performance.
• `modules/fpf-methodology.md` (~800 tokens): FPF (Functional, Practical, Foundation) multi-perspective review methodology.

Load all modules for full reviews. For focused reviews, load only relevant modules.

Required TodoWrite Items

1. arch-review:context-established: Repository, branch, motivation. 2. arch-review:adr-audit: ADR verification and new ADR needs. 3. arch-review:interaction-mapping: Module coupling analysis. 4. arch-review:invariant-check: Invariant conflict detection and 3-option analysis. 5. arch-review:principle-checks: LoD, security, performance. 6. arch-review:risks-actions: Recommendation and follow-ups. 7. arch-review:findings-verified

Workflow

Step 1: Establish Context (arch-review:context-established)

Confirm repository and branch:

pwd
git status -sb

Document:

• Feature/bug/epic motivating review.
• Affected subsystems.
• Architectural intent from README/docs.
• Design trade-off assumptions.

Step 2: ADR Audit (arch-review:adr-audit)

Load: `modules/adr-audit.md`

• Locate ADRs in project.
• Verify required sections.
• Check status flow.
• Confirm immutability compliance.
• Flag need for new ADRs.

Step 3: Interaction Mapping (arch-review:interaction-mapping)

Load: `modules/coupling-analysis.md`

• Diagram before/after module interactions.
• Verify composition boundaries.
• Check data ownership clarity.
• Validate dependency flow direction.
• Identify coupling violations.

Step 3.5: Invariant Conflict Detection (arch-review:invariant-check)

Before checking principles, identify whether the changes conflict with existing design invariants. This is the highest-judgment step in architecture review: models get this wrong more often than any other call.

Identify existing invariants:

1. Scan ADRs for recorded decisions still in "accepted" status 2. Check module boundaries (are imports crossing layers that previously didn't?) 3. Check data flow direction (does data now flow in a new direction?) 4. Check API contracts (are public interfaces changing shape?) 5. Check structural patterns (is a new pattern being introduced alongside an existing one?)

# Detect boundary crossings in changed files
git diff --name-only | while read f; do
  head -20 "$f" 2>/dev/null | rg "^(import|from|use |require)" || true
done

When a conflict is detected:

Do NOT recommend a resolution. Present the three options and escalate to human judgment:

Output format:

### Invariant Conflicts

[I1] **[Invariant name]** — [what decision it represents]
- **Location**: file.py:42
- **Anchor**: `verbatim source text at line 42`
- **Conflict**: [what change clashes]
- **Options**: Preserve / Layer / Revise
- **Recommendation**: ESCALATE TO HUMAN
- **Risk if wrong**: [what compounds]

Why this matters: Bad invariant decisions compound. After a few wrong calls the codebase becomes unsalvageable. This is a judgment problem rather than a context problem: the agent should surface it, not solve it.

Step 4: Principle Checks (arch-review:principle-checks)

Load: `modules/principle-checks.md`

• Law of Demeter.
• Anti-slop patterns.
• Security (input validation, least privilege).
• Performance (N+1 queries, caching).

Step 5: Risks and Actions (arch-review:risks-actions)

Summarize using imbue:diff-analysis/modules/risk-assessment-framework:

• Current vs proposed architecture.
• Business impact.
• Technical debt implications.

List follow-ups with owners and dates.

Provide recommendation:

• Approve: Architecture sound.
• Approve with actions: Minor issues to address.
• Block: Fundamental problems requiring redesign.

Architecture Principles Checklist

Coupling

• [ ] Dependencies follow defined boundaries.
• [ ] No circular dependencies.
• [ ] Extension points used properly.
• [ ] Abstractions don't leak.

Cohesion

• [ ] Related functionality grouped.
• [ ] Single responsibility per module.
• [ ] Clear module purposes.

Layering

• [ ] Layers have clear responsibilities.
• [ ] Dependencies flow downward.
• [ ] No layer bypassing.

Invariants

• [ ] Existing design invariants identified.
• [ ] Conflicts between changes and invariants surfaced.
• [ ] Three-option analysis (preserve/layer/revise) presented.
• [ ] Invariant changes escalated to human judgment.
• [ ] No silent invariant revisions in the diff.

Evolution

• [ ] Changes are reversible.
• [ ] Migration paths are clear.
• [ ] ADRs document decisions.

Verify Findings Are Grounded (arch-review:findings-verified)

Every finding must cite a real location and a verbatim anchor. Write findings to .review/findings.json and confirm each citation resolves:

python plugins/imbue/scripts/citation_verifier.py \
  --findings .review/findings.json --repo-root .

Drop or label UNVERIFIED any finding the verifier fails (exit 1); only verified findings enter the report. See Skill(imbue:review-core) Step 5 and Skill(imbue:structured-output) for the schema.

Exit Criteria

• Context established, ADR audit complete, interaction mapping done,

invariant conflicts surfaced, principle checks run, risks and actions documented.

• Every reported finding carries a Location + verbatim Anchor

confirmed by citation_verifier.py (exit 0), or unverified findings were dropped or labeled UNVERIFIED.

ADR Audit Module

detailed ADR discovery, validation, and governance patterns.

ADR Location Patterns

Common ADR locations by project type:

# Standard locations
wiki/architecture/
docs/adr/
docs/decisions/
architecture/decisions/
.adr/

# Search pattern
find . -type f -name "*ADR*" -o -name "*decision*" | grep -E "\.(md|txt)$"

Required ADR Sections

Every ADR must include:

1. Title

Clear, specific decision statement:

• "Use PostgreSQL for primary datastore"
• "Adopt hexagonal architecture pattern"
• "Implement JWT-based authentication"

2. Status

Must follow strict progression:

Proposed → Reviewed → Accepted
                    ↓
              Superseded (when invalidated)

Rules:

• Status changes are append-only
• Date each status transition
• Never delete/modify accepted ADRs
• Use "Superseded by ADR-XXX" to replace

3. Context

Document the forces at play:

• Business requirements
• Technical constraints
• Team capabilities
• Timeline pressures
• Existing architecture

4. Decision

The "we will..." statement:

• Clear action chosen
• Implementation approach
• Key design choices

5. Alternatives Considered

For each alternative:

• Description
• Pros/cons
• Why rejected

Minimum 2 alternatives required.

6. Consequences

Positive:

• Benefits gained
• Problems solved
• Capabilities enabled

Negative:

• Trade-offs accepted
• Technical debt incurred
• Complexity added

Neutral:

• Changes required
• Migration steps
• Training needs

7. Metadata

Date: YYYY-MM-DD
Author: [name]
Status: [status]
Supersedes: [ADR-XXX] (if applicable)
Superseded-by: [ADR-XXX] (if applicable)

Status Flow Verification

Valid Transitions

• Proposed → Reviewed
• Reviewed → Accepted
• Reviewed → Rejected
• Accepted → Superseded (via new ADR only)

Invalid Transitions

• Proposed -> Accepted (skip review)
• Accepted -> Rejected (use Superseded)
• Superseded -> Accepted (immutable)

Immutability Rules

Once Accepted: 1. Never modify decision content 2. Never change consequences 3. Never delete the ADR 4. Only append status changes

To Replace: 1. Create new ADR with superseding decision 2. Add "Supersedes: ADR-XXX" to new ADR 3. Add "Superseded-by: ADR-YYY" to old ADR 4. Update old ADR status to "Superseded"

Audit Workflow

1. Locate All ADRs

# Find ADR directory
ls -la docs/adr/ wiki/architecture/ 2>/dev/null

# Count ADRs
find . -path "*/adr/*.md" -o -path "*/decisions/*.md" | wc -l

2. Verify Structure

For each ADR:

• [ ] Has all required sections
• [ ] Status follows valid flow
• [ ] Dates are present
• [ ] Alternatives documented (≥2)
• [ ] Consequences specified

3. Check References

# Find ADR references in code
grep -r "ADR-[0-9]" --include="*.md" --include="*.py" --include="*.js"

# Verify backlinks
grep "Superseded-by" docs/adr/*.md

4. Flag Issues

Common problems:

• Missing sections
• Invalid status transitions
• Modified accepted ADRs
• Missing supersession links
• Insufficient alternatives

New ADR Requirements

Flag need for new ADR when:

• Introducing new architectural pattern
• Changing core technology
• Modifying system boundaries
• Adding external dependencies
• Changing security model

Before implementation: 1. Draft ADR with all sections 2. Set status: Proposed 3. Request review 4. Update to Reviewed 5. Gain approval → Accepted 6. Then proceed with implementation

Integration with Architecture Review

Use this module during Step 2 (ADR Audit): 1. Locate ADRs using patterns 2. Verify structure completeness 3. Check status flow validity 4. Confirm immutability compliance 5. Identify missing ADRs for current work 6. Draft new ADRs if needed

Coupling Analysis Module

Systematic analysis of module interactions, boundaries, and dependency flows.

Interaction Mapping Patterns

Visual Representation

Create before/after diagrams:

Before:
┌─────────┐     ┌─────────┐     ┌──────────┐
│Module A │────▶│Module B │────▶│ Database │
└─────────┘     └─────────┘     └──────────┘

After:
┌─────────┐     ┌───────┐     ┌─────────┐     ┌──────────┐
│Module A │────▶│ Cache │────▶│Module B │────▶│ Database │
└─────────┘     └───────┘     └─────────┘     └──────────┘

Dependency Graph Tools

# Python: Generate import graph
pydeps --max-bacon=2 --cluster src/

# TypeScript: Analyze module dependencies
madge --circular --extensions ts src/

# Generic: Find direct dependencies
grep -r "import\|require\|from" src/ | cut -d: -f1 | sort | uniq -c

Composition Boundaries

Boundary Definition

Clear boundaries have: 1. Explicit interfaces - Published contracts 2. Data ownership - Single source of truth 3. Encapsulation - Hidden implementation 4. Stability - Minimal breaking changes

Boundary Types

Module Boundaries:

┌──────────────────────────┐
│   Public API             │
├──────────────────────────┤
│   Internal Logic         │
│   (implementation)       │
└──────────────────────────┘

Layer Boundaries:

┌──────────────────────────┐
│   Presentation Layer     │ ← HTTP/UI
├──────────────────────────┤
│   Application Layer      │ ← Business Logic
├──────────────────────────┤
│   Domain Layer           │ ← Core Models
├──────────────────────────┤
│   Infrastructure Layer   │ ← Database/External
└──────────────────────────┘

Service Boundaries:

Service A          Service B
┌────────┐        ┌────────┐
│  API   │◀──────▶│  API   │
├────────┤        ├────────┤
│  DB A  │        │  DB B  │
└────────┘        └────────┘

Boundary Violations

Ad-hoc Reach-ins:

# Bad: Reaching through module boundary
user.profile.settings.theme.get_color()

# Good: Ask for what you need
user.get_theme_color()

Layering Violations:

# Bad: Domain layer accessing infrastructure
class Order:
    def save(self):
        db.execute("INSERT INTO orders...")

# Good: Infrastructure handles persistence
class OrderRepository:
    def save(self, order: Order):
        db.execute("INSERT INTO orders...")

Data Ownership Analysis

Single Owner Principle

Each data entity has exactly one authoritative owner:

User Data:
├── Auth Service (owner: credentials)
├── Profile Service (owner: profile data)
└── Analytics Service (consumer: read-only)

Ownership Violations

Multiple Writers:

# Bad: Two services modify same data
auth_service.update_user_email()
profile_service.update_user_email()

# Good: Single owner
profile_service.update_email()  # Publishes event
auth_service.handle_email_changed()  # Subscribes to event

Ownership Leaks:

# Bad: Exposing internal structure
def get_user():
    return user_database_model

# Good: Return boundary type
def get_user():
    return UserDTO(id=..., name=...)

Dependency Flow Checking

Expected Flow Patterns

Layered Architecture:

Presentation → Application → Domain → Infrastructure
     ↓              ↓           ↓            ↓
  (no reverse dependencies allowed)

Hexagonal Architecture:

     ┌─────────────┐
     │   Domain    │ ← Core (no dependencies)
     └──────┬──────┘
            │
  ┌─────────┴─────────┐
  │   Application     │ ← Orchestration
  └────────┬──────────┘
           │
  ┌────────┴─────────┐
  │   Adapters       │ ← External interfaces
  └──────────────────┘

Circular Dependency Detection

# Python
pydeps --show-cycles src/

# JavaScript/TypeScript
madge --circular src/

# Manual check
grep -r "from.*import" src/ | # Extract all imports
  python -c "
import sys
from collections import defaultdict

graph = defaultdict(set)
for line in sys.stdin:
    # Parse: file imports module
    # Build graph, detect cycles
"

Dependency Metrics

Afferent Coupling (Ca): Number of modules that depend on this module.

• High Ca = Stable (many dependents)

Efferent Coupling (Ce): Number of modules this module depends on.

• High Ce = Unstable (many dependencies)

Instability (I):

I = Ce / (Ca + Ce)

• I = 0: Maximally stable
• I = 1: Maximally unstable

Ideal Patterns

Stable Abstractions:

• Core domain: Low I (stable)
• Infrastructure: High I (unstable, replaceable)

Dependency Direction:

Unstable → Stable
(changing) depends on (stable)

Side Effects Analysis

Side Effect Categories

1. State Mutations:

# Track mutations
def process_order(order):
    order.status = "PROCESSED"  # Mutation
    notify_customer(order)       # Side effect
    log_event(order)            # Side effect

2. External I/O:

• Database writes
• API calls
• File operations
• Message queue publishing

3. Timing Dependencies:

• Caching
• Rate limiting
• Session management

Containment Strategies

Command-Query Separation:

# Query: No side effects
def get_order_total(order): -> Decimal

# Command: Mutations allowed
def place_order(order) -> None

Effect Tracking:

# Explicit effect types
Effect = Database | API | Cache | Event

def process_payment(order) -> tuple[Result, list[Effect]]:
    effects = []
    # Track all effects
    return result, effects

Cross-Boundary Dependencies

Allowed Patterns

1. Events:

# Service A publishes
event_bus.publish(UserCreated(user_id))

# Service B subscribes
@subscribe(UserCreated)
def handle_user_created(event):
    # React independently

2. Shared Kernel:

# Common domain types
from shared.types import Money, UserId, Email

3. Published APIs:

# Service B calls Service A's API
response = service_a_client.get_user(user_id)

Forbidden Patterns

1. Shared Database:

# Bad: Direct database access across services
user_db.query("SELECT * FROM users")  # From order service

2. Implementation Sharing:

# Bad: Importing internal modules
from service_a.internal.helpers import format_date

Integration with Architecture Review

Use this module during Step 3 (Interaction Mapping): 1. Map all module interactions (before/after) 2. Verify composition boundaries 3. Check data ownership clarity 4. Validate dependency flow direction 5. Detect circular dependencies 6. Identify coupling violations 7. Analyze side effect containment

FPF Architecture Review Methodology

Conduct architecture reviews using the FPF (Functional, Practical, Foundation) methodology, evaluating codebases through three complementary perspectives.

Philosophy

Architecture reviews should be systematic and multi-dimensional. FPF provides three lenses:

• Functional: What the system does (capabilities, behaviors)
• Practical: How well it works (performance, usability)
• Foundation: What it's built on (principles, patterns)

Quick Start

# Full FPF review
/architecture-review --methodology fpf

# Specific perspective
/architecture-review --perspective functional
/architecture-review --perspective practical
/architecture-review --perspective foundation

The Three Perspectives

1. Functional Perspective

Question: What does this system do?

Evaluates:

• Feature completeness
• Capability coverage
• Behavior correctness
• Integration points

Outputs:

• Feature inventory
• Capability gaps
• Behavior anomalies

2. Practical Perspective

Question: How well does this system work?

Evaluates:

• Performance characteristics
• Usability patterns
• Operational concerns
• Scalability considerations

Outputs:

• Performance assessment
• Usability issues
• Operational recommendations

3. Foundation Perspective

Question: What is this system built on?

Evaluates:

• Architectural patterns
• Design principles
• Code quality
• Technical debt

Outputs:

• Pattern analysis
• Principle adherence
• Debt inventory

FPF Workflow

Phase 1: Discovery

1. Scan codebase structure - Identify components, modules, layers 2. Map dependencies - Internal and external relationships 3. Identify entry points - Public APIs, commands, interfaces

Phase 2: Functional Analysis

1. Inventory features - What capabilities exist 2. Trace behaviors - How features work end-to-end 3. Identify gaps - Missing or incomplete functionality

Phase 3: Practical Analysis

1. Assess performance - Latency, throughput, resource usage 2. Evaluate usability - Developer experience, API design 3. Check operations - Logging, monitoring, error handling

Phase 4: Foundation Analysis

1. Pattern recognition - What patterns are used 2. Principle check - SOLID, DRY, KISS adherence 3. Debt assessment - Technical debt inventory

Phase 5: Synthesis

1. Cross-reference findings - Connect issues across perspectives 2. Prioritize recommendations - Based on impact and effort 3. Generate report - Structured findings and actions

FPF Report Template

# FPF Architecture Review: [Project/Component]

**Date:** [DATE]
**Scope:** [what was reviewed]

## Executive Summary
[2-3 sentence overview of findings]

## Functional Perspective
### Features Inventory
| Feature | Status | Notes |
|---------|--------|-------|
| [Feature 1] | Complete | - |

### Capability Gaps
1. [Gap 1] - [Impact]

## Practical Perspective
### Performance Assessment
| Metric | Current | Target | Status |
|--------|---------|--------|--------|
| [Metric 1] | [value] | [target] | PASS/FAIL |

## Foundation Perspective
### Pattern Analysis
| Pattern | Usage | Assessment |
|---------|-------|------------|
| [Pattern 1] | [where used] | Appropriate/Problematic |

### Technical Debt
| Item | Severity | Effort | Priority |
|------|----------|--------|----------|
| [Debt 1] | High | Medium | P1 |

## Recommendations
### High Priority
1. **[Recommendation]** - Impact: [what improves] - Effort: [estimate]

Configuration

perspectives:
  functional:
    enabled: true
    depth: "full"  # full, summary
  practical:
    enabled: true
    depth: "full"
  foundation:
    enabled: true
    depth: "full"

Guardrails

1. Scope boundaries - Stay within configured scope 2. Evidence-based - Every finding needs supporting evidence 3. Actionable output - Recommendations must be actionable 4. Balanced perspectives - Don't over-index on one perspective

References

• FPF Framework - Original methodology
• quint-code - Heavy implementation (this skill is lighter)

Principle Checks Module

Systematic verification of architectural principles, anti-patterns, and quality attributes.

Law of Demeter (LoD)

The Principle

"Talk to friends, not to strangers."

An object should only call methods on: 1. Itself 2. Its parameters 3. Objects it creates 4. Its direct components

Train Wreck Detection

Anti-pattern:

# Bad: Chain of calls
customer.get_address().get_city().get_postal_code()

# Bad: Multiple dereferences
order.customer.billing_address.street

# Bad: Deep navigation
context.request.session.user.preferences.theme

Search patterns:

# Python
grep -rn '\.\w\+(\)\.\w\+(\)\.\w\+(' src/

# JavaScript/TypeScript
grep -rn '\.\w\+\.\w\+\.\w\+' src/ --include="*.js" --include="*.ts"

# Count violations
grep -r '\.\w\+\.\w\+\.\w\+' src/ | wc -l

Refactoring Strategies

Strategy 1: Tell, Don't Ask

# Before
if customer.get_address().get_country() == "US":
    apply_us_tax()

# After
if customer.is_in_country("US"):
    apply_us_tax()

Strategy 2: Move Logic to Owner

# Before
postal_code = customer.get_address().get_postal_code()
region = lookup_region(postal_code)

# After
region = customer.get_region()  # Address logic inside Customer

Strategy 3: Introduce Facade

# Before
config.get_database().get_connection_pool().get_connection()

# After
config.get_database_connection()  # Facade hides complexity

Anti-Slop Checks

What is "Slop"?

Code that appears professional but lacks substance:

• Generic naming
• Overengineering
• Cargo cult patterns
• Hallucinated dependencies
• Hollow abstractions

Detection Patterns

1. Overengineering Red Flags:

# Bad: Unnecessary abstraction layers
class UserFactoryFactory:
    def create_user_factory(self):
        return UserFactory()

# Bad: Premature generalization
class AbstractBaseEntityManagerInterface:
    pass

Search:

# Find "Abstract" overuse
grep -r "class Abstract" src/ | wc -l

# Find "Manager" bloat
grep -r "Manager\|Handler\|Processor" src/ --include="*.py"

# Find deep inheritance
grep -A 5 "class.*:" src/**/*.py | grep "    class"

2. Generic Naming:

# Bad: Non-descriptive names
def process_data(data):
    result = handle_item(data)
    return do_thing(result)

# Good: Specific names
def calculate_tax(order):
    taxable_amount = extract_taxable_items(order)
    return apply_tax_rate(taxable_amount)

Search:

# Find generic names
grep -rn "process\|handle\|manage\|do_\|data\|item\|thing" src/

3. Hidden Fragility:

# Bad: Silent failure
try:
    critical_operation()
except Exception:
    pass  # Swallowed error

# Bad: Implicit coupling
global_state = {}  # Hidden dependency

# Bad: Magic values
if status == 42:  # What does 42 mean?

Search:

# Find bare except
grep -rn "except:" src/

# Find global state
grep -rn "^[A-Z_]\+ = " src/

# Find magic numbers
grep -rn "if.*== [0-9]\+" src/

4. Hallucinated Dependencies:

# Bad: Assuming non-existent methods
user.auto_validate()  # Does this exist?
cache.smart_invalidate()  # What does "smart" mean?

# Bad: Imaginary patterns
@auto_retry  # Not in codebase
@cache_result  # Decorator doesn't exist

Verification:

# Check decorator existence
grep -r "^def auto_retry\|^class auto_retry" src/

# Verify method definitions
grep -r "def auto_validate" src/

Guardrails for AI Assistance

Evidence-Based Critiques

Required:

• File paths
• Line numbers
• Actual code snippets
• Measured metrics

Forbidden:

• "Looks like..."
• "Probably should..."
• "Best practice is..."
• "Generally we..."

Trade-Off Statements

Good:

Option A: PostgreSQL
+ Proven reliability, ACID compliance
+ Team expertise
- Higher hosting cost
- Vertical scaling limits

Option B: DynamoDB
+ Horizontal scalability
+ Lower latency
- Team learning curve
- Complex query limitations

Bad:

"PostgreSQL is better for this use case."
"DynamoDB would be more scalable."

Replace Hollow Phrases

Security Checks

Input Validation

1. Boundary Validation:

# Check: All external inputs validated
@validate_input
def create_user(email: str, age: int):
    if not is_valid_email(email):
        raise ValidationError("Invalid email")
    if not (0 < age < 150):
        raise ValidationError("Invalid age")

Search:

# Find unvalidated endpoints
grep -rn "@app.route\|@api" src/ -A 10 | grep -v "validate\|check\|verify"

2. SQL Injection Prevention:

# Bad
query = f"SELECT * FROM users WHERE id = {user_id}"

# Good
query = "SELECT * FROM users WHERE id = ?"
cursor.execute(query, (user_id,))

Search:

# Find string interpolation in SQL
grep -rn "f\".*SELECT\|\".*SELECT.*{" src/

3. XSS Prevention:

# Check for auto-escaping
# Framework default: Flask (manual), Django (auto)

Least Privilege

1. Minimum Permissions:

# Bad: Admin for everything
db_user = "admin"

# Good: Specific roles
db_user = "app_readonly"  # For queries
db_user = "app_writer"    # For mutations

2. Capability Checks:

# Find permission checks
grep -rn "check_permission\|require_role\|authorize" src/

Error Handling

1. No Sensitive Leaks:

# Bad
except Exception as e:
    return {"error": str(e)}  # May expose internals

# Good
except Exception as e:
    logger.error(f"Operation failed: {e}")
    return {"error": "Operation failed"}

2. Proper Logging:

# Check logging coverage
grep -rn "logger\.\(error\|warning\)" src/ | wc -l

Performance Checks

Performance Budgets

Define limits:

response_time:
  p50: 100ms
  p95: 500ms
  p99: 1000ms

database_queries:
  max_per_request: 10

memory:
  max_heap: 512MB

N+1 Query Detection

# Bad: N+1 queries
for user in users:
    user.get_orders()  # Query per user

# Good: Eager loading
users = User.query.options(joinedload('orders')).all()

Search:

# Find potential N+1
grep -rn "for.*in.*:" src/ -A 3 | grep "get_\|fetch_\|find_"

Caching Strategy

Check for:

• Cache key design
• TTL configuration
• Invalidation strategy
• Cache stampede prevention

# Find caching usage
grep -rn "@cache\|cache.get\|cache.set" src/

Index Coverage

# Check migrations for indexes
grep -r "CREATE INDEX\|add_index" migrations/

# Find missing indexes (slow queries)
# Review query logs, not static analysis

Integration with Architecture Review

Use this module during Step 4 (Principle Checks): 1. Run LoD detection searches 2. Check for anti-slop patterns 3. Verify AI assistance guardrails 4. Execute security checks 5. Validate performance budgets 6. Document violations with evidence 7. Recommend specific fixes with file/line references