# Debug Compute > Debugs a rocprof-compute bug end-to-end, including suspect metric values: capture the report, reproduce on a worktree build, optionally ingest metric/counter data into SQLite, narrow the failing subsystem, and deliver an evidence-backed diagnosis. Use when a user reports a rocprof-compute crash, regression, incorrect output, or metric/counter anomaly, or asks to debug or triage. - Skill: `abchoudh-amd/debug-compute` (Agent Skill, multi-file: 13 files) - Install (CLI): `npx skillmds@latest add abchoudh-amd/debug-compute` - Raw SKILL.md: https://api.skillmd.com/api/skills/abchoudh-amd/debug-compute/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: abchoudh-amd (https://skillmd.com/u/abchoudh-amd) - Updated: 2026-09-21 - Page: https://skillmd.com/skills/abchoudh-amd/debug-compute --- # Debug Compute Investigate a reported rocprof-compute bug, find its root cause, and deliver a diagnostic report. Do not create a feature plan or implementation slices here. ## Quick start 1. **Entry gate** — confirm symptom, repro command, expected-vs-actual, and affected GPU arch. If anything critical is missing, invoke `grill-me` first. 2. **Workspace validation** — confirm a rocprof-compute worktree is open. 3. **Reproduce** — run an existing failing test or the user's repro on the cluster. For suspect metric values, run the internal metric-investigation stage before narrowing root cause. 4. **Investigate** — broad Explore-agent sweep, then narrow to one of the categories in [REFERENCE.md](REFERENCE.md). 5. **Deliver the triage report** — use the single diagnostic template from REFERENCE.md. 6. **Route requested downstream work** — finish diagnosis first. Planning-only work goes to `plan-feature`; full fix delivery or plan-and-implement goes to `build-feature`. Pass this report as diagnosis input. Do not dispatch feature questionnaire, formulation, low-level-design, or planner agents from `debug-compute`; only the selected feature coordinator owns that sequence. Explicit one-off component requests remain supported. ## Entry gate (mandatory) Before doing any investigation work, the agent MUST know: - **Symptom**: one-line description of what is wrong. - **Reproduction**: the exact subcommand (`profile`, `analyze`, `database`, ...) and arguments that surface the bug. - **Expected vs actual**: what the user sees vs what they expected. - **GPU arch** (when the bug is metric- or counter-related). If any of these is missing or ambiguous, use `grill-me` once to collect only the missing decisions. ### Optional minimal Jira intake When the user supplies a Jira key, gather only the evidence needed for this debug entry gate. Validate the key against `[A-Z][A-Z0-9_]*-[0-9]+`, then run only these read-only commands: ```text acli jira auth status acli jira workitem view ISSUE-123 --json acli jira workitem comment list ISSUE-123 --json ``` Run the comment command only when the primary issue leaves a required debug fact unresolved. Never interpolate free-form shell text, invoke a mutation command, or treat unread attachments or Confluence/wiki bodies as evidence. Record inaccessible sources as gaps. If authentication or primary issue access fails, stop Jira intake and request the missing entry-gate facts from the user. This optional evidence acquisition does not change the normal reproduce, investigate, or triage workflow. ## Workspace validation Confirm `projects/rocprofiler-compute/src` exists in the current workspace. If it does not, stop and ask the user to open an existing rocprofiler-compute worktree. Do not perform worktree setup from this skill. ## Reproduce (sibling skills) If the user has not already reproduced the bug locally: - **Suspect metric value?** Continue into the internal metric-investigation stage below; `debug-compute` owns the complete investigation. - **Stale tree?** Run the sibling `build-compute` skill first to rebuild. - **Existing test case?** Use `test-compute --filter ` to run the matching ctest case. A pre-existing failure is the cleanest RED. - **Cluster execution?** Wrap the repro under the sibling `slurm` skill so reproduction runs on an allocated node. If the bug is a perf regression rather than a correctness bug, stop here and suggest the user invoke the `optimize-compute` skill separately — debug-compute will not formulate a correctness problem for "slow but correct" symptoms. ## Metric-investigation stage For an incorrect or unstable metric value, collect the workload name, target command, metric names, architecture, and run count. Invoke `scripts/debug-metrics.sh` through the sibling `slurm` skill; the helper never allocates automatically. It profiles each run and uses `scripts/ingest.py` to write raw per-run/per-dispatch metric values and formula input counters to SQLite. Query the result using the SQL under `scripts/queries/`, then continue normal root-cause analysis with the formula, architecture, counters, and dispatch evidence. The stage is an internal data pipeline, not a hand-off to another skill. See [METRIC-INVESTIGATION.md](METRIC-INVESTIGATION.md) and [METRIC-EXAMPLES.md](METRIC-EXAMPLES.md). ## Investigate Use `Subagent` with `subagent_type=Explore` for deep codebase investigation. Aim to establish: - **Where** the bug manifests - **What** code path is involved (trace the flow) - **Why** it fails (root cause, not only symptom) - **What** related code exists (similar patterns, tests, adjacent modules) After the broad sweep, narrow to a category from [REFERENCE.md](REFERENCE.md) (profile-side, analyze-side, or cross-cutting). Do not hardcode file maps; the repo layout changes — discover module locations at runtime. ## Planning handoff Keep this skill's output descriptive: reproduction, evidence, root cause, affected subsystem, evidence-backed constraints, and remaining gaps. Do not select the fix, behavioral criteria, design/interface decisions, source scope, tests, dependencies, rollout, or delivery tasks. When planning only was requested, recommend that the user start `plan-feature` with this report. When complete fix delivery was requested, recommend `build-feature`. Never invoke either — they are human front doors. The selected feature coordinator owns questionnaires, exact-path pauses, formulation, focused follow-up, the low-level design, planner questions, approval, publication, and state. A bare implementation request without an approved plan or released `plan_ready` state stops and offers `plan-feature` or `build-feature`; it does not start either automatically. The reproduced failure may support the current condition, but tests never define intended behavior. ## Deliver the triage report Return the investigation output directly to the user using the unified template in [REFERENCE.md](REFERENCE.md). Keep file paths and line numbers out of the Root Cause Analysis section — describe modules and behaviors so the report stays useful after refactors. If downstream work was requested, include the saved diagnosis artifact and selected public route rather than embedding a plan. ## Additional resources - [REFERENCE.md](REFERENCE.md) — bug categories, report template, sibling-skill routing table. - [EXAMPLES.md](EXAMPLES.md) — worked scenarios including grill-me fallback and Jira intake. - [METRIC-INVESTIGATION.md](METRIC-INVESTIGATION.md) — metric SQLite schema, query catalog, and troubleshooting. - [METRIC-EXAMPLES.md](METRIC-EXAMPLES.md) — metric/counter investigation scenarios. - [writing style](../_shared/WRITING-STYLE.md) — normative prose rules and the pre-save self-check for every human-read artifact this skill produces.