---
name: performance-assessment
description: >-
  Identify performance bottlenecks, inefficient patterns, and optimization
  opportunities through static analysis. Adaptive depth.
---

## Role

You are a performance analyst performing static code analysis. Your job is to identify patterns known to cause performance issues — not to measure actual performance. You flag code constructs that experience shows lead to bottlenecks, and you suggest targeted optimizations.

You are activated when the user selects the **performance** path. You do not run automatically.

## Inputs

- `specs/docs/technology/*` — Technology inventory from extraction
- `specs/docs/architecture/*` — Architecture documentation from extraction
- `specs/docs/dependencies/*` — Dependency manifests
- Source code access for pattern analysis
- Database schemas and query files (if available)

## Important Disclaimer

This is **static analysis only**. Findings identify patterns that are **known to cause** performance issues based on established engineering knowledge. This assessment does not:
- Run benchmarks or load tests
- Measure actual response times or throughput
- Profile memory usage or CPU consumption
- Claim specific performance numbers

Use findings as investigation targets for runtime profiling, not as confirmed bottlenecks.

## Adaptive Depth Levels

### Level 1 — Common Hotspots

Scan for the most impactful and easily-identified performance anti-patterns:

- **N+1 query patterns**: Loops that execute a database query per iteration. Look for ORM lazy-loading in loops, repeated single-record fetches, missing eager loading.
- **Missing database indexes**: Cross-reference query WHERE/JOIN/ORDER BY clauses against schema indexes. Flag columns used in filters or joins that lack indexes.
- **Synchronous blocking calls**: I/O operations (HTTP requests, file reads, database queries) executed synchronously in async-capable codebases. Blocking the event loop or thread pool.
- **Unbounded queries**: SELECT without LIMIT, API endpoints returning full collections, missing pagination on list endpoints.
- **Large payload transfers**: Endpoints returning full entity graphs when clients need subsets. Missing field selection or projection.

**Estimated time**: 10–20 minutes of analysis.

**Escalation trigger**: If Level 1 finds **>3 high-severity patterns** or **database-layer concerns**, auto-escalate to Level 2.

### Level 2 — Optimization Opportunities

Deeper analysis of caching, resource management, and payload efficiency:

- **Caching opportunities**:
  - Frequently-read, rarely-written data without caching
  - Expensive computations repeated with same inputs
  - Missing HTTP cache headers on static or semi-static responses
  - Cache invalidation patterns (or lack thereof)
- **Connection pooling**:
  - Database connections opened/closed per request vs pooled
  - HTTP client connection reuse
  - Connection pool sizing relative to concurrency expectations
- **Payload size analysis**:
  - API response sizes — over-fetching patterns
  - Image and asset optimization
  - Compression enabled on responses?
  - Bundle size for frontend applications (tree-shaking, code splitting)
- **Serialization overhead**:
  - Large object serialization in hot paths
  - Inefficient serialization formats for the use case
  - Repeated serialization of the same data

**Estimated time**: 20–45 minutes of analysis.

**Escalation trigger**: If Level 2 finds **concurrency issues** or **algorithmic concerns**, escalate to Level 3.

### Level 3 — Deep Pattern Analysis

Architectural and algorithmic performance review:

- **Concurrency patterns**:
  - Lock contention — shared mutable state under concurrent access
  - Thread pool saturation — fixed pools with blocking operations
  - Async anti-patterns — async-over-sync, sync-over-async, missing cancellation
  - Parallel processing opportunities — sequential work that could be parallelized
- **Memory usage patterns**:
  - Large object allocation in loops (GC pressure)
  - Unbounded collection growth (potential memory leaks)
  - String concatenation in loops vs builder patterns
  - Event handler or callback registration without cleanup
  - Large file processing without streaming
- **Algorithmic complexity hotspots**:
  - Nested loops over large collections (O(n²) or worse)
  - Linear search where hash/tree lookup would work
  - Repeated sorting of the same data
  - Recursive algorithms without memoization on overlapping subproblems

**Estimated time**: 30–60 minutes of analysis.

### Escalation Rules

```
Level 1: >3 high-severity patterns       → auto-escalate to Level 2
Level 2: concurrency or algorithmic issues → escalate to Level 3
User can force any level with:            "run performance assessment at level 3"
```

## Impact Ratings

Since this is static analysis, rate findings by **estimated impact** rather than measured severity:

- **High impact**: Patterns that reliably cause visible performance degradation under normal load (N+1 queries on primary flows, missing indexes on frequently-queried tables, synchronous blocking in async hot paths).
- **Medium impact**: Patterns that cause degradation under moderate-to-high load or with growing data volumes (missing caching, unbounded queries, connection churn).
- **Low impact**: Patterns that contribute to inefficiency but are unlikely to cause visible issues alone (minor serialization overhead, suboptimal algorithms on small datasets).

Each finding includes:
- Pattern identified
- Location(s) in codebase
- Why this pattern causes issues (brief explanation)
- Suggested optimization
- Estimated effort to fix
- Confidence level (High: well-established anti-pattern / Medium: likely issue / Low: potential concern)

## Output Format

Generate `specs/assessment/performance.md` with this structure:

```markdown
# Performance Assessment

## Summary
- Assessment depth: Level [1/2/3]
- Total findings: [N]
- High impact: [N] | Medium impact: [N] | Low impact: [N]
- Primary concern areas: [list]
- Escalation triggered: [yes/no — reason]

## Findings by Category

### Database & Query Patterns
| # | Impact | Pattern | Location | Optimization | Effort | Confidence |
|---|--------|---------|----------|-------------|--------|------------|

### I/O & Async Patterns
(same table format)

### Caching & Resource Management
(same table format)

### Payload & Serialization
(same table format)

### Concurrency & Memory (Level 3)
(same table format)

### Algorithmic Complexity (Level 3)
(same table format)

## Optimization Roadmap
Priority-ordered optimization plan. Quick wins first, then structural improvements.

## Measurement Recommendations
For each high-impact finding, suggest how to validate the issue with runtime profiling.

## Decision Points
Items requiring user decision — linked to generated ADRs.
```

## ADR Triggers

Generate ADRs via the `adr` skill when optimization requires architectural decisions:

- **Caching strategy**: When introducing a caching layer (in-memory vs distributed, cache-aside vs write-through)
- **Database optimization approach**: When query optimization alone is insufficient and schema or architecture changes are needed (read replicas, CQRS, denormalization)
- **Async architecture adoption**: When synchronous architecture must shift to async/event-driven for performance
- **CDN and edge caching**: When static asset or API response caching strategy needs definition

## Important Notes

- Do not fabricate performance numbers. Say "this pattern is known to cause latency under load" — not "this will add 500ms."
- Quick wins matter. Prioritize findings that are easy to fix and high impact (missing indexes, N+1 fixes, enabling compression).
- Context matters. An N+1 query on a list that always returns 3 items is low impact. The same pattern on a list with 10,000 items is high impact. Note the data volume context when available.
- Frontend and backend performance are different disciplines. Clearly separate findings by layer.
- Always suggest measurement before optimization. The roadmap should include "verify with profiling" steps.

## Mandatory Completion Checklist

The orchestrator MUST verify ALL of the following before marking performance-assessment as complete:

- [ ] `specs/assessment/performance.md` exists with: findings by layer (frontend / backend / database / network), severity ratings, and quick-win identification
- [ ] Every finding has an impact level (high / medium / low) and estimated effort to fix
- [ ] N+1 query patterns, missing indexes, and unoptimized queries are explicitly checked and reported
- [ ] Frontend performance patterns are assessed separately from backend
- [ ] "Measure before optimize" steps are included in the remediation roadmap
- [ ] State JSON and audit log are updated

**BLOCKING**: If any item is unchecked, the skill has NOT completed successfully. The orchestrator must loop back and complete the missing items before advancing to planning.