Productionize This Codebase

mkdir -p ~/.claude/commands

# Productionize This Codebase

Deep, autonomous non-functional-requirements (NFR) review of a vibe-coded, functionally-complete app — surfaces production-readiness gaps (performance, efficiency, security, capacity, extensibility, rate limiting in and out of the app, and anything else a real production deployment needs) and hands back a findings + action list + phased remediation plan. **Read-only**: this skill never edits application code — it only ever produces documentation for you to act on separately.

## Usage

```
/productionize
/productionize focus heavily on outbound rate limiting — we're getting 429s from a third-party API and I think our retry/backoff design is wrong
/productionize docs/productionization/rate-limit-focus.md
```

- **No argument** → comprehensive sweep across every default category below, no special emphasis.
- **Argument that resolves to an existing file** (relative to the repo root, or absolute) → read that file in full as this run's detailed customization instructions. Treat its contents as **additive** to the default category list (it narrows/emphasizes, it doesn't silently drop categories) unless the file explicitly says to skip something.
- **Argument that is not a valid file path** → treat it as inline free-text focus/emphasis for this run, layered on top of the default full sweep the same way.

## Step 0 — Resolve this run's focus

1. Work out which of the three argument modes above applies.
2. Derive a short kebab-case slug from the focus for filenames (e.g. `outbound-rate-limiting`, `full-sweep` if no argument was given).
3. Note today's date (`date +%Y-%m-%d`).

## Step 1 — Ground yourself in the real codebase first

Do this yourself before writing anything — don't hand a blind brief to the investigating agent. Use Explore agents for a large/unfamiliar codebase; read key files directly for a small one. At minimum, establish:

- Language(s), framework(s), how it's built/run/deployed (`package.json`/equivalent scripts, Dockerfile, CI config, IaC, hosting platform).
- What NFR-relevant mechanisms already exist: rate limiting or throttling (inbound and outbound), retry/backoff logic, circuit breakers, caching, connection pooling/limits, timeouts, logging/observability, secrets management, authn/authz, error handling patterns, existing test coverage, CI/CD gates.
- Every third-party API/service the app calls — especially load-bearing if this run is about outbound rate limiting: enumerate them, any documented rate limits you can find in code/config/comments/vendor docs, and exactly how the app currently reacts to 429s/backpressure/timeouts from each (retries? backoff? queuing? nothing at all?).
- Whether any existing project docs (README, CLAUDE.md, architecture notes) describing current NFR posture are trustworthy — verify against actual code rather than assuming they're current; call out anything stale.

## Step 2 — Write a self-contained, repo-grounded brief

Write it to `docs/productionization/<date>-<slug>-BRIEF.md` (create the directory if needed). It must stand alone — the agent executing it in Step 3 has no memory of this conversation. Include:

- **Mission** — the investigating agent acts as a multi-disciplinary production-readiness review team (performance engineer, security engineer, SRE/capacity planner, API-integration architect, technical writer) auditing this specific codebase — not a generic checklist exercise.
- **Grounding section** — every verified fact from Step 1 (stack, deployment target, what NFR mechanisms already exist, the third-party dependency inventory, any stale-doc warnings), phrased as verified facts, so the agent starts from reality instead of re-deriving it or guessing.
- **Review categories** — always in scope unless this run's focus explicitly narrows them out (state clearly whether this run narrows scope to one category or just weights it more heavily within a full sweep):
  - Performance
  - Efficiency (compute/memory/cost, not just latency)
  - Security
  - Capacity (what load does this actually fall over at, and where's the ceiling)
  - Extensibility (how much pain does the next feature/integration cost, architecturally)
  - Rate limiting — **inbound**: is this app's own surface (API routes, webhooks, public endpoints) protected against abuse/overload?
  - Rate limiting — **outbound**: for every third-party API/service the app depends on, is there real backoff/retry/concurrency-control/circuit-breaking, or does it just hammer the API and hope?
  - Other NFRs the agent should proactively identify and is expected to go looking for even though they're not enumerated above — explicitly prompt for: observability/monitoring/alerting, resilience & error handling, logging & audit trails, secrets/credentials management, backup & disaster recovery, dependency/supply-chain health, cost efficiency, compliance considerations (if applicable to the domain), deployment & rollback safety, operational runbooks/documentation, test coverage & CI/CD gates.
- **This run's focus** — the resolved emphasis/narrowing from Step 0, stated explicitly.
- **Working method**:
  - **Read-only.** Never edit application code, never run destructive or state-changing commands, never commit, stage, or push anything.
  - Verify claims empirically wherever you safely can without modifying anything — run the app locally, exercise real endpoints, read actual response headers/timings/logs, run the *existing* test suite — but do not add, change, or commit code to do so.
  - Work autonomously without pausing to ask questions. If something is genuinely ambiguous or needs a business/human judgment call (budget, risk appetite, compliance posture), record it as an open question in the report rather than stopping.
  - There is no time limit — investigate as long as it takes to be thorough. Depth over speed.
- **Required report structure** (so every run is consistent and comparable over time) — write the final report to `docs/productionization/<date>-<slug>-REPORT.md`:
  1. **Executive summary** — a few sentences: overall production-readiness verdict, top 3–5 risks.
  2. **Findings**, grouped by category. Each finding needs: severity (Critical/High/Medium/Low), one-line summary, concrete evidence (real `file:line` references — no vague claims), a concrete failure scenario (what breaks, under what real-world condition — mirror the rigor of "concrete inputs/state → wrong output/crash", not generic advice), and a recommended action.
  3. **Tangible action list** — a flat, prioritized checklist derived straight from the findings, usable directly as a backlog.
  4. **Phased remediation plan** — group actions into phases (e.g. "before any real traffic", "before scaling up", "nice to have"), noting rough effort and any dependencies between phases.
  5. **Open questions** — anything needing a human/business decision rather than a pure engineering call.

## Step 3 — Launch the investigation

1. Determine the model: default to `fable`. If the resolved focus (inline text or customization file) explicitly requests a different model (e.g. "model:sonnet", "use opus"), honor that instead.
2. Launch via the Agent tool with that model, `run_in_background: true`, instructing it to read the brief file in full and execute it exactly, writing its report to the path specified in the brief.
3. Do not poll or wait. Tell Simon the investigation has been launched, where the brief lives, and that you'll relay results when it completes.

## Step 4 — When it reports back

- Read the produced report yourself and spot-check a handful of its `file:line` claims against the real repo before relaying anything — don't take it on faith.
- Give Simon a concise summary: top findings by severity, the prioritized action list, where the full report and plan live. Don't dump the entire report inline.
- Do not implement anything from the findings yourself — this skill's job ends at the report. Acting on it is a separate, explicit follow-up.

## Notes

- This skill produces documentation only, on purpose — it's meant to run repeatedly over a project's life with different focuses (e.g. first an outbound-rate-limiting-specific run, later a full sweep, later a security-specific pass), and `docs/productionization/` becomes a running, dated audit trail. Don't collapse runs into one file.
- The brief this skill writes should read like a grounded engineering document, not a generic checklist: every claim in it should be something you actually verified in Step 1, not boilerplate. That rigor is the entire point — it's what lets the investigating agent spend its time finding real problems instead of re-discovering facts about the repo it's sitting in.
- Deliberately does not `git add`/`commit`/`push` anything, including its own brief/report files — leave them as new, uncommitted files for Simon to review and commit himself once he's read them.

cd /path/to/your/project
claude

/productionize