Imported from gabrielmoreira/agent-skills-mirror (mirrors/repos/mohitagw15856@pm-claude-skills/exports/openclaw/capacity-planning/SKILL.md). Install upstream with npx skills add gabrielmoreira/agent-skills-mirror --skill capacity-planning. Copyright stays with the author.

Capacity Planning Skill

Produce a complete capacity planning document for a service. Capacity planning is not about predicting the future exactly — it is about understanding current headroom, modelling growth, and ensuring the team takes infrastructure action before a constraint becomes an incident.

A good capacity plan answers: what is running out first, how long before it runs out, what does it cost to fix it, and who decides when to act.

Required Inputs

Ask for these if not already provided:

• Service name and description — what the service does and who depends on it
• Current traffic and usage metrics — requests per second (or per day), active users, data volume — whatever units are most natural for this service
• Current resource utilisation — CPU %, memory %, disk usage, connection pool utilisation, DB query throughput
• Growth rate or projections — historical growth rate, or known upcoming events (product launch, sales cycle, seasonal peak)
• Tech stack and infrastructure — cloud provider, compute type (VMs, containers, serverless), database, caching layer, CDN
• Cost constraints — current infrastructure spend, acceptable cost ceiling, or target cost per unit of traffic

Output Format

Capacity Plan: [Service Name]

Service: [Name] | Team: [Team name] Author: [Name] | Last updated: [Date] Planning horizon: [12 months — [Month Year] to [Month Year]] Review cadence: [Quarterly]

1. Executive Summary

[3–5 sentences covering: current state, the most critical capacity constraint, the timeline before it becomes a risk, the recommended action, and the cost implication. Written for an engineering manager or VP who needs the key facts without reading the full document.]

Critical finding: [e.g. "The database connection pool will reach 90% utilisation within 6 weeks at current growth. Without action, this will cause request queueing and latency spikes under normal traffic."]

Recommended immediate action: [e.g. "Increase connection pool limit and add a read replica within the next 2 weeks."]

Estimated cost impact: [e.g. "Recommended changes add ~$[X]/month to infrastructure spend."]

2. Current Baseline

All metrics are 30-day averages unless noted. Date captured: [Date]

Traffic

Compute

Database

Cache

Storage / Object Store

Cost Baseline

Unit economics: $[X] per [1,000 requests / 1,000 users / GB processed]

3. Growth Projections

Assumptions

Traffic Forecast

Growth formula: [Baseline] × (1 + [monthly rate])^[months] + seasonal adjustment

Capacity Headroom Analysis

When does each resource run out at current utilisation and projected growth?

Red flags (resources hitting ceiling within 3 months):

• [Resource]: [current]% → ceiling in [X weeks] — Action required
• [Resource]: [current]% → ceiling in [X weeks] — Action required

4. Resource Requirements

Compute Requirements

Memory headroom target: Maintain ≥30% available memory at average load; ≥20% at peak. CPU headroom target: Maintain ≥30% available CPU at average load; ≥15% at peak.

Database Requirements

Storage growth management:

• Current growth: [~X GB/month]
• Storage auto-scaling: [Enabled / Not enabled — enable by [date]]
• Archiving policy: [Records older than X months moved to [cold storage / archive tier]]

Cache Requirements

5. Scaling Strategy

Compute — Horizontal Scaling

Decision: [Horizontal / Vertical / Both]

[State the scaling strategy and the reasoning. E.g. "The application is stateless and CPU-bound; horizontal scaling is preferred. Vertical scaling is a short-term fallback only."]

Auto-scaling configuration:

Scale-out trigger:  CPU > [X%] for [Y minutes] OR memory > [X%] for [Y minutes]
Scale-in trigger:   CPU < [X%] for [Y minutes] AND memory < [X%] for [Y minutes]
Min instances:      [X] (ensures HA across [X] AZs)
Max instances:      [Y] (cost ceiling)
Cooldown period:    [X seconds]
Warmup time:        [X seconds] (time for new instance to be healthy)

Limits of horizontal scaling:

• [e.g. Database connection pool is the current bottleneck — adding more app instances without increasing DB connections will not help]
• [e.g. Session affinity required for WebSocket connections — limits pure stateless scaling]

Database — Read Scaling

Strategy: [Read replica / Connection pooling via PgBouncer / Query caching / None needed yet]

When to add a read replica:

• DB CPU sustained >60% for >30 minutes, OR
• Read query P95 latency >50ms, OR
• Connection pool utilisation >70%

Connection pooling:

• Pooler: [PgBouncer / RDS Proxy / application-level / not configured]
• Pool size: [X connections per app instance × Y instances = Z total]
• Max DB connections: [configured to Z + 20% headroom]

Caching Strategy

Cache policy: [Cache-aside / Write-through / Write-behind] TTL strategy:

Cache miss handling: [Describe what happens on a cache miss — does it fall through gracefully or cause a thundering herd risk?]

6. Cost Projections

Infrastructure Cost Forecast

Unit economics trend:

Cost optimisation opportunities:

7. Capacity Triggers and Actions

Define the thresholds that require explicit action — not retrospective fixes after an incident.

When a Watch threshold is crossed:

• Engineer who observes it creates a ticket with capacity label
• Ticket reviewed in next sprint planning

When an Act threshold is crossed:

• On-call engineer creates a ticket marked P2
• Tech lead reviews within 24 hours
• Action plan documented and scheduled within 1 sprint

When an Emergency threshold is crossed:

• Treat as a potential incident — page on-call
• Emergency scaling actions taken immediately (see runbook)
• Root cause investigation starts within 2 hours

Emergency scaling runbook: [Link to oncall-runbook for capacity incidents]

8. Infrastructure Action Roadmap

Immediate Actions (next 2 weeks)

This Quarter (within 3 months)

Next Quarter (3–6 months)

Horizon (6–12 months)

Anti-Patterns

• Do not set capacity trigger thresholds without knowing the baseline — a "CPU > 70%" alert is meaningless if you don't know what normal looks like
• Do not plan only for average traffic — capacity plans that don't model peak load will result in incidents during the events that matter most
• Do not conflate vertical and horizontal scaling — adding more app servers without addressing database connection limits will not resolve the constraint
• Do not present growth projections as certainties — all forecasts have uncertainty; state the confidence level and provide a conservative and optimistic scenario
• Do not defer action items without a named owner and a specific date — a roadmap with no owners is a wish list

Quality Checks

• Every resource has a quantified current utilisation and a projected months-to-ceiling — no hand-waving
• The most critical constraint is called out in the executive summary with a specific timeline
• Growth projections state their assumptions and confidence level — not presented as certainties
• Capacity triggers define amber/red thresholds and name who acts at each level
• Cost projections include unit economics, not just absolute totals
• The infrastructure roadmap has named owners and effort estimates — not just a wish list
• Auto-scaling configuration includes both scale-out AND scale-in triggers, and a min/max range
• Actions are ordered by urgency — immediate items are genuinely immediate, not backlog filler