Build Doctor

Build Doctor

Systematically fix build errors using parallel subagents with intelligent coordination, resource-aware execution, and iterative verification.

Supported Build Frameworks:

• TypeScript/JavaScript: tsconfig.json, ESLint, Prettier, tsc, npm/pnpm/yarn build
• .NET: Solution files (.sln), Project files (.csproj), dotnet build, dotnet format

---

Warning Handling

⚠️ ALL WARNINGS MUST BE FIXED - This is a ZERO-WARNING skill.

This skill enforces zero-warning builds to maintain code quality. "Not blocking build" is NOT an acceptable reason to leave warnings unfixed.

Framework-Specific Behavior:

• TypeScript/JavaScript: ALL warnings from ESLint, TypeScript compiler, and build tools must be fixed
• .NET: ALL warnings must be fixed, except for the two explicitly excluded codes below

Excluded .NET Warnings (ONLY these two):

• NU1902: NuGet package vulnerability warnings (often cannot be immediately fixed due to upstream dependencies)
• DX1000: DevExpress evaluation license warnings (requires commercial license purchase)

CRITICAL: If ANY other warning code appears (e.g., xUnit1026, CS0618, etc.), it MUST be fixed. Do NOT skip warnings just because they don't block the build.

If a warning cannot be fixed:

1. Document WHY it cannot be fixed (technical blocker, not just "doesn't block build")
2. Ask the user if this warning code should be added to exclusions
3. Do NOT mark the skill as successful until resolved

To exclude additional warning codes, modify the .NET adapter configuration.

---

When to Use

• ✅ Build failures with multiple errors across files
• ✅ Type/compilation errors blocking builds
• ✅ Lint/format errors preventing successful builds
• ✅ Build warnings that must be fixed
• ✅ After major refactoring or dependency updates
• ✅ Pre-commit cleanup needed
• ✅ Monorepos with multiple projects
• ✅ Projects with multiple build targets

---

Core Workflow

IMPORTANT: Use the TodoWrite tool throughout this workflow to track progress and ensure ALL steps are completed. Create todos at the start and update them as you progress through each phase.

Initial Task Planning

Before starting, create a comprehensive todo list:

Single Framework:

TodoWrite:
1. Detect build frameworks (pending)
2. Select framework(s) to fix (pending)
3. Run build discovery (pending)
4. Calculate parallelism (pending)
5. Fix files in parallel (pending)
6. Verify all files processed (pending)
7. Run final validation (pending)

Multiple Frameworks (use framework labels):

TodoWrite:
1. Detect build frameworks (pending)
2. Select framework(s) to fix (pending)
3. Run build discovery - ALL frameworks (pending)
4. Calculate parallelism (pending)
5. [.NET] Fix files in parallel (pending)
6. [TypeScript] Fix files in parallel (pending)
7. [.NET] Verify all files processed (pending)
8. [TypeScript] Verify all files processed (pending)
9. [.NET] Run final validation (pending)
10. [TypeScript] Run final validation (pending)

Mark each todo as in_progress when starting, and completed when finished. Add file-specific todos during the fixing phase.

1. Discovery & Analysis

Auto-detect build framework and run discovery:

node scripts/detect-build-environment.mjs  # Detect framework

Output: JSON array of detection objects (stderr shows summary, stdout contains JSON)

Each detection object has this structure:

{
  "framework": "typescript",
  "displayName": "frontend (typescript)",
  "buildType": "typescript",
  "projectRoot": "/absolute/path/to/project",
  "config": {
    "packageManager": "pnpm",
    ...
  }
}

IMPORTANT: Use these complete detection objects throughout the workflow - do NOT extract just the config property!

2. Framework Selection (if multiple detected)

If multiple build frameworks are detected, prompt the user to select which to fix.

Selection Strategy:

A. If 2-4 frameworks detected - Use AskUserQuestion with multiSelect: true:

Which build frameworks would you like the doctor to look at?

Options:

1. All frameworks (Recommended) - Fix all build projects sequentially
2. Individual framework entries with details (up to 3):
   • Context-specific display name:
     • .NET: Solution/project name (e.g., "MyApp.sln (dotnet)" or "Backend.csproj (dotnet)")
     • TypeScript: Relative folder path (e.g., "frontend (typescript)" or "packages/ui (typescript)")
   • Project root path
   • Package manager or solution file (if applicable)

B. If >4 frameworks detected - Show grouped, numbered list and ask for text response:

Display frameworks grouped by type:

Detected 6 build frameworks:

**TypeScript (3 projects):**
1. frontend (typescript) - pnpm
2. packages/ui (typescript) - pnpm
3. packages/utils (typescript) - pnpm

**.NET (3 projects):**
4. API.sln (dotnet)
5. Services.csproj (dotnet)
6. Tests.csproj (dotnet)

Which would you like the doctor to look at (or all)?

Store Selection: Keep the complete detection object(s) for the selected framework(s). Each object must include: framework, projectRoot, config, displayName, and buildType.

Processing Strategy:

• Single framework: Continue with that framework's detection object only
• Multiple frameworks: Use parallel-framework optimization (see below)

Parallel-Framework Optimization (multiple frameworks selected):

1. Run discovery (step 3) on ALL frameworks first
2. Check build status:
   • .NET builds successfully (even with warnings) → Can proceed with fixing
   • TypeScript/JavaScript builds successfully (even with warnings) → Can proceed with fixing
   • Framework fails to build → Must fix critical errors first before warnings
3. Start fixing frameworks in parallel:
   • If .NET builds + TypeScript builds → Fix both simultaneously
   • Create separate todo groups for each framework
   • Spawn subagents for both frameworks (count toward total MAX_PARALLEL)
4. Each framework follows its own fixing workflow:
   • .NET: Fix all files → One final build
   • TypeScript: Fix file → Verify → Next
5. Final validation runs for ALL frameworks

Example: 16GB RAM with MAX_PARALLEL=4, .NET + TypeScript both build successfully:

• Spawn 2 .NET fix subagents (working on different files)
• Spawn 2 TypeScript fix subagents (working on different files)
• Total: 4 concurrent subagents across both frameworks

3. Run Build Discovery

Run build and validation for the selected framework(s):

# Pass the FULL detection object from step 1 (not just config property!)
# The detection object includes: framework, displayName, buildType, projectRoot, config
node scripts/run-build.mjs '<detection-object-json>'

IMPORTANT: The parameter must be the complete detection object from step 1, which includes:

• framework: The framework identifier (e.g., "typescript", "dotnet")
• projectRoot: Absolute path to the project root
• config: Framework-specific configuration
• displayName, buildType: Additional metadata

IMPORTANT (Windows): When passing the detection object JSON, ensure all file paths use forward slashes (/), not backslashes (\). The detection script already normalizes paths, but if you reconstruct the JSON manually, use forward slashes to avoid JSON parse errors.

Example:

node scripts/run-build.mjs '{"framework":"typescript","displayName":"frontend (typescript)","buildType":"typescript","projectRoot":"C:/Projects/my-app","config":{"packageManager":"pnpm"}}'

Parse output to identify files with errors:

node scripts/parse-build-output.mjs table

Output: List of files sorted by error count (fix high-impact files first)

4. Calculate Parallelism

Determine optimal parallelism based on system resources and build framework:

# Auto-calculates based on:
# - TypeScript: 3GB per agent
# - .NET: 4GB per agent
node calculate-parallelism.mjs --mem-per-agent=<framework_value>

Uses calculate-parallelism skill for resource-aware execution (2-6 parallel agents).

5. Parallel File Fixing

CRITICAL: Process ALL files with errors, not just the first one!

TodoWrite Integration: When you receive the file list, create a todo for each file:

TodoWrite (add to existing list):
- Fix src/utils/helper.ts (12 errors) (pending)
- Fix src/components/Button.tsx (8 errors) (pending)
- Fix src/services/api.ts (5 errors) (pending)
... (one todo per file)

As you spawn subagents, mark files as in_progress. When verified, mark as completed.

Framework-Specific Workflow:

TypeScript/JavaScript: Fix → Verify → Next

For each file:

1. Spawn Fix Subagent → Fix the file
2. Verify Fix → Run node scripts/verify-fix.mjs {file} (checks individual file)
3. Evaluate → If success, mark completed and move to next file

.NET: Fix ALL Files → Verify Once

IMPORTANT: Do NOT run dotnet build or any verification during the fixing phase!

1. Generate complete file list from initial build errors

2. Create todos for ALL files (add to TodoWrite)

3. Spawn fix subagents for ALL files (respecting MAX_PARALLEL limit):

   Task: Fix all build errors in {filename}
   
   Context:
   - File: {path}
   - Framework: .NET
   - Issues: {compilation errors, warnings}
   
   Requirements:
   - Fix ALL issues in this file only
   - Do NOT modify other files
   - Do NOT run dotnet build to verify
   - Follow project standards (check CLAUDE.md)
   
   Success: All issues addressed in code
   

4. Mark todos as completed when subagent finishes (no verification yet)

5. Wait for ALL files to be fixed before verification

6. Proceed to Step 7 (Final Validation) for single build verification

Why this matters:

• ✅ TypeScript: Can verify individual files (tsc --noEmit file.ts)
• ❌ .NET: Cannot compile individual C# files - requires full project build
• ❌ Running dotnet build | grep for each file wastes time and resources

6. Progress Verification

Verify ALL files were processed:

node scripts/verify-progress.mjs initial-files.txt fixed-files.txt

If files remain, spawn subagents for remaining files.

For .NET projects: This step confirms all files were addressed. Do NOT run builds here - verification happens in step 7.

7. Final Validation

IMPORTANT: Run this as a single sequential command directly in the main agent. Do NOT spawn subagents or use the Task tool for this step.

Run complete validation after ALL files processed:

# Pass the same FULL detection object used in step 3
node scripts/run-final-build.mjs '<detection-object-json>'

Expected: All builds passing, zero type/lint errors.

Framework-Specific Behavior:

• TypeScript/JavaScript: This is a final comprehensive check (all files were already verified individually)
• .NET: This is the FIRST and ONLY build since fixing started - verifies ALL fixes together

.NET Workflow Note: The discovery/fixing phase builds Debug configuration only (where most warnings appear). Final validation then builds both Debug and Release to confirm all configurations are clean.

If warnings remain after fixes:

1. Identify warning codes: Parse which specific warning codes remain (e.g., xUnit1026, CS0618)
2. Check exclusion list: Only NU1902 and DX1000 are acceptable
3. If NOT in exclusion list:
   • Create new file-specific todos for files with these warnings
   • Spawn fix subagents to address them
   • Repeat (max 2 cycles for .NET, since verification is expensive)
4. If warnings CANNOT be fixed:
   • Document the technical blocker (NOT just "doesn't block build")
   • Ask user if this warning code should be excluded
   • Do NOT mark skill as successful

CRITICAL: "Not blocking build" is NOT a valid reason to accept warnings. ALL warnings must be fixed or explicitly excluded.

---

Resource Management

Subagent Lifecycle

• Do NOT use run_in_background: true when spawning fix subagents. Always use foreground Task calls so you know exactly when each agent completes.
• Wait for ALL subagents to complete before proceeding to the next phase (e.g., all fix agents must finish before running Progress Verification or Final Validation).
• Track active agents: When spawning parallel agents, send all Task calls in a single message. The response will contain all results, confirming they are complete.
• No orphaned agents: Never move to Final Validation while fix subagents are still running.

Key Constraints

• Never exceed MAX_PARALLEL concurrent subagents
• Queue remaining files if limit reached
• Monitor resources during execution:
  • Memory < 2GB: Pause new spawns
  • CPU load > 150%: Reduce MAX_PARALLEL by 1
  • I/O saturated: Stagger launches (10s delay)

Framework-Specific Resources

• TypeScript/JavaScript: 3GB per agent (tsc + ESLint + build tools)
• .NET: 4GB per agent (Roslyn compiler + NuGet + build)

---

Build Framework Detection

Auto-detection via detect-build-environment.mjs:

TypeScript/JavaScript:

• Detection: tsconfig.json or typescript in package.json
• Build Command: npm/pnpm/yarn run build
• Validation: prettier (optional), eslint --max-warnings=0, tsc --noEmit
• Patterns: **/*.ts, **/*.tsx, **/*.js, **/*.jsx
• Verification: Individual files (immediate)
• Warning Treatment: All warnings treated as errors

.NET:

• Detection: *.sln, *.slnx, or *.csproj files (prefer solution files)
• Build Command: dotnet restore + dotnet build --configuration Debug (during discovery only)
• Final Validation: Builds both Debug and Release configurations to verify all warnings are fixed
• Validation: dotnet format --verify-no-changes (only if detected in GitHub workflows)
• Patterns: **/*.cs, **/*.csproj, **/*.sln, **/*.slnx
• Verification: Deferred to final build - DO NOT run dotnet build during fixing phase
• Warning Treatment: ALL warnings treated as errors except NU1902 (NuGet vulnerabilities) and DX1000 (DevExpress license)
• Success means ZERO warnings except NU1902/DX1000 - "not blocking build" is NOT acceptable

CRITICAL .NET Rules:

1. After initial discovery, fix ALL files without building, then run ONE final build to verify
2. Fix ALL warnings (xUnit1026, CS0618, etc.) - only NU1902 and DX1000 are excluded
3. If warnings remain, they MUST be fixed or explicitly discussed with user

Key .NET Behaviors:

• If .sln or .slnx file exists, .csproj files are ignored (solution contains all projects)
• dotnet format is only run if detected in .github/workflows/**/*.yml files
• Individual file verification is not supported - all fixes verified in final build

---

Preview Mode

Before running the full skill, preview what would be detected and fixed:

# From skill directory
node preview.mjs [target-directory]

# Uses Git repository root if no directory specified
node preview.mjs

What it does:

1. Detects all build frameworks in the target directory
2. Runs build + validation - read-only analysis
3. Shows files that would be fixed (sorted by error count)

Perfect for:

• Understanding what the skill will do before running it
• Checking if your project is supported
• Seeing which files have the most issues

---

Tool Coordination

• TodoWrite: Track workflow progress and file-level fixes (REQUIRED - use throughout)
• Task: Spawn parallel fix subagents with subagent_type="general-purpose"
• Bash: Run detection, build, verification scripts
• Read/Grep/Glob: Gather context before fixing

TodoWrite Examples

Phase 1 - Initial Planning:

1. Detect build frameworks (in_progress)
2. Select framework(s) to fix (pending)
3. Run build discovery (pending)
4. Calculate parallelism (pending)
5. Fix files in parallel (pending)
6. Verify all files processed (pending)
7. Run final validation (pending)

Phase 2a - During Parallel Fixing (Single Framework):

1. Detect build frameworks (completed)
2. Select framework(s) to fix (completed)
3. Run build discovery (completed)
4. Calculate parallelism (completed)
5. Fix src/utils/helper.ts (12 errors) (in_progress)
6. Fix src/components/Button.tsx (8 errors) (in_progress)
7. Fix src/services/api.ts (5 errors) (pending)
8. Fix src/hooks/useAuth.ts (3 errors) (pending)
9. Verify all files processed (pending)
10. Run final validation (pending)

Phase 2b - During Parallel Fixing (Multiple Frameworks, MAX_PARALLEL=4):

1. Detect build frameworks (completed)
2. Select framework(s) to fix (completed)
3. Run build discovery - ALL frameworks (completed)
4. Calculate parallelism (completed)
5. [.NET] Fix Services/AuthService.cs (8 warnings) (in_progress)
6. [.NET] Fix Controllers/UserController.cs (5 warnings) (in_progress)
7. [TypeScript] Fix src/utils/helper.ts (12 errors) (in_progress)
8. [TypeScript] Fix src/components/Button.tsx (8 errors) (in_progress)
9. [.NET] Fix Models/User.cs (3 warnings) (pending)
10. [TypeScript] Fix src/services/api.ts (5 errors) (pending)
... (frameworks interleaved, 4 total subagents running)

Phase 3 - Near Completion:

1-8. [All file fixes] (completed)
9. Verify all files processed (in_progress)
10. Run final validation (pending)

---

Supporting Scripts

All scripts are in scripts/ directory and work cross-platform:

Core Scripts

detect-build-environment.mjs - Auto-detect framework and config

node scripts/detect-build-environment.mjs [directory]
# Outputs JSON array (to stdout) of detection objects
# Each object has: framework, displayName, buildType, projectRoot, config

run-build.mjs - Run build + validation for discovery

node scripts/run-build.mjs '<detection-object-json>'
# Saves to build-output.txt and validate-output.txt
# Parameter must be the FULL detection object from detect-build-environment.mjs

parse-build-output.mjs - Parse and group errors by file

node scripts/parse-build-output.mjs [table|json]
# Outputs files sorted by error count

verify-fix.mjs - Verify single file fix

node scripts/verify-fix.mjs <file> [--json]
# Exit 0: fixed, 1: errors remain

verify-progress.mjs - Check all files processed

node scripts/verify-progress.mjs initial.txt fixed.txt

run-final-build.mjs - Final validation after all fixes

node scripts/run-final-build.mjs '<detection-object-json>'
# Parameter must be the same FULL detection object used throughout the workflow
# Automatically cleans up temporary files (build-output.txt, validate-output.txt)

---

Subagent Requirements

Each fix subagent MUST:

1. Read Context: Source file, related files, project configuration
2. Apply Standards: Check CLAUDE.md, follow best practices
3. Fix Systematically: Build errors → Type errors → Lint errors
4. Verify Using verify-fix.mjs: Run node scripts/verify-fix.mjs {file} to validate the fix. Do NOT run eslint ., eslint src, tsc, or any whole-project commands. Always target the specific file being fixed. (.NET exception: skip verification during fixing phase)
5. Report Status: Issues fixed, issues remaining, blockers

---

Best Practices

DO

• ✅ Calculate MAX_PARALLEL based on resources
• ✅ Process ALL files in error list (not just first!)
• ✅ Fix files in priority order (most issues first)
• ✅ Spawn subagents in parallel (up to MAX_PARALLEL)
• ✅ Parallelize across frameworks if multiple frameworks build successfully
• ✅ Verify each file individually (TypeScript only)
• ✅ Run full validation at end

DON'T

• ❌ Stop after fixing ONE file (process ALL!)
• ❌ Exceed MAX_PARALLEL limit
• ❌ Skip file-level verification (TypeScript only - .NET verifies at end)
• ❌ Run whole-project commands in subagents (eslint ., eslint src, tsc) — always target the specific file
• ❌ Run dotnet build during .NET fixing phase (wait for final validation)
• ❌ Accept warnings just because they "don't block build" (fix ALL warnings!)
• ❌ Comment out code to "fix" build errors
• ❌ Modify multiple files per subagent

---

Error Handling

CRITICAL: Do NOT work around script failures.

If any script in this skill produces no output, fails, or returns unexpected results:

1. Report the problem to the user immediately
2. Do NOT invent workarounds like running alternative commands directly
3. Do NOT silently continue with different approaches

If a script fails, ask the user how to proceed before continuing.

Subagent and Runtime Errors:

• Subagent Timeout: Kill, log, retry once at end of queue
• Persistent Failures: After 3 attempts, mark for manual review
• Regression Detected: Spawn targeted fix subagents (max 2 cycles)
• Memory Exhaustion: Wait for current subagents, reduce MAX_PARALLEL

---

Success Criteria

Skill succeeds ONLY when all checks pass with ZERO warnings (except explicitly excluded codes).

TypeScript/JavaScript:

• ✅ tsc --noEmit passes with zero warnings (type checking)
• ✅ eslint --max-warnings=0 passes (linting, zero warnings)
• ✅ npm/pnpm/yarn run build passes with zero warnings (build)

.NET:

• ✅ dotnet build passes with zero warnings (except NU1902 and DX1000 only)
• ✅ dotnet format --verify-no-changes passes (only if used in GitHub workflows)
• ✅ Only acceptable warnings: NU1902 (NuGet vulnerabilities), DX1000 (DevExpress license)
• ❌ All other warnings MUST be fixed (xUnit1026, CS0618, etc.)

CRITICAL: If ANY warning code appears that is NOT in the exclusion list (NU1902, DX1000), the skill has NOT succeeded. Fix the warnings or document why they cannot be fixed and ask user for guidance.

---

Dependencies

• calculate-parallelism - Determines optimal parallelism based on system resources

---

Remember: Process ALL files with errors, not just the first one! Resource-aware execution ensures optimal performance without overwhelming the system.

Version: 1.0.0 License: MIT Author: Wayne Brantley