Scanning and Autofixing Projects
Never start fixing before understanding. Sequence is always:
1. UNDERSTAND → read README/docs, architecture, requirements, configs
2. MAP → build file/dependency/service graph
3. SCAN → deep static+build+security scan, per language
4. REPORT → classified, evidence-backed findings (no guessing)
5. FIX → minimal, targeted fixes preserving architecture
6. VALIDATE → re-scan + tests + build, prove the fix worked
7. REPORT → final summary: errors found, fixed, tested, residual risk
If project explanation/requirements are missing, ask for or infer them from README/package manifests/docs before any scan step — do not skip to scanning.
Progress checklist to track and show the user:
- [ ] 1. Project Understanding (docs, architecture, requirements)
- [ ] 2. Structure & Dependency Mapping
- [ ] 3. Deep Scan (code, config, security, build, integration)
- [ ] 4. Error Classification & Report
- [ ] 5. AutoFix (prioritized, minimal diffs)
- [ ] 6. Validation (tests, build, regression)
- [ ] 7. Final Report & Backup Confirmation
1. Project Understanding
- Read README, docs, CONTRIBUTING, package.json/pyproject.toml/pom.xml/Cargo.toml/*.csproj, etc.
- Identify stated purpose, target users, and non-negotiable requirements.
- Map high-level architecture: monolith/microservices, frontend framework, backend framework, DB, external APIs.
- Do not scan or fix until this is done. If requirements are ambiguous, state assumptions explicitly in the report rather than guessing silently.
2. Structure & Dependency Mapping
- Walk the full directory tree — root to deepest subfolder. No skipping "irrelevant-looking" folders.
- Build a dependency graph: internal module imports, external packages (with versions), API endpoints, DB connections, env vars.
- Note language/framework per module (polyglot repos are common — tag each file).
3. Deep Scan (per applicable category)
| Category | What to check |
|---|---|
| Source code | syntax, logic errors, dead code, unreachable branches |
| Config/build | package.json, tsconfig, webpack/vite, Makefile, CMake, Dockerfile, CI YAML |
| Dependencies | version conflicts, deprecated/vulnerable packages, unused/missing deps |
| APIs/services | broken routes, mismatched contracts, missing error handling |
| Database | connection strings, migrations, query correctness, injection risk |
| Frontend↔Backend | CORS, auth token flow, API contract mismatches |
| Security | XSS, CSRF, SQLi, SSRF, insecure deserialization, secrets in code, broken auth |
| Compatibility | language/runtime version mismatches, OS-specific paths |
| Missing refs | broken imports, dangling file references, orphaned assets |
Use the right tool per language — e.g. eslint/tsc for JS/TS, pylint/mypy/bandit for Python, go vet/staticcheck for Go, clippy for Rust, cppcheck/compiler warnings for C/C++, dotnet build analyzers for C#, phpstan for PHP, rubocop for Ruby, swiftlint for Swift, ktlint/detekt for Kotlin, dart analyze for Dart, shellcheck for Bash, PSScriptAnalyzer for PowerShell, schema validators for JSON/YAML/XML. If a tool isn't available, do manual review and say so.
4. Error Classification & Report
Every finding must include:
[SEVERITY: Critical|High|Medium|Low] <Category> — <short title>
File: path/to/file.ext : line N
Cause: <why this is wrong>
Impact: <what breaks / risk>
Related to: <other findings it's linked to, if any>
Confidence: Confirmed | Likely | Needs verification
Never label a "Needs verification" item as a confirmed fact. Never invent errors to look thorough.
5. AutoFix
- Fix highest severity / highest confidence first.
- Make minimal, targeted diffs — do not rewrite whole files unless the file is beyond repair (state why).
- Preserve existing architecture, naming conventions, and public interfaces unless the fix explicitly requires a breaking change (flag this clearly and ask/confirm).
- Never delete files, functions, or config without clear necessity — explain and get confirmation first.
- Create a backup (git stash/branch or file copy) before any multi-file or destructive change.
- Apply defensive security practices: input/output validation, parameterized queries, proper auth checks, no secrets in code, CSRF tokens, CSP headers — only defensive, never offensive/exploit tooling.
6. Validation
- Re-scan all modified files.
- Run unit tests, integration tests, and build/compile.
- Confirm no new errors introduced (regression check).
- Only declare a fix "successful" when test/build output proves it — attach the evidence.
7. Final Report
Summarize: errors found (by severity count), errors fixed, errors deferred (and why), tests run and results, backups created, remaining risks/recommendations.
Example 1: Input: "Scan this Node.js + React + PostgreSQL app and fix what's broken." Output:
Understanding: Express REST API + React SPA + Postgres via pg pool. Auth via JWT.
Scan found:
[HIGH] Security — SQL built via string concatenation
File: backend/routes/users.js:42
Cause: user input interpolated directly into query string
Impact: SQL injection
Confidence: Confirmed
[MEDIUM] Integration — API base URL hardcoded to localhost
File: frontend/src/api/client.js:7
Impact: breaks in staging/prod
Confidence: Confirmed
Fixes applied:
- users.js:42 → converted to parameterized query ($1 placeholder)
- client.js:7 → read from process.env.API_BASE_URL with fallback
Validation: npm test → 42/42 passing. npm run build → success. No new lint errors.
Backup: git branch `backup/pre-autofix-2024` created before changes.
Example 2: Input: "Why does the build fail on this Android Kotlin project?" Output:
Scan: Gradle sync shows dependency conflict.
[CRITICAL] Build — version conflict
File: app/build.gradle.kts:18
Cause: kotlin-stdlib 1.9.0 required by module A, 1.8.0 pinned in root build.gradle.kts
Impact: compilation fails at :app:compileDebugKotlin
Confidence: Confirmed (from Gradle error log)
Fix: aligned root build.gradle.kts kotlin version to 1.9.0, ran `./gradlew clean build`.
Validation: BUILD SUCCESSFUL in 46s, 0 errors, 0 new warnings.
- Always state assumptions explicitly if requirements are unclear — never silently assume.
- Prefer minimal diffs over full rewrites; rewrite only when justified and stated.
- Treat every fix as needing proof (test/build output), not just a claim.
- Keep a running map of cross-file/cross-service relationships — many bugs are systemic, not isolated.
- When uncertain about tool availability for a language, fall back to manual static review and flag the limitation.
- Escalate (ask user) before any destructive, architecture-changing, or breaking-interface change.
- Do NOT scan before understanding project purpose/architecture — leads to irrelevant or harmful fixes.
- Do NOT report unverified guesses as confirmed bugs.
- Do NOT delete/rename files, functions, or configs without explicit necessity and confirmation.
- Do NOT apply large-scale rewrites when a targeted patch suffices.
- Do NOT claim a fix "works" without test/build evidence.
- Do NOT build offensive security tools/exploits — defensive hardening only.
- Do NOT ignore polyglot repo parts (e.g., skipping the Python scripts folder in a JS-majority repo).