build-errors

name	build-errors
description	Use this skill when the build fails, compilation errors occur, or you see undefined references, linker errors, CUDA compilation issues, missing headers, or template instantiation failures. Analyzes errors, suggests fixes, and iteratively rebuilds until success.
argument-hint	[preset] [--max-iterations N]

Build Error Analyzer

Analyze build errors, suggest fixes, rebuild, and iterate until the build succeeds.

Reference: See .claude/skills/_shared/build-and-query.md for shared infrastructure (build modes, autonomy mode, change tracking).

Workflow

1. Parse arguments:

   • Build preset: release (default), relwithdebinfo, or clang-debug from $ARGUMENTS
   • Max iterations: default 5, configurable via --max-iterations N
   • Autonomy mode: interactive (default), autonomous, or semi-autonomous

2. Pre-build checks (run all before attempting the build):

   a. Submodule verification:

   git submodule status
   

   Check that all submodules (duckdb, cucascade, substrait, duckdb-python, vcpkg) are at expected commits. If any show a + prefix (out of sync), warn the user and offer:

   git submodule update --init --recursive
   

   b. Pixi environment: Verify running inside pixi. If not, remind user to run pixi shell first.

   c. sccache health:

   sccache --show-stats
   

   If it hangs or returns an error, restart:

   sccache --stop-server && sccache --start-server
   

3. Run the build:

   CMAKE_BUILD_PARALLEL_LEVEL=$(nproc) make <preset> 2>&1 | tail -200
   

4. If build succeeds: Report success and exit.

5. If build fails, analyze the error output:

   • Identify error type: undefined reference, syntax error, missing include, template error, CUDA kernel error, linker error
   • Read the relevant source files mentioned in the error
   • Understand surrounding code context
   • Cross-reference with known error patterns in error-patterns.md
   • Propose a fix with explanation

6. Apply the fix:

   • In interactive mode: show the fix and wait for user approval
   • In autonomous/semi-autonomous mode: apply immediately with git checkpoint

7. Rebuild and repeat until success or max iterations reached.

8. If max iterations reached: Present summary of all attempted fixes and remaining errors.

Error Analysis Strategy

When analyzing build errors:

1. Read the full error -- don't just look at the first line. Template errors and linker errors often have the root cause buried in later lines.
2. Check the error file -- read the source file at the error location to understand context.
3. Check recent changes -- git diff HEAD~1 to see if the error was introduced by a recent change.
4. Look for cascading errors -- fix the first error first; subsequent errors may be caused by it.
5. CUDA-specific: Check GPU architecture compatibility, CUDA standard version, and separable compilation settings.

Common Patterns

See error-patterns.md in this directory for a catalog of known Sirius build errors and their fixes.

Important Notes

• Most effective when errors are localized and fixes are 1-4 lines
• Always present each fix as a draft for review before applying (in interactive mode)
• Track which files were modified so changes can be reverted
• If a clean build is needed, suggest rm -rf build but confirm with user first (destructive)
• Reduce parallelism if OOM during build: CMAKE_BUILD_PARALLEL_LEVEL=4 make