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

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 <regex> 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 and 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 (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. 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 — bug categories, report template, sibling-skill routing table.
• EXAMPLES.md — worked scenarios including grill-me fallback and Jira intake.
• METRIC-INVESTIGATION.md — metric SQLite schema, query catalog, and troubleshooting.
• METRIC-EXAMPLES.md — metric/counter investigation scenarios.
• writing style — normative prose rules and the pre-save self-check for every human-read artifact this skill produces.