Compileiq Debug

What it does

When your agent uses it

• Something is wrong: Search() hangs
• All evaluations return INVALIDSCORE
• Scores arent improving
• Every config returns the same number

Example prompts

• “compileiq hang”
• “socket timeout”
• “INVALIDSCORE”
• “/compileiq-debug”

Requirements

• Python 3
• Pre-approved tools (allowed-tools): Bash, Read

Workflow steps

3 steps, taken from the first numbered list in SKILL.md.

1. 1CIQ_SOCKET_TIMEOUT too low. Default is 20 seconds, which is fine for
2. 2Release-backed search-space fetch is slow or blocked. First call to
3. 3forkserver is unsupported on the host. Set CIQ_PROCESS_MODE=spawn.

What it can do on your machine

Read from SKILL.md and the folder at commit 743aca4. It shows what the files ask for, not the result of running them.

• Tool permissions

  Pre-approves these tools, so the agent can use them without asking each time:

  • Bash
  • Read

  From allowed-tools in the SKILL.md frontmatter.

• Runs code

  Ships 1 file in scripts/ (Python), which the agent can run.

  Shell commands in SKILL.md call:

  • python
  • gh
  • bash

  From the folder's file list and the shell code blocks in SKILL.md.

• Network

  No URLs in SKILL.md. Its commands use gh, which can reach the network depending on how they are called.

  From URLs in SKILL.md, links to its own repository left out.

• Credentials

  Names no API keys, tokens, secrets or passwords.

  From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Compileiq Debug loads about 2.9k tokens when it runs. Until then it costs about 128 tokens; SKILL.md has 1,038 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it

~128

When it runs · the whole SKILL.md, loaded when a task matches

~2.9k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

• NotePre-approves every shell command (allowed-tools: Bash)SKILL.md

  allowed-tools: Bash, Read

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.

SKILL.md

The full file from NVIDIA/CompileIQ at commit 743aca4, republished under its Apache-2.0 licence (© NVIDIA). 1,038 words, ~2,877 tokens.

name

compileiq-debug

description

Use when something is wrong: Search() hangs, all evaluations return INVALID_SCORE, scores aren't improving, every config returns the same number, ptxas errors fill the log, CV% is too high, or a winning ACF candidate needs NCU profiling to explain. Symptom-indexed table on top. Triggers on "compileiq hang", "socket timeout", "INVALID_SCORE", "not converging", "every score is the same", "TypeError fromhex", "ncu profile", "register spill", "ptxas error", "not in expected format", "high cv".

allowed-tools

Bash, Read

when_to_use

- User reports any unexpected behavior from Search() or its results. - User wants to NCU-profile a winning ACF to understand WHY it helps. - High CV% on…

license

Apache-2.0

metadata.version

1.0.0

metadata.author

NVIDIA CompileIQ

metadata.domain

compiler-optimization

paths

**/*.py, **/*.csv, **/*.ptx, **/*.acf

sample = tuner.sample(1)[0]
score = objective(sample)
print(type(score), score)

# OLD — DO NOT USE
def objective(config_blob):
    with open(tmp_path, "wb") as f:
        f.write(bytes.fromhex(config_blob))
    ...

from compileiq.utils.helpers import save_compiler_config

def objective(config: str):
    save_compiler_config(tmp_path, config)
    ...

result = objective(sample)
assert (
    (search_config.num_objectives == 1 and isinstance(result, (int, float)))
    or (search_config.num_objectives  > 1 and len(result) == search_config.num_objectives)
), f"shape mismatch: {result!r} vs num_objectives={search_config.num_objectives}"

export CIQ_KEEP_CACHE=1

import pandas as pd
df = pd.read_csv("results.csv")
df["score_numeric"] = pd.to_numeric(df["score_1"], errors="coerce")

gen_summary = df.groupby("generation").agg(
    n=("score_numeric", "size"),
    invalid=("score_numeric", lambda s: s.isna().sum() + (s > 1e10).sum()),
    best=("score_numeric", "min"),
)
print(gen_summary)

# Baseline (no ACF)
ncu --set full -o baseline -f --kernel-name my_kernel python bench.py

# ACF-applied — match the injection your objective uses
# Raw PTXAS:
ncu --set full -o opt -f --kernel-name my_kernel \
    bash -c 'PTXAS_OPTIONS="--apply-controls=best.acf" python bench.py'
# NVCC build:
nvcc -Xptxas --apply-controls=best.acf bench.cu -o bench && \
    ncu --set full -o opt -f --kernel-name my_kernel ./bench

# Diff
ncu --import baseline.ncu-rep --import opt.ncu-rep --csv --page raw > diff.csv

ptxas -v -arch=sm_100 --apply-controls best.acf kernel.ptx 2>&1 \
    | grep -E "registers|spill|stack"

python scripts/diagnose_csv.py --self-test

© NVIDIA, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 1 other file (scripts) in agent-skills/compileiq-debug of NVIDIA/CompileIQ.

• SKILL.md
• scripts/diagnose_csv.py

Open the folder on GitHubat commit 743aca4