Skip to content
Skills Library
DevOps & cloud · Analysis

scalability-advisor

/scalability-advisor

Assess system scalability: identify bottlenecks, recommend scaling strategies per container, and define capacity planning guidelines. Use when working on solution architecture, C4 diagrams, APIs, ADRs, or system design.

Repository
APES ↗
Licence
MIT
Last repository change
03.07.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
3
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 03.07.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Assess system scalability: identify bottlenecks, recommend scaling strategies per container, and define capacity planning guidelines. Use when working on solution architecture, C4 diagrams, APIs, ADRs, or system design.

Original author description

Assess system scalability: identify bottlenecks, recommend scaling strategies per container, and define capacity planning guidelines. Use when working on solution architecture, C4 diagrams, APIs, ADRs, or system design.

How it works

  1. Step 1: Extract scalability requirements
  2. Step 2: Analyze each container
  3. Step 3: Identify system bottlenecks
  4. Step 4: Recommend scaling strategies
  5. Step 5: Build capacity model
  6. Step 6: Define load testing plan
  7. Step 7: Validate
Original SKILL.md headings · 166 lines, 631 words
SKILL.md preview
---
name: scalability-advisor
description: >
  Assess system scalability: identify bottlenecks, recommend scaling strategies per container, and define capacity planning guidelines. Use when working on solution architecture, C4 diagrams, APIs, ADRs, or system design.
metadata:
  apes-version: "1.1"
  category: architecture
---

# Scalability Advisor

# Purpose

Assess system scalability: identify bottlenecks, recommend scaling strategies per container, and define capacity planning guidelines.

**Input:** Container diagram, NFRs (throughput, latency, users), data flow analysis (optional)  
**Output:** Scalability Assessment with bottleneck analysis, scaling recommendations, and capacity model
**Examples:** See [examples.md](examples.md) for worked input/output.

---

# Workflow

## Step 1: Extract scalability requirements

From NFRs, define:

| Metric | Target | Peak multiplier | Measurement |
|--------|--------|-----------------|-------------|

Metrics: concurrent users, requests/sec, data volume, growth rate.

## Step 2: Analyze each container

For each container:

| Container | Stateless? | Bottleneck risk | Current limit estimate |
|-----------|------------|-----------------|------------------------|

Identify: CPU-bound, memory-bound, I/O-bound, connection-pool limits.

## Step 3: Identify system bottlenecks

Rank bottlenecks:

| Rank | Component | Constraint | Impact at scale |
|------|-----------|------------|-----------------|

Common: database connections, single instance, sync external calls, large payloads.

## Step 4: Recommend scaling strategies

Per container:

| Strategy | When | Trade-off |
|----------|------|-----------|
| Horizontal scaling | Stateless services | Coordination complexity |
| Vertical scaling | Short-term, DB | Cost ceiling |
| Caching | Read-heavy | Staleness |
| Read replicas | Read/write split | Replication lag |
| Sharding | Large datasets | Query complexity |
| Async processing | Burst workloads | Latency |

## Step 5: Build capacity model

Simple capacity estimate:

```text
Peak RPS = users × actions_per_session / session_duration
Required instances = Peak RPS / RPS_per_instance
```

Document assumptions explicitly.

## Step 6: Define load testing plan

| Scenario | Load | Success criteria |
|----------|------|------------------|

## Step 7: Validate

Run Validation checklist.

---

# Decision Rules

| Condition | Action |
|-----------|--------|
| No NFR throughput targets | Request targets or use conservative assumptions; mark Confidence low |
| Stateful container scaled horizontally | Flag session/state management requirement |
| Database is bottleneck | Recommend read replicas, caching, or sharding with trade-offs |
| External API rate limits | Include in capacity model; recommend caching/batching |
| Scale requirements < 1000 users | Recommend simple vertical scaling; avoid premature optimization |

---

# Validation

- [ ] Scalability NFRs extracted or assumptions stated
- [ ] Every container analyzed for bottleneck risk
- [ ] Top 3 bottlenecks ranked with rationale
- [ ] Scaling strategy per high-risk container
- [ ] Capacity model with explicit assumptions
- [ ] Load testing scenarios defined
- [ ] Premature optimization flagged if scale is small
- [ ] Trade-offs documented for each strategy

---

# Anti-patterns

- **Scale everything** — horizontal scaling stateful DB without plan.
- **Cache as fix-all** — caching without invalidation strategy.
- **Ignore externals** — not modeling third-party rate limits.
- **No load testing** — recommendations without validation plan.
- **Infinite scale claims** — "handles any load" without evidence.

---

# Best Practices

- Start with measured baseline, not guesses.
- Scale the bottleneck first (Amdahl's law).
- Prefer stateless containers for horizontal scaling.
- Plan scale-down as well as scale-up (cost).
- Align with data-flow-analyzer for data layer scaling.

---

# Output Structure

```markdown
# Scalability Assessment: [System Name]

## Requirements
| Metric | Target | Peak | Assumptions |
|--------|--------|------|-------------|

## Container Analysis
| Container | Stateless | Risk | Limit |
|-----------|-----------|------|-------|

## Bottlenecks
| Rank | Component | Constraint | At-risk metric |
|------|-----------|------------|----------------|

## Recommendations
| Container | Strategy | Rationale | Trade-off |
|-----------|----------|-----------|-----------|

## Capacity Model
[Calculations with assumptions]

## Load Test Plan
| Scenario | Load | Pass criteria |
|----------|------|---------------|

## Risks
| Risk | Mitigation |
|------|------------|
```

---

# Next Skills

| Outcome | Recommended Skill |
|---------|-------------------|
| Review scalability in full context | `architecture/architecture-review` |
| Update architecture for scale | `architecture/solution-architecture` |
| Document scaling decision | `architecture/adr-generator` |
| AI system scaling | `ai/ai-solution-architect` |
Files in this package (3)
  • README.md 1 KB
  • examples.md 1 KB
  • skill.md 5 KB

Versions

The database has no other skills named scalability-advisor.

Database snapshot: 13.11.2026 · package version 12d8a2107ff1 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 1 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90system-scalability
    Audit and architect scaling boundaries and bottlenecks. Use when: scale up, scale out, horizontal scalability, vertical scaling, load balancing, analyze scalability.
  • 100analyzing-capacity-planning
    Execute this skill enables AI assistant to analyze capacity requirements and plan for future growth. it uses the capacity-planning-analyzer plugin to assess current utilization, forecast growth trends, and recommend scaling strategies. use this skill when the u... Use when…
  • 100analyzing-capacity-planning
    Execute this skill enables AI assistant to analyze capacity requirements and plan for future growth. it uses the capacity-planning-analyzer plugin to assess current utilization, forecast growth trends, and recommend scaling strategies. use this skill when the u... Use when…
  • 90scalability-planning
    Plan scalability from a load model and bottleneck math, designing for realistic growth without premature over-engineering. Use when designing for scale or after a load-driven incident.
  • 100system-benchmark
    Measure system throughput, stability, scalability, and resilience. Use when: Run system benchmark, Test scalability, Measure throughput, Check system stability, Run load test.
  • 100performance-scalability
    Identifies, diagnoses, and remediates performance bottlenecks, memory leaks, and architectural scaling limitations. Use this skill when asked to optimize slow queries, configure caching mechanisms, design asynchronous worker systems, or perform load profiling.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.