Scanning and Autofixing Projects
Never jump straight to fixing. Follow the mandatory sequence:
1. UNDERSTAND → read docs/README, map architecture, list dependencies
2. SCAN → deep-scan every file/folder, categorize by language/layer
3. REPORT → list findings with file:line, severity, cause, impact
4. CONFIRM → (if destructive fixes needed) flag for approval
5. FIX → minimal, targeted fixes preserving architecture
6. VALIDATE → re-run tests/builds, prove no regressions
7. SUMMARIZE → final report: errors found, fixes applied, test evidence
If a user asks to "fix the project" without context, start at step 1. Do not skip to step 5.
Progress checklist to track and surface to the user:
- [ ] 1. Project Understanding (docs, architecture, deps, data flow)
- [ ] 2. Deep Scan (structure, config, build, security, compatibility)
- [ ] 3. Error Report (categorized, with location & reasoning)
- [ ] 4. AutoFix Plan (what will change, what won't)
- [ ] 5. Apply Fixes (incremental, backed up)
- [ ] 6. Validation (tests, build, regression)
- [ ] 7. Final Report
Step 1 — Project Understanding
- Read README, CONTRIBUTING, docs, ADRs, inline architecture comments first.
- Map the stack: languages, frameworks, build tools, package managers (
package.json,requirements.txt,go.mod,Cargo.toml,*.csproj,pom.xml,Gemfile,pubspec.yaml, etc.). - Trace data flow: frontend ↔ backend ↔ APIs ↔ DB ↔ external services.
- Identify environment configs (
.env,appsettings.json,application.yml, CI/CD files). - Do not scan or fix until this mental model exists.
Step 2 — Deep Scan
Walk the entire tree (root → nested), skipping only node_modules/vendor/build artifacts unless specifically relevant. For each file category apply the matching tool/technique:
| Area | What to check | Typical tools |
|---|---|---|
| Source code | syntax, logic, dead code, type errors | language linters/compilers (eslint, tsc, pylint/mypy, clippy, go vet, javac, roslyn) |
| Config/Build | malformed JSON/YAML/XML, missing keys, mismatched build targets | schema validators, jsonlint, yamllint, build dry-run |
| Dependencies | version conflicts, missing/unused, vulnerable packages | npm audit, pip-audit, cargo audit, bundler-audit |
| APIs/Services | broken endpoints, contract mismatches, auth gaps | manual trace + static review |
| Database | connection strings, migration drift, query errors | migration diff, query lint |
| Frontend↔Backend | CORS, API shape mismatch, env var mismatch | cross-reference route definitions vs calls |
| Security | injection, XSS/CSRF, secrets in code, insecure auth | SAST-style manual review (defensive only) |
| Broken refs | missing imports/files, dead links, orphaned configs | reference graph scan |
| Compatibility | language/runtime version mismatches | version manifest cross-check |
Classify every finding immediately as: Critical / High / Medium / Low, with type (Syntax, Logic, Security, Config, Dependency, Integration, Build).
Step 3 — Error Report
Report format (never guess — mark uncertain items explicitly):
[SEVERITY] [TYPE] file/path.ext:line
Issue: <concise description>
Cause: <root cause, evidence-based>
Impact: <what breaks / risk>
Related to: <other finding IDs, if correlated>
Confidence: Confirmed | Likely | Needs Investigation
Step 4 — AutoFix Plan & Execution
- Fix the smallest unit that resolves the root cause — no rewrites unless the code is unsalvageable (state why if so).
- Preserve public APIs, function signatures, architecture, and file layout unless explicitly approved otherwise.
- Never delete files/functions/configs without clear necessity + user confirmation.
- Create a backup (copy or git stash/commit) before touching files tied to Critical/High fixes.
- Group fixes logically (per-module or per-bug) rather than one giant diff.
- Order of operations: Syntax/Build-blocking errors → Security → Logic → Config/Integration → Style.
Step 5 — Validation
After every fix batch:
- Re-run linters/compilers on changed files.
- Run unit + integration tests if present; if absent, note the gap explicitly.
- Run a full build.
- Run regression check on previously passing tests.
- Only report "fixed" when test/build evidence confirms it. Otherwise state "fix applied, unverified — tests unavailable."
Step 6 — Final Report
Always conclude with:
- Scanned: N files across [languages/stacks]
- Errors found: X (Critical: a, High: b, Medium: c, Low: d)
- Fixed: Y / Unresolved: Z (with reasons)
- Tests: pass/fail status + coverage of changed areas
- Architecture changes: none | list (with approval reference)
- Backups: location/commit hash
Example 1: Input: "Scan this Node/React app and fix build errors." Output:
[CRITICAL][Build] backend/server.js:12
Issue: require('./utils/logger') — file does not exist (renamed to logger.util.js)
Cause: refactor left stale import
Impact: server fails to start
Confidence: Confirmed
Fix applied: updated import path to './utils/logger.util.js'
Validation: `npm run build` → success; `npm test` → 24/24 passed
Example 2: Input: "Check for security issues in this PHP backend." Output:
[HIGH][Security] api/user.php:45
Issue: raw $_GET['id'] concatenated into SQL query
Cause: no parameterization
Impact: SQL injection risk
Confidence: Confirmed
Fix applied: switched to PDO prepared statement, preserved function signature
Validation: existing endpoint tests pass; added 1 regression test for injection payload
- Always state assumptions explicitly; never silently assume missing config values.
- Match tool to language (e.g.,
tsc --noEmitfor TS,go vet/go buildfor Go,cargo checkfor Rust). - Keep fixes reversible — prefer patches/diffs over full-file rewrites.
- Surface cross-cutting issues (e.g., one bad env var breaking three services) as a single correlated finding.
- When scanning frontend auth/API code, check for secrets, exposed endpoints, and missing input validation by default.
- If the project has no tests, say so plainly and recommend minimal smoke tests before claiming a fix works.
- Do not run AutoFix before presenting the error report — findings must be shown first.
- Do not invent errors to appear thorough; mark uncertain findings as "Needs Investigation," not fact.
- Do not perform large rewrites when a small patch suffices.
- Do not delete unused-looking files/functions without confirming they're truly unreferenced.
- Do not claim "all tests pass" without actually having run them.
- Do not change architecture, folder structure, or core workflows without explicit approval.
- Do not produce offensive security tools/exploits — security work is defensive only (detection + fix).