Optimization Phase

This skill orchestrates the /optimize phase, which runs after /implement and before /preview in the deployment workflow.

Inputs: Implemented code (from /implement), spec.md (success criteria) Outputs: optimization-report.md, code-review-report.md Expected duration: 1-2 hours

1. Performance Benchmarking - API p50 <200ms, p95 <500ms, page load <2s
2. Accessibility Audit - WCAG 2.1 AA compliance (if UI feature)
3. Security Review - npm audit, dependency scanning, OWASP top 10
4. Code Quality Review - DRY violations <3, test coverage ≥80%
5. Generate Reports - optimization-report.md + code-review-report.md

Key principle: All blocking quality gates must pass before deployment.

Before beginning optimization:

• Implementation phase completed (all tasks done or blocked)
• All tests passing (CI pipeline green)
• Code committed to feature branch (git status clean)
• spec.md contains performance targets and success criteria

If prerequisites not met, return to /implement phase.

Validate API response times and page load performance against spec.md targets.

API Performance Testing:

# Measure API endpoint response times (10 requests)
for i in {1..10}; do
  curl -w "%{time_total}\n" -o /dev/null -s "http://localhost:3000/api/endpoint"
done | sort -n

# Calculate p50 (median): 5th value
# Calculate p95 (95th percentile): 10th value

Page Load Testing:

# Run Lighthouse CI for page load metrics
npm install -g @lhci/cli
lhci autorun --url=http://localhost:3000

# Check metrics:
# - First Contentful Paint (FCP): <1.8s
# - Largest Contentful Paint (LCP): <2.5s
# - Time to Interactive (TTI): <3.8s

Targets from spec.md:

• API p50 (median): <200ms
• API p95 (95th percentile): <500ms
• Page load (initial): <2 seconds
• Time to Interactive (TTI): <3 seconds

Blocking: If performance targets not met, optimization required before deployment.

See resources/performance-benchmarking.md for detailed testing procedures.

Validate WCAG 2.1 AA compliance for all UI changes.

Lighthouse CI Audit:

# Run Lighthouse accessibility audit
lhci autorun --collect.settings.onlyCategories=accessibility

# Target score: ≥95/100

axe-core Validation:

# Install axe-core DevTools extension
# Or use axe CLI:
npm install -g @axe-core/cli
axe http://localhost:3000 --tags wcag2aa

WCAG 2.1 AA Requirements:

• Color contrast ≥4.5:1 (text), ≥3:1 (UI components)
• Keyboard navigation (all interactive elements accessible)
• Screen reader compatibility (ARIA labels, semantic HTML)
• Focus indicators visible (outline, border, background change)

Blocking (if UI feature): All WCAG 2.1 AA violations must be fixed.

Skip if: No UI changes in this feature (backend/API only).

See resources/accessibility-audit.md for comprehensive checklist.

Scan for vulnerabilities in dependencies and code.

Dependency Vulnerability Scan:

# npm audit for Node.js projects
npm audit --audit-level=moderate

# Check for critical and high severity vulnerabilities
# Fix: npm audit fix (or manual upgrade)

OWASP Top 10 Checks:

• SQL Injection: Parameterized queries, no string concatenation
• XSS: Input sanitization, output encoding
• CSRF: CSRF tokens on state-changing endpoints
• Authentication: Secure password hashing (bcrypt), JWT validation
• Sensitive Data Exposure: No secrets in code/logs, HTTPS enforced

Secret Scanning:

# Check for accidentally committed secrets
git secrets --scan

# Or use gitleaks:
gitleaks detect --source . --verbose

Blocking: Critical and high severity vulnerabilities must be fixed.

See resources/security-review.md for OWASP top 10 checklist.

Validate code follows DRY/KISS principles and test coverage standards.

Test Coverage Check:

# Run coverage report
npm run test:coverage

# Target: ≥80% coverage (unit + integration)

DRY Violations Check:

# Manual review for code duplication
# Or use jsinspect (JavaScript):
npm install -g jsinspect
jsinspect src/

# Target: <3 instances of code duplication

KISS Principle Validation:

• Functions ≤50 lines (complex functions split)
• Cyclomatic complexity <10 (no deeply nested logic)
• No premature optimization (YAGNI principle)

Code Review Checklist:

• No magic numbers (constants extracted)
• Descriptive variable/function names
• Error handling present (try/catch, error boundaries)
• No commented-out code (dead code removed)
• Consistent code style (linter passing)

Blocking if: Test coverage <80% OR >5 DRY violations OR critical complexity issues.

See resources/code-quality-review.md for complete checklist.

Create optimization-report.md and code-review-report.md.

optimization-report.md format:

# Optimization Report: [Feature Name]

**Date**: 2025-11-19
**Feature**: specs/NNN-slug

## Performance Results

### API Performance

- GET /api/users: p50=145ms ✅, p95=320ms ✅
- POST /api/orders: p50=230ms ❌, p95=580ms ❌ (exceeds p95 target)

### Page Load Performance

- Homepage: LCP=1.9s ✅, TTI=2.8s ✅
- Dashboard: LCP=3.2s ❌ (exceeds target)

## Accessibility Audit (WCAG 2.1 AA)

- Lighthouse score: 98/100 ✅
- axe-core violations: 0 ✅

## Security Review

- npm audit: 0 critical, 0 high ✅
- OWASP top 10: All checks passed ✅
- Secret scanning: No secrets detected ✅

## Code Quality

- Test coverage: 85% ✅
- DRY violations: 2 ✅
- Complexity: All functions <10 ✅

## Blocking Issues

- POST /api/orders p95 exceeds target (580ms vs 500ms)
- Dashboard LCP exceeds target (3.2s vs 2.5s)

## Recommendations

- Add caching to /api/orders endpoint (reduce p95 to <500ms)
- Lazy load dashboard widgets (reduce LCP to <2.5s)

code-review-report.md format:

# Code Review Report: [Feature Name]

**Date**: 2025-11-19
**Reviewer**: optimization-phase skill

## Summary

- Files reviewed: 15
- Issues found: 7 (3 critical, 4 minor)

## Critical Issues

1. [src/api/orders.ts:45] Missing input validation on order.total
2. [src/components/Dashboard.tsx:89] Potential memory leak (event listener not removed)
3. [src/services/AuthService.ts:23] Password logged in plaintext (security risk)

## Minor Issues

1. [src/utils/formatDate.ts:12] Magic number 1000 should be constant
2. [src/components/UserCard.tsx:34] Unused import (React.Fragment)

## Recommendations

- Fix all critical issues before deployment
- Consider refactoring Dashboard.tsx (180 lines, split into smaller components)

Update state.yaml: optimization.status = completed

See resources/report-generation.md for report templates.

• All blocking quality gates passed (performance, accessibility, security, code quality)
• optimization-report.md generated with all sections completed
• code-review-report.md generated with issues documented
• Critical issues fixed (blocking deployment)
• Minor issues documented (can defer or fix)
• state.yaml updated (optimization.status = completed)

If blocking issues found, return to /implement to fix, then re-run /optimize.

Environment checks:

• Environment variables configured (.env.production exists)
• Production build succeeds (npm run build passes)
• No TypeScript/lint errors (npm run type-check passes)
• All tests passing (npm test green)

If any check fails, fix before proceeding to quality gates.

API performance:

• p50 (median) <200ms
• p95 (95th percentile) <500ms

Page load performance:

• Initial load <2 seconds
• Time to Interactive <3 seconds

If targets not met, profile and optimize before deployment.

WCAG 2.1 AA compliance:

• Lighthouse accessibility score ≥95/100
• axe-core violations: 0 (WCAG 2.1 AA)
• Keyboard navigation functional
• Screen reader compatible

Skip if: Backend/API feature with no UI changes.

Vulnerability scanning:

• npm audit: 0 critical, 0 high severity
• OWASP top 10 checks passed
• No secrets in code/logs (gitleaks clean)

If critical/high vulnerabilities found, fix or accept risk (document).

Quality standards:

• Test coverage ≥80% (unit + integration)
• DRY violations <3 instances
• Cyclomatic complexity <10 (all functions)

Blocking if: Coverage <80% OR >5 DRY violations OR complexity >15.

Why: Even small UI changes can introduce accessibility violations (color contrast, keyboard nav, screen readers). WCAG compliance is non-negotiable for production.

Example (bad):

"This is just a button color change, no need for accessibility audit"
[Ships button with insufficient color contrast, fails WCAG 2.1 AA]

Example (good):

"Button color changed from blue to green"
→ Run Lighthouse accessibility audit
→ Check color contrast ratio (4.5:1 minimum)
→ Verify keyboard focus indicator visible
→ Deploy with confidence

Why: Performance regressions accumulate over time. Without benchmarking, small slowdowns compound into major UX issues.

Example (bad):

"Dashboard feels fast to me, ship it"
[Reality: LCP=5s, users complain about slow load]

Example (good):

Run Lighthouse: LCP=3.2s (target: 2.5s)
Identify bottleneck: Large uncompressed image
Fix: Lazy load + WebP format
Re-test: LCP=1.8s ✅
Deploy

Why: Security vulnerabilities in production are exploited quickly. Deferring fixes creates risk.

Example (bad):

npm audit: 2 critical, 5 high vulnerabilities
"We'll fix these in the next sprint"
[Ships vulnerable dependencies, gets hacked]

Example (good):

npm audit: 2 critical, 5 high vulnerabilities
BLOCK deployment
Run: npm audit fix
Or: Manually upgrade vulnerable dependencies
Re-test: 0 critical, 0 high
Deploy safely

Why: Low coverage = high risk of bugs in production. "Later" rarely happens.

Example (bad):

Test coverage: 45%
"Core functionality is tested, ship it"
[Untested edge cases cause production bugs]

Example (good):

Test coverage: 45% ❌
BLOCK deployment
Write missing tests (focus on critical paths)
Re-run: 82% ✅
Deploy with confidence

Why: Manual reviews miss issues that automated tools catch instantly.

Example (bad):

"I reviewed the code, looks good"
[Ships with 12 accessibility violations, 8 security issues]

Example (good):

Lighthouse: 15 accessibility violations
npm audit: 8 vulnerabilities
Coverage: 67%
Fix all blocking issues
Re-run all tools
Deploy when green

# .github/workflows/optimize.yml
- run: npm run test:coverage
  # Fail if <80%
- run: npm audit --audit-level=high
  # Fail if critical/high vulnerabilities
- run: lhci autorun
  # Fail if performance/accessibility targets not met

Result: Quality gates enforced automatically, no human error

## Success Criteria

**Performance**:

- API p50 <200ms, p95 <500ms
- Page load <2s, TTI <3s
- Lighthouse performance score ≥90/100

Result: Clear, measurable targets validated during /optimize

• During /implement (run axe-core locally)
• During /optimize (full WCAG 2.1 AA audit)
• In CI pipeline (automated Lighthouse checks)

Result: Accessibility violations caught early, cheaper to fix

• Never defer critical vulnerabilities
• Fix or accept risk (with documented justification)
• Re-scan after fixes to verify clean

Result: No vulnerable code in production

• Document all metrics (performance, security, accessibility, quality)
• List blocking issues clearly
• Provide actionable recommendations
• Track improvements over time

Result: Audit trail for deployment decisions, learning from past optimizations

• All blocking quality gates passed (pre-flight, performance, security, code quality)
• Accessibility gate passed (if UI feature)
• optimization-report.md generated with all results
• code-review-report.md generated with issues documented
• Critical issues fixed (blocking deployment)
• Minor issues documented (can defer)
• state.yaml updated (optimization.status = completed)
• Ready to proceed to local preview or staging (use installed /preview only if your adapter ships it)

If blocking issues remain, return to /implement to fix, then re-run /optimize.

• All quality gates automated (CI pipeline enforcement)
• Performance targets met (benchmarked against spec.md)
• Accessibility validated (WCAG 2.1 AA compliance)
• Security clean (0 critical/high vulnerabilities)
• High test coverage (≥80%)
• Comprehensive reports (optimization-report.md + code-review-report.md)

Bad optimization:

• Manual-only review (no automated tools)
• Performance not measured (subjective "feels fast")
• Accessibility skipped (ships with violations)
• Security vulnerabilities deferred (critical issues in production)
• Low test coverage (<80%, high bug risk)
• No documentation (no optimization-report.md)

Issue: Accessibility violations detected (WCAG 2.1 AA) Solution: Fix color contrast, add ARIA labels, ensure keyboard navigation, test with screen reader

Issue: Critical security vulnerabilities found Solution: Run npm audit fix, manually upgrade dependencies, re-scan until clean

Issue: Test coverage below 80% Solution: Write missing tests (focus on critical paths), use test-architect for complex features

Issue: DRY violations >3 instances Solution: Extract duplicated code to shared utilities, refactor into reusable functions

Issue: Lighthouse performance score <90 Solution: Optimize images (WebP, lazy loading), minify JS/CSS, enable compression, use CDN

• Performance Benchmarking (resources/performance-benchmarking.md) - API p50/p95, page load targets
• Accessibility Audit (resources/accessibility-audit.md) - WCAG 2.1 AA compliance, Lighthouse CI
• Security Review (resources/security-review.md) - npm audit, OWASP top 10, secret scanning

Code quality (blocking if critical):

• Code Quality Review (resources/code-quality-review.md) - DRY, KISS, test coverage
• Code Review Checklist (resources/code-review-checklist.md) - Pre-commit validation

Documentation:

• Report Generation (resources/report-generation.md) - optimization-report.md templates
• Common Mistakes (resources/common-mistakes.md) - Anti-patterns to avoid
• Examples (examples.md) - Good vs bad optimization examples

Next phase: After optimization completes → /preview (manual UI/UX testing)