SDD Design Perf

Write the Performance Strategy section of a design document.

Scope

Cross-Cutting Roles

Note: Cross-cutting concerns are an extension to docs/sdd-guidelines.md for specialist coordination. See sdd-design for full mapping.

Perf is:

• Primary owner: (none in typical frontend projects)
• Reviewer for: Loading states (owned by uiux), Code display (owned by frontend)

Instructions

Step 1: Read Context

1. Design skeleton (from sdd-design)
2. All REQs in your section's @derives
3. Foundation anchors (especially CONSTRAINT-* for size limits)
4. Frontend section (for library candidates)

Step 2: Identify Performance Requirements

Extract from REQs:

Look for:

• Explicit size/speed constraints
• "Fast", "instant", "responsive" language
• Large data sets, many items
• Mobile/low-power device mentions

Step 3: Define Bundle Budget

Based on REQ constraints:

If no explicit constraint: Use sensible defaults based on project type.

Document with @derives linking to REQ or CONSTRAINT.

Step 4: Select Libraries

Review frontend's candidates against budget:

Selection criteria:

• Fits within budget
• Tree-shakable preferred
• No unnecessary features

Step 5: Design Code Splitting

Based on user flow from REQs:

Principles:

• Critical path in main bundle
• Features on-demand
• Route-based splitting when applicable

Step 6: Design Lazy Loading

For heavy resources:

Strategies:

• Route-based: React.lazy()
• Scroll-based: Intersection Observer
• User-action: On click/expand

Step 7: Identify Render Optimizations

For REQs with "real-time" or "immediate" language:

Common techniques:

• React.memo for pure components
• useMemo / useCallback for expensive computations
• Virtualization for long lists

Step 8: Define Caching Strategy

Step 9: Define Metrics

Step 10: Write Section

## Performance Strategy

@derives: {REQ-IDs}

### Bundle Budget
### Library Selection
### Code Splitting
### Lazy Loading
### Render Optimization
### Caching Strategy
### Performance Metrics

**Status:** draft

Step 11: Add Decisions

For library selections and trade-offs:

| ID | Decision | Rationale | Owner |
|----|----------|-----------|-------|
| DEC-00x | {what} | {why — connect to budget/REQ} | perf |

Step 12: Handoff

Per docs/sdd-guidelines.md §4.3 and §10.6.

1. Update Section Status

**Status:** verified

2. Update State File

# .sdd/state.yaml
documents:
  design:
    sections:
      perf: verified

3. Create Handoff Record

# .sdd/handoffs/{timestamp}-perf.yaml
from: sdd-design-perf
to: sdd-design
timestamp: {ISO-8601}

completed:
  - design.perf: verified

in_progress: []

blocked: []

gaps: []

next_steps:
  - sdd-design-frontend: Use selected libraries
  - sdd-design-uiux: Review — loading states align with lazy loading

4. Cross-Cutting Status

@derives Judgment

A performance decision @derives from a REQ when:

NOT @derives:

• Generic optimizations not tied to REQ
• Premature optimization without constraint

Verification

• Bundle budget defined and justified
• Library selections within budget
• Code splitting covers all lazy-loadable features
• Lazy loading for heavy resources
• Render optimizations for "real-time" REQs
• Decisions logged with rationale
• Cross-cutting reviews completed

References

Examples