Troubleshooting & Repair
Relevant source files
The following files were used as context for generating this wiki page:
The Troubleshooting & Repair system in Everything Claude Code (ECC) is a multi-layered infrastructure designed to diagnose, resolve, and prevent system drift and compilation failures. It encompasses automated diagnostic scripts, specialized autonomous agents for different programming languages, and a structured workflow for restoring the codebase to a functional state.
The system's scope covers environment integrity checks, TypeScript/JavaScript build resolution, and specialized language support for C++ and Go. By utilizing automated recovery commands and surgical code fixes, the system ensures that development environments remain consistent and builds remain "green" with minimal architectural disruption.
Sources: AGENTS.md:1-15, agents/build-error-resolver.md:1-15, scripts/doctor.js
System Diagnostics and Environment Integrity
Environment integrity is managed primarily through the doctor.js script, which serves as a diagnostic tool for identifying installation drift and state inconsistencies. This script is part of the "Quality Gates" category within the project's harness audit and is essential for maintaining the integrity of the installation state.
The following flowchart illustrates the diagnostic and repair lifecycle:
The diagram shows the transition from initial diagnosis via the doctor script to automated remediation and final verification.
Sources: scripts/harness-audit.js:335-341, AGENTS.md:120-130
Key Diagnostic Components
| Component | Function | Scope |
|---|---|---|
scripts/doctor.js | Identifies installation drift and state integrity issues | Environment & Dependencies |
harness:audit | Executes deterministic text/JSON scorecards for harness baselines | Project Configuration |
npm audit | Identifies supply-chain vulnerabilities and signatures | Security & Dependencies |
Sources: scripts/harness-audit.js:150-160, scripts/observability-readiness.js:180-190
Specialized Build Resolution Agents
ECC employs specialized agents to handle build failures across different technology stacks. These agents are programmed to perform surgical fixes, prioritizing speed and build success over code refactoring.
TypeScript and General Build Resolver
The build-error-resolver is the primary agent for TypeScript inference issues, module resolution failures, and dependency conflicts. It follows a strict "Minimal Diff" policy, ensuring that changes do not alter the existing architecture.
The sequence diagram demonstrates the iterative process of collecting errors, applying minimal changes, and re-verifying the build.
Sources: agents/build-error-resolver.md:16-45
Multi-Language Support
The project provides dedicated resolvers for C++ and Go, each equipped with specific diagnostic commands and common fix patterns.
C++ Build Resolver (cpp-build-resolver)
Focuses on CMake configurations, linker errors, and template instantiations.
- Diagnostic Commands:
cmake --build build,clang-tidy,cppcheck. - Common Fixes: Handling "undefined reference," "multiple definition," and "incomplete type" errors.
Sources: agents/cpp-build-resolver.md:25-50
Go Build Resolver (go-build-resolver)
Specializes in Go compilation, go vet issues, and module dependency problems.
- Diagnostic Commands:
go build ./...,go vet ./...,go mod verify. - Common Fixes: Resolving "import cycle," "missing return," and "interface implementation" errors.
Sources: agents/go-build-resolver.md:25-50
Common Troubleshooting Patterns
The following table summarizes standard error categories and their respective remediation strategies across the ECC ecosystem:
| Error Category | Typical Cause | Remediation Action |
|---|---|---|
| Dependency Drift | Missing or mismatched packages | rm -rf node_modules package-lock.json && npm install |
| Type Inference | Implicit 'any' or possible 'undefined' | Add type annotations or optional chaining ?. |
| C++ Linker | Missing library or implementation | Add source file to CMakeLists.txt or implementation to .cpp |
| Go Modules | Checksum issues or local replaces | go clean -modcache && go mod download |
| State Mutation | Side effects from in-place mutation | Refactor to immutable patterns (create new objects) |
Sources: agents/build-error-resolver.md:50-70, agents/cpp-build-resolver.md:45-60, agents/go-build-resolver.md:45-60, rules/common/coding-style.md:5-15
Emergency Recovery and Caches
For cases where incremental fixes fail, the system defines a "Nuclear Option" to reset the environment state. This involves clearing build caches and re-initializing dependencies.
# Clear Next.js and build caches
rm -rf .next node_modules/.cache && npm run build
# Reset dependency tree
rm -rf node_modules package-lock.json && npm install
# Fix linting inconsistencies automatically
npx eslint . --fix
Sources: agents/build-error-resolver.md:85-95
The Troubleshooting & Repair module serves as the primary defense against technical debt and environmental decay. By combining rigorous diagnostic scripts like doctor.js with specialized language agents, ECC maintains a high standard of build reliability and environment consistency, ensuring that developers can resolve failures through surgical, non-destructive interventions.