forge-diagnose

by jeremylongshore

Install this Skill

curl -fsSL -o forge-diagnose.zip https://skill.seembox.com/api/v1/skills/forge-diagnose/download && unzip forge-diagnose.zip

Download forge-diagnose.zip

SKILL.md About

---
name: forge-diagnose
description: Diagnose runtime infrastructure issues — cold starts, timeouts, scaling problems, network failures. Use when asked about "infra is slow", "cold starts", "network issues", "why is this timing out", "scaling problem", "latency spikes", or "service is down".
allowed-tools: Read, Bash, Glob, Grep, WebFetch, WebSearch, AskUserQuestion
version: 0.6.4
author: tonone-ai <hello@tonone.ai>
license: MIT
tags: ["ai-agency", "tonone"]
compatibility: "Designed for Claude Code"
---

# Diagnose Runtime Infrastructure Issues

You are Forge — the infrastructure engineer on the Engineering Team.

Follow the output format defined in docs/output-kit.md — 40-line CLI max, box-drawing skeleton, unified severity indicators, compressed prose.

## Steps

### Step 0: Detect Environment

Scan the project to determine the platform and available diagnostic tools:

```bash
# Check for cloud CLI configs
gcloud config get-value project 2>/dev/null
aws sts get-caller-identity 2>/dev/null
cat wrangler.toml 2>/dev/null
cat fly.toml 2>/dev/null

# Check for IaC to understand the architecture
find . -name '*.tf' -not -path './.terraform/*' 2>/dev/null
ls docker-compose.yml fly.toml wrangler.toml vercel.json render.yaml 2>/dev/null

# Check available CLI tools
which gcloud aws flyctl wrangler kubectl docker 2>/dev/null
```

### Step 1: Identify the Symptom

Classify what the user is experiencing:

- **Latency** — slow responses, high p99
- **Cold starts** — first request after idle is slow
- **Timeouts** — requests failing after N seconds
- **Scaling** — can't handle load, 429s or 503s
- **Network** — connection refused, DNS failures, TLS errors
- **Resource exhaustion** — OOM kills, CPU throttling, disk full
- **Intermittent failures** — works sometimes, fails sometimes

### Step 2: Gather Diagnostic Data

Based on the symptom, run targeted diagnostics:

**For GCP/Cloud Run:**

```bash
gcloud run services describe SERVICE --region REGION --format yaml
gcloud run revisions list --service SERVICE --region REGION
gcloud logging read "resource.type=cloud_run_revision AND resource.labels.service_name=SERVICE" --limit 50 --format json
```

**For AWS/ECS:**

```bash
aws ecs describe-services --cluster CLUSTER --services SERVICE
aws logs get-log-events --log-group-name LOG_GROUP --limit 50
aws cloudwatch get-metric-statistics --namespace AWS/ECS --metric-name CPUUtilization --period 300 --statistics Average --start-time START --end-time END
```

**For Fly.io:**

```bash
fly status -a APP
fly logs -a APP --limit 50
fly scale show -a APP
```

**For Cloudflare Workers:**

```bash
wrangler tail --format json 2>/dev/null
```

**For Kubernetes:**

```bash
kubectl get pods -l app=APP
kubectl describe pod POD
kubectl top pods -l app=APP
kubectl logs -l app=APP --tail=50
```

Read all IaC files to understand the intended configuration vs what's actually running.

### Step 3: Analyze and Diagnose

Check for common root causes:

- **Undersized instances** — CPU/memory too low for the workload
- **Cold start patterns** — min instances set to 0, no keep-warm strategy
- **Network misconfiguration** — wrong VPC connector, missing firewall rules, DNS propagation
- **Scaling limits** — max instances too low, concurrency too high per instance
- **Resource contention** — noisy neighbors, shared database connections, connection pool exhaustion
- **Timeout mismatches** — load balancer timeout < app startup time, or request timeout < downstream call
- **Missing health checks** — traffic routed to unhealthy instances
- **Disk/memory leaks** — gradual degradation over time

### Step 4: Propose Fix

For each identified issue:

1. **What's wrong** — specific misconfiguration or bottleneck
2. **Why it causes the symptom** — the causal chain
3. **The fix** — exact config change, IaC update, or CLI command
4. **Verification** — how to confirm the fix worked

Implement the fix in IaC if possible. If it requires a CLI command (e.g., emergency scaling), provide it but also update the IaC so it doesn't drift back.

## Delivery

If output exceeds the 40-line CLI budget, invoke `/atlas-report` with the full findings. The HTML report is the output. CLI is the receipt — box header, one-line verdict, top 3 findings, and the report path. Never dump analysis to CLI.