Optimize Compute

Optimize Compute

Profile the rocprof-compute source CLI with Scalene, interpret bottlenecks, and deliver actionable recommendations.

This skill runs the script directly from the worktree's src/ tree — no build or install step is required. The sibling build-compute skill is unrelated.

Quick start

bash <SKILL_DIR>/scripts/optimize-compute.sh --label baseline -- profile -n smoke -- ./gpu-burn

Replace <SKILL_DIR> with the absolute path to this skill directory. Anything after -- is forwarded verbatim to rocprof-compute.

Entry gate (mandatory)

Before invoking the helper, the agent MUST know two things:

1. The rocprof-compute subcommand to profile (profile, analyze, database, ...).
2. A representative workload for that subcommand — the args after the subcommand, including any -p <workload-path>, -n <name>, target binary, or input arguments.

If either piece is missing or ambiguous in the user's prompt, invoke the grill-me skill first to collect:

• subcommand
• workload command/inputs (small enough to finish quickly under Scalene)
• label for this run (baseline vs optimized, etc.)
• any Scalene tuning flags (e.g. --cpu-percent-threshold)

Only invoke the helper once these are pinned down.

Profiling workflow

Run from the rocprof-compute worktree root (so src/rocprof-compute is auto-discovered):

bash <SKILL_DIR>/scripts/optimize-compute.sh --label <name> -- <subcommand> <args>

To forward Scalene tuning flags use --scalene-arg (repeatable):

bash <SKILL_DIR>/scripts/optimize-compute.sh \
    --label optimized \
    --scalene-arg --cpu-percent-threshold --scalene-arg 0.5 \
    -- analyze -p workloads/smoke

To point at a different worktree or a non-standard entry path use --source-dir / --entry. See REFERENCE.md.

The helper:

• Validates Scalene is installed (prompts to pip install scalene if not).
• Resolves src/rocprof-compute (or src/rocprof-compute.py) under --source-dir.
• Runs Scalene with --json --cpu-only defaults plus any --scalene-arg values.
• Saves output to .scalene-profiles/<label>.json and validates it.

Comparison workflow

1. Profile current code: --label baseline
2. User applies a change.
3. Profile again: --label optimized
4. Compare:

bash <SKILL_DIR>/scripts/optimize-compute.sh --compare baseline optimized

This validates and prints both JSON paths; it does not calculate deltas. Read both reports, then compare line-level CPU metrics:

• Delta in cpu_percent_python and cpu_percent_c per hotspot
• Delta in cpu_percent_system where system-call overhead is material
• Delta in elapsed_time_sec for the identical representative workload
• Report which hotspots improved, regressed, or are new

Interpretation rules

Classify each hotspot by its dominant metric:

• CPU-bound (Python): high cpu_percent_python — algorithmic improvements, vectorization, caching.
• CPU-bound (native): high cpu_percent_c — faster library alternative or reduced call frequency.
• System-heavy: high cpu_percent_system — excessive system calls, synchronization, or process/file overhead.
• I/O-bound: low CPU % relative to wall time — Scalene does not directly measure I/O wait, so report this only as a hypothesis requiring another profiler.

Report template

1. Executive Summary — one-line verdict: "rocprof-compute <subcommand> is [type]-bound, spending [X]% in [file:line]"
2. Top Hotspots — table: Rank | File:Line | Metric | % of Total | Type
3. Bottleneck Classification — group hotspots by type.
4. Recommendations — specific change per hotspot with file:line and expected impact.
5. Next Steps — re-profile command and remaining opportunities.

Additional resources

• REFERENCE.md — flag contract, Scalene forwarded flags, JSON schema, limitations.
• EXAMPLES.md — concrete usage scenarios including the grill-me fallback.
• writing style — normative prose rules and the pre-save self-check for every human-read artifact this skill produces.