What Are the Bottlenecks?

An open, portable Agent Skill for finding the constraint that actually limits an idea, product, codebase, architecture, workflow, or AI agent.

Most audits produce a long list of issues. This skill asks a harder and more useful question:

What is limiting the goal now, why does it dominate, and what will become the next constraint after it is relieved?

It works from the whole system down to the relevant details. It can start with a one-paragraph idea, a repository, architecture documents, logs, traces, or an operating workflow.

Why this exists

A slow query may be a performance problem without being the product's bottleneck. A storage design may look fine for a demo but become the first scale-breaker. A technically strong bot may be constrained by distribution, provider quotas, conversation-state growth, moderation, human review, or negative unit economics.

$bottleneck keeps these categories separate:

• current constraint — limits the stated goal in the current scenario;
• emerging constraint — likely to limit the next milestone or scale transition;
• risk — serious, but not currently rate-limiting;
• symptom — an observable effect whose upstream cause may be elsewhere;
• unknown — plausible, but the available evidence cannot distinguish the cause.

The result is a ranked diagnosis, not a generic checklist.

What it audits

• Idea quality, demand, adoption, distribution, retention, and validation debt
• Delivery flow, ownership, approvals, feedback delay, and human capacity
• Architecture, code, algorithms, state, coupling, queues, and failure propagation
• Data growth, storage, retention, backup, recovery, migrations, and access patterns
• AI model quality, context growth, retrieval, tools, evals, latency, and cost per outcome
• Infrastructure capacity, observability, reliability, recovery, and operational load
• Security, safety, privacy, compliance, and launch-blocking controls
• Unit economics, vendors, quotas, platform policy, and external dependencies

How it works

1. Define the outcome, actor, success metric, scenario, horizon, and hard limits.
2. Trace the smallest end-to-end flow that produces the outcome.
3. Generate competing bottleneck hypotheses across technical and non-technical layers.
4. Test whether each candidate is truly constraint-like or merely important.
5. Rank the candidates and build the causal chain behind the primary constraint.
6. Recommend the cheapest decisive experiment before a structural redesign.
7. Predict which constraint will appear next.

The skill supports three depths:

• scan — up to three likely constraints for an early idea or small artifact;
• audit — the default repository or mature-proposal assessment;
• deep — cross-layer investigation with history, runtime evidence, and competing hypotheses.

Quick start

Invoke the skill explicitly:

Use $bottleneck to audit this project.
Identify the primary current constraint, what will break first at 10x scale,
and the cheapest experiment that could disprove your diagnosis.

Compatible agents may also activate it automatically for prompts such as:

What is actually holding this product back?
Audit this idea before I build it.
What will break first when this system scales?
Why is this team shipping slowly despite adding more developers?
Find the hidden bottlenecks in this AI-agent workflow.

Installation

The installable skill is in skills/bottleneck.

Codex

Copy the skill directory into a personal or repository skill location:

~/.agents/skills/bottleneck/

or:

<repository>/.agents/skills/bottleneck/

Then invoke it with $bottleneck. Restart Codex if the new skill does not appear immediately.

Other Agent Skills-compatible tools

Copy skills/bottleneck into the tool's supported skills directory. The package uses the open Agent Skills layout: a required SKILL.md, optional references, and optional UI metadata. It has no API, MCP, runtime, or package dependencies.

Examples

Detailed examples are available in examples/:

• Early Telegram bot idea
• Existing repository audit
• AI-agent workflow audit
• CI/release bottleneck gate

Example diagnosis

For an early personal-assistant bot, the skill should not automatically declare storage the primary bottleneck. With no users yet, repeat usage may be the current constraint, while unbounded conversation history is an emerging constraint. The decisive next steps differ:

The skill preserves storage as a real concern while placing it at the correct horizon.

Output

A full audit produces:

• an executive diagnosis;
• the goal, scenario, scale, and inspected boundary;
• a compact critical-flow map;
• a ranked constraint register with evidence for and against;
• the primary causal chain;
• validation, containment, relief, and guard actions;
• the likely next constraint;
• explicit blind spots and confidence limits.

It deliberately avoids fake numerical precision, unsupported scale claims, and recommendations such as caching, microservices, Kubernetes, more agents, or a rewrite unless the evidence shows how they relieve the primary constraint.

Relationship to other approaches

This skill complements rather than replaces:

• profilers and performance optimization, which find measured runtime hotspots;
• architecture trade-off methods, which evaluate quality attributes and design risks;
• security reviews, which identify vulnerabilities and controls;
• workflow frameworks such as GSD, which organize planning, execution, and verification;
• cloud well-architected reviews, which assess provider-specific workload pillars.

Its distinct job is cross-layer constraint diagnosis: connect the business or mission goal to the critical flow, determine what truly limits it, and descend into technical detail only when that detail can change the ranking.

Design principles

• Evidence over assumptions
• System flow before local detail
• One primary constraint per scenario when evidence permits
• Severity and confidence reported separately
• Counterfactual tests instead of labels
• The cheapest discriminating experiment before expensive redesign
• Explicit prediction of constraint migration
• Clear coverage boundaries instead of claiming to have inspected “everything”

Repository structure

.
├── README.md
├── LICENSE
├── examples/
└── skills/
    └── bottleneck/
        ├── SKILL.md
        ├── agents/openai.yaml
        └── references/
            ├── diagnostic-lenses.md
            └── report-contract.md

Contributing

Issues and pull requests are welcome. Useful contributions include:

• raw examples where the obvious problem was not the real constraint;
• domain-specific blind spots that generalize beyond one project;
• trigger prompts that reveal false positives or missed activations;
• improvements that make the diagnosis shorter, more falsifiable, or better evidenced.

Please keep the core skill focused. Long explanations and user-facing material belong in repository documentation, not in SKILL.md.

License

MIT