// Use when CI/CD pipeline fails. Provides systematic diagnosis for lint, type, test, and build failures across Python, TypeScript, Java, Rust, and n8n SDKs.
Use when adding a new method, function, or API endpoint to the SDK. Ensures consistent implementation across all SDKs (Python, TypeScript, Java, Rust CLI) with proper types, tests, and naming conventions.
Use when adding unit or integration tests. Provides test patterns, naming conventions, and fixtures for Python (pytest), TypeScript (vitest), Java (JUnit/Mockito), and Rust.
Load ONLY for Python code Use when writing, reviewing, or refactoring Python to ensure adherence to LBYL exception handling patterns, modern type syntax (list[str], str | None), pathlib operations, ABC-based interfaces, absolute imports, and explicit error boundaries at CLI level. Also provides production-tested code smell patterns from Dagster Labs for API design, parameter complexity, and code organization. Essential for maintaining erk's dignified Python standards.
Use when running integration tests against a real Metadata instance. Guides setup of environment variables (AI_SDK_HOST, AI_SDK_TOKEN) and runs tests that make actual API calls.
Use when reviewing or validating documentation. Checks for clarity, completeness, broken links, undefined terms, and ensures beginners can follow guides without prior knowledge of the SDK.
| name | debug-ci |
| description | Use when CI/CD pipeline fails. Provides systematic diagnosis for lint, type, test, and build failures across Python, TypeScript, Java, Rust, and n8n SDKs. |
Systematically diagnose and fix CI failures across all SDKs.
/debug-ci [workflow-url]
Check the CI summary to identify which SDK(s) failed:
| Category | Symptoms | Common Causes |
|---|---|---|
| Lint | "cargo fmt", "ruff", "eslint", "spotless" errors | Code not formatted, style violations |
| Type | "ty", "tsc", "clippy" errors | Type mismatches, missing types |
| Test | "pytest", "vitest", "mvn test", "cargo test" failures | Logic bugs, missing mocks, flaky tests |
| Build | Compilation errors | Syntax errors, missing dependencies |
| Integration | Timeout, 401, 404 errors | Credentials, network, API changes |
# Fix all formatting/linting
make format
# Then verify
make lint
cd python && ty check src tests
# Run specific SDK tests locally
cd <sdk> && <test-command>
# Run with verbose output
pytest -v --tb=long # Python
npm test -- --reporter=verbose # TypeScript
mvn test -X # Java
cargo test -- --nocapture # Rust
# Run the same checks CI runs
make lint
make test-all
| Error | Fix |
|---|---|
ruff check fails | cd python && ruff check --fix src tests |
ruff format fails | cd python && ruff format src tests |
| Import errors | Check __init__.py exports |
| pytest collection error | Check for syntax errors in test files |
| Error | Fix |
|---|---|
| ESLint errors | cd typescript && npm run lint -- --fix |
| Type errors | Fix type annotations, check models.ts |
| Module not found | npm ci to reinstall deps |
| Error | Fix |
|---|---|
| Spotless check fails | cd java && mvn spotless:apply |
| Compilation error | Check Java 11 compatibility |
| Test failure | Check mocks, Jackson annotations |
| Error | Fix |
|---|---|
cargo fmt fails | cd cli && cargo fmt |
| Clippy warnings | Fix the warning or add #[allow(...)] with justification |
| Test failure | Check assertions, mock responses |
| Error | Fix |
|---|---|
| ESLint errors | cd n8n-nodes-metadata && npm run lint:fix |
| Build error | Rebuild TypeScript SDK first: cd typescript && npm run build |
make lint && make test-all locally