CataloguePerformance, Scale & Cost
Statefulness & Scalability Blocker Audit
Finds state that lives on one machine, so a second instance would be wrong.
What it examines
- Sessions and caches kept in process memory
- Uploads and files on local disk that a later request has to read
- Hostnames and absolute paths written into the code
- Cron on the host instead of the platform
- Background jobs that would run twice with a second replica
- Sticky sessions required for correctness
- Startup work heavy enough to fail a health check during scale-out
What you get back
A findings file. Each item has the evidence, how serious it is, and a fix.
Dependencies
- An AI coding agent that reads SKILL.md files, such as Claude Code, Codex or Gemini CLI
- Read access to the repository, including deployment files, Dockerfiles and any checked-in cron or scheduled-task definitions
- Python 3 with the jsonschema package, to check findings.json before fixing anything
How it works
The audit is read-only. It looks for anything that stops a second copy of the application from running safely.
That includes sessions and caches held in process memory, files written to local disk and read later, hardcoded hostnames and paths, and scheduled jobs that would run once per instance.
You get findings.json and findings.md. The remediate skill reads findings.json. You approve each change.
Setup
- Unzip the download. Copy the audit and remediate folders into your agent's skills folder (for Claude Code, .claude/skills/) in the repository you want to check.
- Check that deployment files and cron definitions are in the repository, because the audit only reads what it can see there.
- Open the repository in your agent and ask it to run the c4-statefulness-audit skill.
- Check the result with the validator: pip install jsonschema, then python3 schema/validate.py findings.json.
- Ask your agent to run the c4-statefulness-remediate skill using findings.json. Fix some findings and leave the rest open if you like.
Run it with your agent
Copy the prompt, fill in the parts in square brackets, and paste it into your agent.
Run the c4-statefulness-audit skill on this repository. Deployment files and cron definitions are in the repository. Mode: audit only. Do not change any code. Write findings.json and findings.md in the repository root.
Run the c4-statefulness-remediate skill using findings.json. Work through the findings I choose, and leave the rest open.