docs: enhance 5 thin commands and add Rust API example

Commands enhanced with multi-language support, error recovery strategies,
and structured step-by-step workflows:
- build-fix: build system detection table, fix loop, recovery strategies
- test-coverage: framework detection, test generation rules, before/after report
- refactor-clean: safety tiers (SAFE/CAUTION/DANGER), multi-language tools
- update-codemaps: codemap format spec, diff detection, metadata headers
- update-docs: source-of-truth mapping, staleness checks, generated markers

New example:
- rust-api-CLAUDE.md: Axum + SQLx + PostgreSQL with layered architecture,
  thiserror patterns, compile-time SQL verification, integration test examples
This commit is contained in:
Affaan Mustafa
2026-02-12 15:38:27 -08:00
parent 4209421349
commit 733295b44e
6 changed files with 611 additions and 91 deletions

View File

@@ -1,29 +1,62 @@
# Build and Fix
Incrementally fix TypeScript and build errors:
Incrementally fix build and type errors with minimal, safe changes.
1. Run build: npm run build or pnpm build
## Step 1: Detect Build System
2. Parse error output:
- Group by file
- Sort by severity
Identify the project's build tool and run the build:
3. For each error:
- Show error context (5 lines before/after)
- Explain the issue
- Propose fix
- Apply fix
- Re-run build
- Verify error resolved
| Indicator | Build Command |
|-----------|---------------|
| `package.json` with `build` script | `npm run build` or `pnpm build` |
| `tsconfig.json` (TypeScript only) | `npx tsc --noEmit` |
| `Cargo.toml` | `cargo build 2>&1` |
| `pom.xml` | `mvn compile` |
| `build.gradle` | `./gradlew compileJava` |
| `go.mod` | `go build ./...` |
| `pyproject.toml` | `python -m py_compile` or `mypy .` |
4. Stop if:
- Fix introduces new errors
- Same error persists after 3 attempts
- User requests pause
## Step 2: Parse and Group Errors
5. Show summary:
- Errors fixed
- Errors remaining
- New errors introduced
1. Run the build command and capture stderr
2. Group errors by file path
3. Sort by dependency order (fix imports/types before logic errors)
4. Count total errors for progress tracking
Fix one error at a time for safety!
## Step 3: Fix Loop (One Error at a Time)
For each error:
1. **Read the file** — Use Read tool to see error context (10 lines around the error)
2. **Diagnose** — Identify root cause (missing import, wrong type, syntax error)
3. **Fix minimally** — Use Edit tool for the smallest change that resolves the error
4. **Re-run build** — Verify the error is gone and no new errors introduced
5. **Move to next** — Continue with remaining errors
## Step 4: Guardrails
Stop and ask the user if:
- A fix introduces **more errors than it resolves**
- The **same error persists after 3 attempts** (likely a deeper issue)
- The fix requires **architectural changes** (not just a build fix)
- Build errors stem from **missing dependencies** (need `npm install`, `cargo add`, etc.)
## Step 5: Summary
Show results:
- Errors fixed (with file paths)
- Errors remaining (if any)
- New errors introduced (should be zero)
- Suggested next steps for unresolved issues
## Recovery Strategies
| Situation | Action |
|-----------|--------|
| Missing module/import | Check if package is installed; suggest install command |
| Type mismatch | Read both type definitions; fix the narrower type |
| Circular dependency | Identify cycle with import graph; suggest extraction |
| Version conflict | Check `package.json` / `Cargo.toml` for version constraints |
| Build tool misconfiguration | Read config file; compare with working defaults |
Fix one error at a time for safety. Prefer minimal diffs over refactoring.