Improvement Bundles
Understand hosted deterministic improvement bundles, what creates them, and how to use them.
Improvement bundles are DebugBundle's deterministic artifact for hardening and optimization opportunities. They are not incident bundles with a different label, and they are not AI-generated plans. They are evidence-driven bundles built from recurring patterns already present in your telemetry.
What They Are
An improvement bundle captures a recurring pattern that is worth addressing before it becomes a larger operational problem.
Examples:
- Repeated slow requests on the same route or service
- Repeated request failures that are noisy but not yet incident-grade
- Warning hotspots with the same canonicalized log pattern
- Incident patterns that should be prioritized through their existing failure bundles
The goal is to give you a bundle-shaped investigation surface for problems that are actionable, but not necessarily urgent failures. When the signal is already an incident, DebugBundle records an improvement opportunity that links to the related incident bundle instead of creating a duplicate improvement bundle.
Availability
DebugBundle supports two improvement flows:
| Flow | Availability | What it does |
|---|---|---|
| Local/manual improvement analysis | All tiers | Run debugbundle analyze --type improvement --local against local bundles and repository context |
| Hosted automated improvement bundles | Solo, Team, self-host | Generate deterministic hosted automated improvement bundles from recurring request and log patterns |
Free tier projects do not receive hosted automated improvement bundles, but they can still use the local/manual analysis flow.
How They Are Generated
Hosted automated improvement bundles are generated by deterministic worker rules. V1 does not depend on an LLM.
The worker evaluates recurring patterns across:
request_eventtelemetrylog_eventtelemetry- incident reopen/regression behavior
- deploy metadata
- rolling counters and frequency windows
When a bundle-producing request or log pattern crosses the configured threshold and passes dedupe/cooldown checks, DebugBundle:
- creates or updates an improvement opportunity
- builds a standard
BundleV1artifact withbundle_type: "improvement" - stores it under the improvement bundle object path
- emits
improvement_bundle.createdwhen a new hosted bundle is persisted
When an incident-derived pattern crosses its threshold, DebugBundle creates or updates the improvement opportunity and stores related_incident_ids. The improvement bundle route returns covered_by_incident_bundle so agents know to fetch the incident bundle instead.
Initial Detection Kinds
V1 hosted improvement detection covers five deterministic signal families:
| Kind | What it looks for |
|---|---|
warning_hotspot | Repeated warning/error logs with a stable canonicalized message |
slow_request | Repeated slow requests on the same route/service/environment |
request_failure_pattern | Repeated contextual request failures that do not need to become incidents first |
recurring_incident | Opportunity-only signal for incidents that repeatedly reopen or keep crossing recurrence thresholds; inspect related_incident_ids |
post_deploy_regression | Opportunity-only signal for incidents that regress after deploy metadata changes; inspect related_incident_ids |
These are intentionally conservative. The purpose is useful signal with bounded noise, not “generate a bundle for every odd event.”
How They Differ From Failure Bundles
| Failure bundle | Improvement bundle |
|---|---|
| Explains what broke | Explains what keeps degrading, repeating, or regressing |
| Centers on an incident or hard failure signal | Centers on an improvement opportunity record |
| Prioritizes debugging an active failure | Prioritizes hardening, cleanup, and pre-incident optimization |
| Generated from incident/failure grouping | Generated from deterministic opportunity rules across request/log data; incident-derived opportunities link back to failure bundles |
Bundle-producing hosted improvements use the same bundle contract shape and retrieval surfaces as failure bundles.
Quota and Retention
Hosted automated improvement bundles count against the existing hosted bundle allowance and retained bundle cap. They do not introduce a separate meter in V1.
Important behavior:
- only persisted hosted automated improvement bundles count
- suppressed candidates and rule evaluations do not count
- improvement generation skips when the hosted bundle allowance is exhausted
- failure debugging keeps higher priority than improvement generation
Project Controls
Solo, Team, and self-host projects expose project-level hosted improvement settings:
automated_improvement_bundles_enabledimprovement_bundle_sensitivity
Sensitivity modes:
| Mode | Intent |
|---|---|
high_confidence | Fewer, stricter opportunities |
balanced | Default tradeoff between usefulness and noise |
verbose | More aggressive detection during hardening or pre-launch review |
Where To Use Them
Hosted automated improvement bundles are available through the same three automation-relevant interfaces:
- Web: global Improvements page, project Improvements tab, improvement detail page
- CLI:
debugbundle improvements ... - MCP/API: list, inspect, bundle fetch, resolve, reopen, snooze, and settings management
Use them when you want to:
- clean up recurring warning or latency issues before launch
- turn “this keeps happening” into a deterministic investigation artifact
- prioritize optimization and hardening across projects
- hand structured, agent-ready context to a workflow without inventing a new artifact type
Next Steps
- Bundles — Overview of the bundle contract and shared bundle model
- Bundle Schema — Full bundle JSON structure
- Pricing — Tier availability for hosted automated improvement bundles
- Webhooks Events —
improvement_bundle.createdlifecycle event