Slang Investigate

Slang Investigate

For: Deep root cause investigation of Slang compiler bugs — from symptom to violated invariant.

Core Principle: Understand before fixing. The first plausible explanation is often wrong. Trace the full code path before proposing any fix.

Usage: /slang-investigate <bug-source> [--wsl]

Where <bug-source> is a GitHub issue, test file, CI log, or symptom description.

--wsl forces native WSL git/gh when running under WSL. Without it, WSL requires Windows-native git.exe/gh.exe and stops if either is missing.

Tool Selection

Before running any git or gh command, initialize selected tools:

ARGS="${ARGUMENTS:-}"
USE_WSL_TOOLS=false
if printf '%s\n' "$ARGS" | grep -Eq '(^|[[:space:]])--wsl([[:space:]]|$)'; then
  USE_WSL_TOOLS=true
  ARGS="$(printf '%s\n' "$ARGS" | sed -E 's/(^|[[:space:]])--wsl([[:space:]]|$)/ /; s/^[[:space:]]+//; s/[[:space:]]+$//')"
fi

is_wsl() {
  [ -n "${WSL_DISTRO_NAME:-}" ] || grep -qi microsoft /proc/version 2>/dev/null
}

choose_tool() {
  tool="$1"
  if is_wsl && [ "$USE_WSL_TOOLS" = false ]; then
    if command -v "${tool}.exe" >/dev/null 2>&1; then
      printf '%s.exe\n' "$tool"
      return 0
    fi
    printf 'Missing Windows-hosted tool: %s.exe\n' "$tool" >&2
    printf 'Install it on Windows or rerun with --wsl to use native WSL %s.\n' "$tool" >&2
    return 1
  fi

  if command -v "$tool" >/dev/null 2>&1; then
    printf '%s\n' "$tool"
    return 0
  fi
  printf 'Missing native tool: %s\n' "$tool" >&2
  return 1
}

GIT="$(choose_tool git)" || exit 1
GH="$(choose_tool gh)" || exit 1

Use $GIT and $GH for all subsequent git and gh commands.

For local compiler/test invocations, follow the slang-run-tests binary selection rule. Under WSL with the default Windows-hosted build, use slangc.exe and slang-test.exe; stop if either is missing instead of running a WSL-native binary from another build.

Step 1: Reproduce Locally

Build if needed (see slang-build skill), then confirm the bug:

# For ICE/crash
"$SLANGC" -target <target> test.slang

# For SPIRV validation
SLANG_RUN_SPIRV_VALIDATION=1 "$SLANGC" -target spirv test.slang

# For wrong codegen (compute test)
"$SLANG_TEST" tests/path/to/test.slang

If the bug does not reproduce, document why and stop.

Step 2: Classify the Error

Step 3: Locate the Crash Site

# Search for the error message text
rg "error message text" source/slang/ source/compiler-core/

# For SLANG_UNIMPLEMENTED_X crashes
rg "SLANG_UNIMPLEMENTED_X" source/slang/ --context 5

# For assertion failures
rg "assert.*message text" source/slang/

Step 4: Trace the Code Path

Use IR dumps to understand which pass is involved:

# Dump IR at every pass (split into per-pass files)
"$SLANGC" -dump-ir -target <target> -o /dev/null test.slang 2>&1 | \
  python extras/split-ir-dump.py

# Dump IR around a suspected pass
"$SLANGC" \
  -dump-ir-before <pass-name> \
  -dump-ir-after <pass-name> \
  -target <target> -o /dev/null test.slang > pass-dump.txt 2>&1

Always combine -dump-ir with -target and -o <file> to avoid mixing output.

Step 5: Understand the Design Context

Before proposing any fix, answer these questions:

Which compiler stage owns this behavior?

What invariant is violated?

• A type that should have been rejected reached a pass that cannot handle it
• A transformation produced invalid IR
• An instruction was not lowered before reaching emission
• A layout calculation produced incorrect results

Is this the right layer to fix?

Compiler philosophy: The Slang compiler is a pipeline of IR passes. Each pass has a clear purpose. Keep emission simple — do heavy lifting in IR passes.

Three levels of fix quality (prefer higher):

1. Best: Add or extend an IR pass — If the bug is caused by IR that wasn't transformed into the right shape, the fix belongs in an IR pass, not at the crash site. If no existing pass has the right theme, add a new one.

2. Acceptable: Annotate early, act later — When a fix needs information from an early compiler stage but must act in a later pass, annotate the IR with decorations in the early pass and read them in the later pass. Do not pattern-match arbitrary IR shapes in the later pass — that approach is fragile.

3. Last resort: Spot-fix at the symptom — Only patch the crash site or emitter when the problem is genuinely local (e.g., a missing case in a switch that follows an established pattern). If you find yourself adding complex conditional logic to an emitter or an existing pass whose theme doesn't match, step back — the fix probably belongs upstream.

Don't shoehorn fixes into existing passes: If the purpose of an existing pass doesn't align with what your fix needs to do, add a new pass rather than complicating an existing one with unrelated logic.

What related code paths exist?

• Does a similar construct work on other targets?
• Does a similar type/pattern work in the same context?
• Is there existing validation for a related case?

Could this be intentional?

Some behaviors that look like bugs may be deliberate (HLSL compatibility, performance trade-offs, known limitations documented in issues).

Step 6: Search for Related Issues and Prior Art

# Search for related issues
"$GH" issue list --repo shader-slang/slang --search "error message keywords" --limit 10

# Search for related fixes in git history
"$GIT" log --all --oneline --grep="error message keywords" -- source/slang/

# Check for TODOs near the crash site
rg "TODO|FIXME|HACK|WORKAROUND" source/slang/<file>.cpp --context 3

External References

For target-specific bugs, consult the relevant specification:

• SPIRV: Khronos SPIRV specification
• HLSL: Microsoft HLSL spec and DXC reference
• GLSL: Khronos GLSL specification
• Metal: Apple Metal Shading Language specification
• WGSL: W3C WGSL specification

Use mcp__deepwiki__ask_question with repoName "shader-slang/slang" for implementation-level questions.

Output

Write tmp/<issue-repository>-<bug-id>/investigation.md (or tmp/<bug-id>/ for local-only bugs):

# Root Cause Investigation

## Crash Site
- File: `source/slang/<file>.cpp`
- Function: `functionName()`
- Line: N
- Error: [exact error message or assertion]

## Code Path
[How the input reaches the crash site — which passes transform it, what decisions lead here]

## Violated Invariant
[What assumption is broken and why]

## Design Context
- Stage: [frontend / IR pass / emission]
- Right layer: [yes/no — if no, which layer should handle it]
- Related patterns: [similar constructs that work, and why they work]

## Related Issues
- #NNNN: [relationship]
- Prior fix in commit abc123: [what it did]

## Potential Fix Locations
1. [Location 1]: [brief description of what a fix here would look like]
2. [Location 2]: [brief description]
3. [Location 3]: [brief description]

## Recommended Approach
[Which fix location and why, considering the "prefer IR pass" principle]

Share investigation (if GitHub issue exists)

STOP and ask the user before posting. Show a preview of the comment.

If approved, post an [Agent]-prefixed summary of the investigation to the linked GitHub issue. This makes the root cause analysis visible to other contributors.