System Design Interrogation

---
name: system-design-interrogation
description: Use when planning system architecture to ensure nothing is missed. Provides structured questions covering scalability, security, data, and operational dimensions before implementation.
tags: [architecture, design, review, questions]
context: fork
agent: system-design-reviewer
version: 1.0.0
author: OrchestKit
user-invocable: false
---

# System Design Interrogation

## The Problem

Rushing to implementation without systematic design thinking leads to:
- Scalability issues discovered too late
- Security holes from missing tenant isolation
- Data model mismatches
- Frontend/backend contract conflicts
- Poor user experience

## The Solution: Question Before Implementing

```
┌────────────────────────────────────────────────────────────────────────────┐
│                    SYSTEM DESIGN INTERROGATION                             │
├────────────────────────────────────────────────────────────────────────────┤
│                                                                            │
│                        ┌─────────────┐                                     │
│                        │   FEATURE   │                                     │
│                        │   REQUEST   │                                     │
│                        └──────┬──────┘                                     │
│                               │                                            │
│    ┌──────────────────────────┼──────────────────────────┐                │
│    │                          │                          │                │
│    ▼                          ▼                          ▼                │
│  ┌────────┐             ┌────────┐              ┌────────┐               │
│  │ SCALE  │             │  DATA  │              │SECURITY│               │
│  └───┬────┘             └───┬────┘              └───┬────┘               │
│      │                      │                       │                     │
│  • Users?               • Where?               • Who access?              │
│  • Volume?              • Pattern?             • Isolation?               │
│  • Growth?              • Search?              • Attacks?                 │
│      │                      │                       │                     │
│      └──────────────────────┼───────────────────────┘                     │
│                             │                                             │
│    ┌────────────────────────┼────────────────────────┐                   │
│    │                        │                        │                   │
│    ▼                        ▼                        ▼                   │
│  ┌────────┐           ┌──────────┐            ┌────────┐                │
│  │   UX   │           │COHERENCE │            │ TRADE- │                │
│  └───┬────┘           └────┬─────┘            │  OFFS  │                │
│      │                     │                  └───┬────┘                │
│  • Latency?           • Contracts?           • Speed?                    │
│  • Feedback?          • Types?               • Quality?                  │
│  • Errors?            • API?                 • Cost?                     │
│      │                     │                      │                      │
│      └─────────────────────┴──────────────────────┘                      │
│                             │                                             │
│                             ▼                                             │
│                     ┌───────────────┐                                    │
│                     │ IMPLEMENTATION│                                    │
│                     │    READY      │                                    │
│                     └───────────────┘                                    │
│                                                                            │
└────────────────────────────────────────────────────────────────────────────┘
```

## The Five Dimensions

### 1. Scale

**Key Questions:**
- How many users/tenants will use this?
- What's the expected data volume (now and in 1 year)?
- What's the request rate? Read-heavy or write-heavy?
- Does complexity grow linearly or exponentially with data?
- What happens at 10x current load? 100x?

**OrchestKit Example:**
```
Feature: "Add document tagging"
- Users: 1000 active users
- Documents per user: ~50 average
- Tags per document: 3-5
- Total tags: 50,000 → 500,000
- Access: Read-heavy (10:1 read:write)
- Search: Need tag autocomplete (prefix search)
```

### 2. Data

**Key Questions:**
- Where does this data naturally belong?
- What's the primary access pattern?
- Is it master data or transactional?
- What's the retention policy?
- Does it need to be searchable? How?

**OrchestKit Example:**
```
Feature: "Add document tagging"
- Data: Tags belong WITH documents (denormalized) or separate table?
- Pattern: Get tags for document (by doc_id), get documents by tag
- Storage: PostgreSQL (relational) or add to document JSON?
- Search: Full-text for tag names, filter by tag for documents
- Decision: Separate `tags` table with many-to-many join
```

### 3. Security

**Key Questions:**
- Who can access this data/feature?
- How is tenant isolation enforced?
- What happens if authorization fails?
- What attack vectors does this introduce?
- Is there PII involved?

**OrchestKit Example:**
```
Feature: "Add document tagging"
- Access: User can only see/manage their own tags
- Isolation: All tag queries MUST include tenant_id filter
- AuthZ: Check user owns document before tagging
- Attacks: Tag injection? Limit tag length, sanitize input
- PII: Tags might contain PII → treat as sensitive
```

### 4. UX Impact

**Key Questions:**
- What's the expected latency for this operation?
- What feedback does the user get during the operation?
- What happens on failure? Can they retry?
- Is there optimistic UI possible?
- How does this affect the overall workflow?

**OrchestKit Example:**
```
Feature: "Add document tagging"
- Latency: < 100ms for add/remove tag
- Feedback: Optimistic update, show tag immediately
- Failure: Rollback tag, show error toast
- Optimistic: Yes - add tag to UI before server confirms
- Workflow: Tags should be inline editable, no modal
```

### 5. Coherence

**Key Questions:**
- Which layers does this touch?
- What contracts/interfaces change?
- Are types consistent frontend ↔ backend?
- Does this break existing clients?
- How does this affect the API?

**OrchestKit Example:**
```
Feature: "Add document tagging"
- Layers: DB → Backend API → Frontend UI → State
- Contracts: Document type needs `tags: Tag[]` field
- Types: Tag = { id: UUID, name: string, color?: string }
- Breaking: No - additive change to Document response
- API: POST /documents/{id}/tags, DELETE /documents/{id}/tags/{tag_id}
```

## The Process

### Before Writing Any Code

1. **State the Feature** - One sentence description
2. **Run Through 5 Dimensions** - Answer key questions for each
3. **Identify Trade-offs** - Speed vs quality, complexity vs flexibility
4. **Document Decisions** - Record answers in design doc or issue
5. **Review with Team** - Get alignment before implementing

### Quick Assessment Template

```markdown
## Feature: [Name]

### Scale
- Users:
- Data volume:
- Access pattern:
- Growth projection:

### Data
- Storage location:
- Schema changes:
- Search requirements:
- Retention:

### Security
- Authorization:
- Tenant isolation:
- Attack surface:
- PII handling:

### UX
- Target latency:
- Feedback mechanism:
- Error handling:
- Optimistic updates:

### Coherence
- Affected layers:
- Type changes:
- API changes:
- Breaking changes:

### Decision
[Final approach with rationale]
```

## Integration with OrchestKit Workflow

### In Brainstorming Phase

Before implementation, run system design interrogation:

```
/brainstorm → System Design Questions → Implementation Plan
```

### In Code Review

Reviewer should verify:
- Scale considerations documented
- Security layer covered
- Types consistent across stack
- UX states handled

### In Testing

Tests should cover:
- Scale: Load tests for expected volume
- Security: Tenant isolation tests
- Coherence: Integration tests across layers
- UX: Error state tests

## Anti-Patterns

```
❌ "I'll add an index later if it's slow"
   → Ask: What's the expected query pattern NOW?

❌ "We can add tenant filtering in a future PR"
   → Ask: How is isolation enforced from DAY ONE?

❌ "The frontend can handle any response shape"
   → Ask: What's the TypeScript type for this?

❌ "Users won't do that"
   → Ask: What's the attack vector? What if they DO?

❌ "It's just a small feature"
   → Ask: How does this grow with 100x users?
```

## Quick Reference Card

| Dimension | Key Question | Red Flag |
|-----------|--------------|----------|
| Scale | How many? | "All users" |
| Data | Where stored? | "I'll figure it out" |
| Security | Who can access? | "Everyone" |
| UX | What's the latency? | "It'll be fast" |
| Coherence | What types change? | "No changes needed" |

---

**Version:** 1.0.0 (December 2025)

## Related Skills

- `brainstorming` - Transform rough ideas into designs before applying system design interrogation
- `architecture-decision-record` - Document key decisions discovered during interrogation
- `explore` - Deep codebase exploration to understand existing architecture before planning
- `verify` - Comprehensive feature verification after implementation

## Key Decisions

| Decision | Choice | Rationale |
|----------|--------|-----------|
| Dimensions count | Five (Scale, Data, Security, UX, Coherence) | Covers all critical architectural concerns without overlap |
| Process timing | Before any code | Prevents costly rework from missed requirements |
| Question format | Structured templates | Ensures consistent coverage, prevents omissions |
| Documentation | Markdown template | Portable, version-controlled, reviewable |
| Integration | Pairs with brainstorming | Brainstorming explores options, interrogation validates choice |

## Capability Details

### scale-assessment
**Keywords:** scale, load, traffic, users, concurrent, throughput
**Solves:**
- How many users will this feature serve?
- What's the expected request rate?
- How does this scale with data growth?

### data-architecture
**Keywords:** data, storage, database, schema, migration, structure
**Solves:**
- Where should this data live?
- What's the access pattern?
- How does this affect existing schemas?

### security-considerations
**Keywords:** security, auth, permission, tenant, isolation, attack
**Solves:**
- What are the security implications?
- How is tenant isolation maintained?
- What attack vectors exist?

### coherence-validation
**Keywords:** coherence, consistency, contract, interface, integration
**Solves:**
- How does this fit the existing architecture?
- What contracts need updating?
- Are frontend/backend aligned?

### ux-impact
**Keywords:** ux, user experience, latency, feedback, error
**Solves:**
- What's the user experience impact?
- How long will users wait?
- What feedback do they get?