Auditing and Completing Projects
Quick Start
When given a project folder:
- Scan the entire repo structure (don't skip files).
- Read config/architecture files first:
package.json,README,tsconfig.json, framework config, folder layout. - Build a mental model of the intended architecture before touching code.
- Report findings (errors, missing files, inconsistent patterns) BEFORE making changes.
- Fix/complete the project, preserving existing conventions, with zero warnings or errors left behind.
Workflow
Progress:
- Step 1: Deep scan — list all files, detect framework/language/stack
- Step 2: Read architecture signals — entry points, config files, folder naming conventions, existing patterns (naming, state management, styling approach)
- Step 3: Diagnose — identify broken imports, missing dependencies, incomplete features, dead code, type errors, lint warnings
- Step 4: Present a short report: what's broken, what's missing, what's suggested
- Step 5: Fix issues incrementally, respecting existing code style (don't rewrite working code unnecessarily)
- Step 6: Complete missing pieces (unfinished functions, missing routes, missing types, empty components) to match the established architecture
- Step 7: Final verification pass — rebuild/typecheck/lint mentally, ensure no warnings, no unused imports, no broken references
- Step 8: Summarize what was changed and why
Examples
Example 1:
Input: A React + TypeScript project with a components/ folder, one page importing a hook that doesn't exist yet, and ESLint warnings about unused variables.
Output: Report listing: missing useCart.ts hook (referenced in Cart.tsx), 3 unused imports in Header.tsx, inconsistent prop typing (some components use interface, others type). Then: hook implemented matching existing hook patterns (same return shape as useAuth.ts), unused imports removed, prop typing unified to match majority convention. Final note: "0 TypeScript errors, 0 ESLint warnings."
Example 2:
Input: Node/Express API missing error handling middleware and a few empty route files.
Output: Report: "routes/orders.js is empty, no centralized error handler, inconsistent response shapes." Then: implemented orders.js following the same controller/service pattern as users.js, added errorHandler.js matching existing middleware style, standardized all responses to { success, data, error } shape used elsewhere in the project.
Best Practices
- Always read before writing — never generate code blind to the existing architecture.
- Match existing conventions (naming, formatting, folder structure) rather than imposing new ones.
- Treat every warning as something to resolve, not ignore.
- When uncertain about intended behavior, infer from similar existing code in the project rather than guessing randomly.
- Keep a visible checklist/report so the user sees exactly what was wrong and what was fixed.
- Prefer minimal, targeted changes over full rewrites unless the existing code is fundamentally broken.
Common Pitfalls
- Don't rewrite the whole project from scratch when only parts are broken.
- Don't ignore the existing stack/framework and introduce a different one.
- Don't leave TODOs, console.logs, or commented-out code in the final delivery.
- Don't silently suppress warnings/errors (e.g.,
// @ts-ignore, disabling lint rules) instead of actually fixing them. - Don't skip the initial "read & understand" phase — jumping straight to edits causes architecture mismatches.
- Don't forget to re-verify the whole project after changes (one fix can break another file).