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 | Paid plans, self-hosted | 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.
Missing or failed artifacts
An opportunity record and its standalone artifact have separate lifecycles. A missing artifact can mean it was never generated, was removed by retention, generation is disabled, an allowance was exhausted, or the opportunity uses a related incident bundle. Missing evidence alone does not establish a generation failure.
The read-only OpenAI connection reports missing objects as missing and explains incident coverage, disabled generation, and allowance exhaustion separately. Recorded build errors and unreadable artifacts report failed with different explanations. A readable existing artifact remains available if a later generation fails. The connection does not regenerate artifacts; use the authorized management workflow for a deliberate repair.
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
Paid and self-hosted projects expose project-level hosted improvement settings:
automated_improvement_bundles_enabledimprovement_bundle_sensitivity
Sensitivity modes:
| Mode | Intent |
|---|---|
high_confidence | Default mode. Fewer, stricter opportunities |
balanced | Broader coverage when you want more suggestions without going fully verbose |
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
- Plan comparison — Tier availability for hosted automated improvement bundles
- Webhooks Events —
improvement_bundle.createdlifecycle event
Weekly project reviews
Smart improvements are weekly project reviews, separate from the improvement bundles described above. The workspace Owner can open Improvements → Weekly reviews → Weekly review settings, choose current projects and give explicit evidence/provider consent once. Future projects never join automatically. Reviews cover the latest completed UTC week each Monday at 09:00 UTC.
The Opportunities tab keeps the existing improvement inventory. The
Weekly reviews tab has its own link at /improvements/reviews, with saved
reviews, refresh and authorised settings controls. Switching views does not
generate a review or change consent.
Team includes up to five selected projects and twenty-five paid reviews per anchored allowance month; Business includes ten projects and fifty paid reviews. This pool is separate from report generations and bundle capacity. Existing customers default off. No data or unchanged evidence makes no provider request; missing or unqualified AI leaves recorded evidence and deterministic checks.
A review links bounded retained incidents, qualified improvement opportunities, aggregate analytics and monitored health. Optional hypotheses are unverified investigation suggestions. It does not inspect your repository/UI, perform actions, create posts, resolve incidents or send email. Raw logs, headers, bodies and individual analytics identities are excluded. Recorded incident-to-improvement relationships are retained as evidence links, not inferred causes. Investigations should say what to inspect, what could confirm or disprove a tentative explanation, and how to verify a bounded change. Analytics checks include denominators, sampling and comparable flows; health checks separate overlapping monitors from account outages. Generic growth advice and speculative content marketing are not the purpose of these reviews.
Restricted uses generic source labels without captured narratives; Full uses bounded redacted titles/summaries. Disabling the schedule preserves history; removing consent/projects or narrowing privacy deletes affected saved content. Current whole-scope access and shorter governing retention still apply; the maximum is ninety days. Paid uncertainty stays held without automatic paid retry.
debugbundle improvements reviews list ORGANISATION_ID --json
debugbundle improvements reviews bundle ORGANISATION_ID REVIEW_ID --json
debugbundle improvements reviews settings ORGANISATION_ID --json
debugbundle improvements reviews allowance ORGANISATION_ID --jsonUse improvements reviews configure ORGANISATION_ID --settings-json JSON to
replace settings with expected_version, explicit project_ids, enabled,
source_consent, and privacy_mode. API starts at
/v1/organizations/ORGANISATION_ID/improvements/reviews; ordinary MCP includes
list_improvement_reviews, get_improvement_review_bundle and
update_improvement_review_settings. Reads never generate work. Restricted/OpenAI
connections do not acquire new operations or permissions.
An agent using ordinary MCP or the CLI can ask for consent in chat, read current settings and allowance, then enable the selected projects using the current workspace Owner's authorised credential. Confirm the workspace, projects, privacy mode and recurring weekly evidence/provider use first, and read settings back after saving. This enables the weekly schedule; it does not offer an immediate paid regeneration. AI suggestions appear when the service is available. The read-only DebugBundle/OpenAI connection cannot perform this change. Chat consent does not elevate permissions or include projects added later.
Review plans and configuration checks
A weekly review plan provides clear next steps: Investigate failure, Review noise, Improve flow, or Collect evidence. Each step links its observations, explains the priority, identifies what to inspect and gives a verification condition. Older saved reviews remain readable; their original evidence is not rewritten.
Noise reviews use the controls DebugBundle already offers: capture presets and verbosity, scoped capture rules, alert cooldowns and email aggregation, improvement sensitivity, and temporary diagnostics. SDK-local filters require inspection by an authorised coding agent. A repeated warning or resource failure first needs an expected-behaviour and user-impact check. Use existing incident-based rule suggestions rather than inventing a broad matcher.
These controls have different effects. Demotion can stop incident churn while retaining context and accepted event usage. Sampling or dropping changes retained event volume. Cooldowns and digests change notifications. Improvement sensitivity changes opportunity discovery. Verify useful errors, critical alerts and regressions remain visible after any deliberately authorised change.
Analytics plans use available measured denominators, sampling and observation windows. Missing measurements lead to evidence collection; low traffic alone does not justify a UI change. A quiet week, deleted source or resolved status does not prove a fix. Compare subsequent observations under equivalent traffic and capture settings.
Factual plans remain useful when AI suggestions are unavailable. Reviews never apply configuration or code changes themselves.
debugbundle improvements reviews plan ORGANISATION_ID REVIEW_ID --jsonAPI callers read /plan; ordinary MCP callers use
get_improvement_review_plan. The existing bundle export remains available. See Managing Noise and
Reducing Ingested Events for the existing controls
and their effects.