DebugBundle
Bundles

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:

FlowAvailabilityWhat it does
Local/manual improvement analysisAll tiersRun debugbundle analyze --type improvement --local against local bundles and repository context
Hosted automated improvement bundlesPaid plans, self-hostedGenerate 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_event telemetry
  • log_event telemetry
  • 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:

  1. creates or updates an improvement opportunity
  2. builds a standard BundleV1 artifact with bundle_type: "improvement"
  3. stores it under the improvement bundle object path
  4. emits improvement_bundle.created when 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:

KindWhat it looks for
warning_hotspotRepeated warning/error logs with a stable canonicalized message
slow_requestRepeated slow requests on the same route/service/environment
request_failure_patternRepeated contextual request failures that do not need to become incidents first
recurring_incidentOpportunity-only signal for incidents that repeatedly reopen or keep crossing recurrence thresholds; inspect related_incident_ids
post_deploy_regressionOpportunity-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 bundleImprovement bundle
Explains what brokeExplains what keeps degrading, repeating, or regressing
Centers on an incident or hard failure signalCenters on an improvement opportunity record
Prioritizes debugging an active failurePrioritizes hardening, cleanup, and pre-incident optimization
Generated from incident/failure groupingGenerated 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_enabled
  • improvement_bundle_sensitivity

Sensitivity modes:

ModeIntent
high_confidenceDefault mode. Fewer, stricter opportunities
balancedBroader coverage when you want more suggestions without going fully verbose
verboseMore 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.created lifecycle 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 --json

Use 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 --json

API 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.

On this page