Community diagnostic prompt for actionable CBM bug reports

[Today20092]

Community diagnostic prompt for actionable CBM bug reports

Codebase Memory MCP provides useful logs and an opt-in diagnostics trajectory, but collecting the right evidence—in the right order—can still be difficult when the server hangs, leaks memory, fails during startup, or carries a large stale cache.

I used an AI-assisted workflow to investigate a Windows installation and found that what initially looked like one problem mapped to three existing issues:

• slow eager project enumeration;
• indexing-worker hangs with poor failure attribution;
• stale indexes retained after temporary worktrees disappeared.

The workflow helped us avoid filing a duplicate, add measured evidence to the correct issues, and recover the local installation without touching source files.

Below is a self-contained prompt other users can paste into an AI coding agent. It combines two disciplines:

1. build a reproducible feedback loop before guessing at a cause;
2. require explicit evidence and completion criteria so the report is useful to maintainers.

It does not require a particular agent framework or locally installed skill.

Copy-paste prompt

Give the complete block to an agent with terminal and GitHub access. The agent will begin by asking a short set of intake questions, so users do not need to edit the prompt first. Screenshots and errors can be attached with the prompt or supplied when requested.

You are diagnosing a Codebase Memory MCP (CBM) failure and preparing actionable upstream evidence.

Your outcome is:

1. reproduce or precisely observe the reported symptom;
2. collect the smallest sufficient, redacted evidence set;
3. search existing DeusData/codebase-memory-mcp issues;
4. decide whether the evidence belongs in an existing issue or a new report;
5. prepare a readable Markdown report;
6. publish only when the user has authorized publishing.

## Step 0: begin with a short intake

Before running commands or changing anything, ask the user the following questions in one concise message:

1. What is CBM doing wrong, and what did you expect instead? Ask for the exact error, screenshot, or approximate timing if available.
2. Which project or directory shows the problem, and which client launches CBM (Codex, Claude Desktop, VS Code, CLI, or another client)?
3. May you restart CBM-backed sessions if diagnostics require a clean daemon start?
4. May you change local CBM configuration when necessary to enable diagnostics?
5. If you find useful upstream evidence, should you only prepare a draft, or may you publish an issue/comment after showing the user the final text?

Ask only for information the user is likely to know. Discover version, platform, hardware, cache paths, Git metadata, process state, and logs yourself through read-only inspection.

If the user already supplied an answer, do not ask for it again. If the user cannot answer a nonessential question, record it as unknown and continue. Do not begin process termination, configuration edits, reproduction, or publication until the corresponding permission is explicit.

After the user answers, summarize the symptom and authorized scope in two or three lines. Then begin Step 1.

Completion criterion: the primary symptom, target project/client, and permissions for restart, configuration changes, and publication are explicit.

## Safety and privacy

- Treat diagnosis and repair as separate activities.
- Begin with read-only inspection.
- Do not delete indexes, caches, source files, logs, or configuration without explicit user authorization.
- Do not kill processes or close daemon-backed sessions unless the user authorized a diagnostic restart.
- Prefer supported CBM operations over direct cache-file manipulation.
- Before material cleanup, resolve exact targets and explain recoverability.
- Never publish credentials, tokens, authentication headers, proprietary source, query text, private log strings, or unrelated personal paths.
- Replace sensitive values with <REDACTED>.
- CBM trajectory files contain resource counters rather than source or query text, but inspect every artifact before publishing.
- If the finding may be a security vulnerability, stop public publication and use:
  https://github.com/DeusData/codebase-memory-mcp/security/advisories/new

## Step 1: establish the environment

Collect:

- codebase-memory-mcp --version;
- operating system, architecture, and OS build;
- installation channel, if discoverable;
- binary variant (standard or ui), if discoverable;
- client or editor launching CBM;
- CPU model and installed RAM for hangs, crashes, or performance problems;
- available disk space when cache/database I/O may be relevant;
- whether the target is a Git working tree;
- public repository URL, commit SHA, and relevant path when shareable;
- approximate project scale: files, nodes, edges, project count, and cache size when relevant.

Do not guess unavailable values. Mark them unknown.

Completion criterion: the report identifies the affected CBM build, platform, client, and reproducible project without exposing private material.

## Step 2: classify the failure

Choose one primary branch:

- startup or transport failure;
- indexing-worker hang or crash;
- slow MCP/CLI query;
- memory growth or suspected leak;
- stale-cache or project-enumeration problem;
- incorrect graph result;
- other.

Record secondary symptoms separately. Do not collapse multiple causes into one issue merely because they appeared during the same session.

Completion criterion: one primary symptom has a measurable pass/fail or expected/actual signal.

## Step 3: build a reproduction loop

Create one command or MCP tool call that detects the specific failure.

Capture:

- exact command or MCP tool name;
- complete arguments, with sensitive values redacted;
- start and end timestamps;
- exit code;
- actual result;
- expected result;
- duration;
- reproduction rate if intermittent.

For a public reproduction, pin the repository and commit. If the original project is private, find a minimal dummy project or public OSS repository showing the same symptom. Do not publish proprietary code or logs.

For slow failures, measure a baseline before changing configuration.

Completion criterion: the command has been run at least once and can distinguish broken behavior from expected behavior.

## Step 4: capture CBM diagnostics when relevant

Use diagnostics for memory, performance, leak, and long-running hang reports.

Important: the shared daemon captures CBM_DIAGNOSTICS from the session that starts it.

1. Set CBM_DIAGNOSTICS=1 in every relevant MCP server environment block, or export it before the first daemon-backed session.
2. If a daemon is already running, close all daemon-backed sessions and wait for it to exit before restarting.
3. Reproduce the problem long enough to reveal the trend. A slow leak may require an extended run.
4. Locate the diagnostics.start event in:

   [CBM_CACHE_DIR]/logs/cbm-daemon.log

5. Record the randomized diagnostics directory and preserve:

   - trajectory.ndjson: resource samples approximately every five seconds;
   - trajectory.ndjson.1: rotated history, if present;
   - snapshot.json: latest live snapshot, when present.

The directory normally appears below $TMPDIR, /tmp, or %TEMP%.

Analyze the trajectory:

- sample count and observed duration;
- first, last, minimum, maximum, and delta for RSS;
- the same values for committed memory on Windows;
- peak RSS and peak committed memory;
- page-fault change;
- file-descriptor trend when available;
- query-count change;
- whether RSS or committed memory grows monotonically;
- approximate growth per minute and per query;
- whether memory returns after activity stops.

Attach trajectory.ndjson when possible. If attachment is unavailable, paste it only when reasonably small; otherwise provide the analysis and retain the file.

Completion criterion: a diagnostics.start event proves diagnostics were active, and the trajectory covers the relevant reproduction window.

## Step 5: collect focused logs

Inspect:

- [CBM_CACHE_DIR]/logs/cbm-daemon.log;
- worker logs referenced by index.supervisor.worker_failed;
- client MCP logs for startup or transport failures;
- UI GET /api/logs output when using the UI variant.

Extract only lines establishing:

- daemon startup and version;
- request/tool name and duration;
- worker start, timeout, crash, or recovery result;
- exact error identifiers;
- diagnostics-path creation;
- process or worker IDs needed to connect events.

State when a referenced worker log is empty or lacks file/phase attribution. That absence can itself be useful evidence.

Completion criterion: every quoted log line directly supports the symptom or timeline.

## Step 6: run branch-specific checks

### Startup or transport failure

- Determine whether the process exits before or after MCP initialize.
- Check for secure endpoint, ownership, ACL, AppContainer, image-verification, or cache-directory errors.
- Compare client-launched behavior with a manual invocation of the same binary when safe.
- Do not label every “transport closed” symptom as the same root cause; find the server-side error.

### Indexing-worker hang or crash

- Record mode: fast, moderate, or full.
- Record worker timeout duration and retry count.
- Capture worker_failed, quarantine, and recovery events.
- Note whether the responsible file or phase is identified.
- Test a smaller public directory only when it preserves the failure.
- If testing CBM_WORKERS=1, label it a controlled comparison rather than a universal fix.

### Slow query

- Run the identical request more than once.
- Separate cold daemon startup from warm request time.
- Record project count, database count, graph size, and response size.
- Compare a shared cache with an isolated cache only as a controlled experiment.
- Note client truncation separately from server latency.

### Memory growth or suspected leak

- Capture a sufficiently long trajectory.
- Relate memory growth to time and query count.
- Allow an idle period to determine whether memory is retained or released.
- Distinguish a leak from a high transient working set.

### Stale-cache accumulation

- Compare recorded project roots with filesystem existence.
- Count valid and missing roots separately.
- Calculate bytes attributable to missing roots.
- Treat permission errors, unavailable mounts, and uncertain I/O errors as unknown—not missing.
- Do not delete anything during diagnosis.

### Incorrect graph result

- Provide the minimal public code construct.
- Record indexing mode and exact query.
- Show expected and actual symbols or edges.
- Check coverage and parse-partial/skipped signals for every cited file.

Completion criterion: the selected branch's discriminating checks are complete, and alternative causes are separated rather than guessed away.

## Step 7: search before publishing

Search open and closed issues in DeusData/codebase-memory-mcp using:

- exact error identifiers;
- tool names;
- platform;
- version;
- distinctive log events;
- failure class.

Read promising issue bodies and maintainer comments, not only titles.

Compare:

- root cause or strongest available evidence;
- platform and version;
- reproduction command;
- expected and actual behavior;
- proposed solution;
- whether the new evidence materially advances the existing report.

Route the result:

- Strong match: add concise evidence to the existing issue.
- Same surface symptom but different cause: create a separate issue and cross-reference it.
- No adequate match: create a new bug report.
- Insufficient reproduction: prepare a draft and list the missing evidence.

Completion criterion: name the closest existing issues and explain why the chosen destination is or is not a duplicate.

## Step 8: prepare the report

Follow the repository's current bug-report fields:

- Version
- Platform
- Install channel
- Binary variant
- What happened and what was expected
- Reproduction
- Logs
- Diagnostics trajectory
- Project scale
- Confirmation that existing issues were searched
- Confirmation that the reproduction is shareable

Use readable Markdown:

- short headings;
- bullet lists;
- a small table for measurements;
- fenced blocks for commands and logs;
- blank lines between sections;
- direct links to related issues;
- concise prose distinguishing observation from inference.

Recommended structure:

~~~markdown
## Environment

## Actual behavior

## Expected behavior

## Reproduction

## Measurements

## Relevant logs

## Diagnostics trajectory

## Related issues and duplicate analysis

## Local workaround, if verified
~~~

Do not present speculative fixes as established causes. Label hypotheses.

When AI materially drafted the report, add an authorship footer using the actual model and mode:

~~~markdown
---

Written by AI: [model] ([mode]).
~~~

Completion criterion: a maintainer can reproduce the problem, identify the environment, inspect the trend/logs, and understand why the report belongs at its chosen destination.

## Step 9: publish only with authorization

Before creating an issue or posting a comment:

- show the user the proposed title, destination, and Markdown body;
- confirm secrets and proprietary material were removed;
- confirm authorization for external publication.

After publishing:

- return the direct URL;
- preserve the trajectory until the issue is resolved;
- record local workarounds separately from the upstream bug.

If publication is not authorized, save the complete Markdown draft locally and report its path.

## Final response

Summarize:

- primary failure;
- reproduction result;
- strongest evidence;
- diagnostics artifact path;
- related-issue decision;
- publication URL or draft path;
- local changes made, if any;
- remaining evidence worth collecting.

Why these requirements matter

The repository's bug template says the most valuable contribution is a reproduction maintainers can run. It requests the CBM version, platform, installation channel, binary variant, exact command or MCP call, actual versus expected output, logs, diagnostics trajectory, and project scale.

The prompt makes those fields the natural output of the investigation instead of an afterthought. It also adds three safeguards that proved valuable in practice:

• one visible symptom can contain multiple independent bugs;
• an existing issue comment is often more useful than a duplicate report;
• local cleanup may restore service without proving the upstream root cause.

Example outcome from a real investigation

Finding	Evidence	Destination
Slow project enumeration	55–67 seconds with a large shared cache; 52.2 seconds after stale-entry cleanup	Existing issue #1066
Index-worker hangs	Repeated supervisor failures after approximately 30 minutes, without useful file/phase attribution	Existing issue #1130
Stale project accumulation	49 missing roots consuming approximately 4.53 GB	Existing issue #1431

Using an isolated one-project cache reduced a cold list_projects call to approximately 4.8 seconds and allowed a fresh fast index to complete in approximately 8.3 seconds. That was a useful local workaround, but it did not replace the upstream reports.

Feedback welcome

This is a community workflow, not an official CBM support policy. Improvements would be especially useful around:

• Linux and macOS daemon lifecycle commands;
• safe attachment handling across AI clients;
• distinguishing cold-start time from daemon request time;
• other failure branches maintainers frequently see;
• shorter variants for users without terminal automation.

If maintainers find it useful, it could later become a troubleshooting document, issue-form companion, or optional agent skill.

---

Drafted with AI assistance using GPT-5.6 Sol (light mode). The workflow was informed by agent-oriented writing principles and a feedback-loop-first bug-diagnosis process, then tested during a real CBM investigation.