# Synthesis Codebase Review > Enterprise-scale codebase audit methodology with tiered review system (Essential through Mission-Critical). Use when asked to: codebase review, code audit, code review, review codebase, architecture review, security audit, full code review, enterprise review, codebase health check. - **Type:** Skill - **Install:** `agentstack add skill-synthesisengineering-synthesis-skills-synthesis-codebase-review` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [synthesisengineering](https://agentstack.voostack.com/s/synthesisengineering) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** Apache-2.0 - **Upstream author:** [synthesisengineering](https://github.com/synthesisengineering) - **Source:** https://github.com/synthesisengineering/synthesis-skills/tree/main/synthesis-codebase-review ## Install ```sh agentstack add skill-synthesisengineering-synthesis-skills-synthesis-codebase-review ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Enterprise-Grade Codebase Review ## Purpose A comprehensive, practical codebase audit methodology for projects of any size. Not every project needs every check — the tiered system ensures you apply the right level of rigor. For the full detailed checklist, see `references/detailed-checklist.md` in this skill directory. --- ## How to Use This Skill ### Step 1: Assess Project Tier Complete the Project Complexity Assessment to determine which tier applies. ### Step 2: Review Applicable Sections Each section and many individual items are marked with tier indicators: - **Essential** (Tier 1) — Apply to ALL projects, even weekend hacks - **Standard** (Tier 2) — Apply to team projects and production apps - **Enterprise** (Tier 3) — Apply to large-scale, multi-team, or regulated systems - **Mission-Critical** (Tier 4) — Apply to financial, healthcare, infrastructure, or high-stakes systems ### Step 3: Skip What Doesn't Apply - Tier 1: focus only on Essential items (~50 checks) - Tier 2: include Essential and Standard items (~150 checks) - Tier 3: include Essential, Standard, and Enterprise items (~400 checks) - Tier 4: include everything (~900+ checks) --- ## Pre-Flight Checklist Complete these checks before starting any review. Skipping pre-flight has caused real wasted effort on real engagements. ### Branch Selection - Confirm which branch represents the current working state — do NOT assume `main` is current - Check the most recent commit date on the target branch. If `main` has not been updated in weeks and there is an active branch with many commits ahead, you are likely reviewing a stale snapshot - Ask whether the team uses git-flow, trunk-based, or another model. In git-flow, `develop` is often the correct review target ### Review Scope - Confirm which directories to exclude (vendor/, node_modules/, generated/, etc.) - Ask if a previous review has been conducted. If yes, obtain prior findings to enable delta review mode - Confirm expected output format (markdown, PDF, etc.) and audience (engineering team, leadership, both) --- ## Project Complexity Assessment Score each characteristic (0 = No, 1 = Yes): **Scale & Users:** >1 developer, >5 developers, >20 developers, >100 users, >10K users, >1M users **Business Criticality:** Production system, downtime costs money, downtime costs >$10K/hour, breach would make news, contractual SLAs **Data Sensitivity:** User accounts, PII, financial data, health data (HIPAA), regulated data (GDPR, SOX) **Architecture Complexity:** >1 service, >5 services, database exists, multiple data stores, third-party integrations, >5 integrations **Operational Requirements:** 99% uptime, 99.9% uptime, 99.99% uptime, dedicated ops/SRE team, 24/7 on-call | Score Range | Tier | Description | |-------------|------|-------------| | 0-4 | Tier 1 - Essential | Solo/hobby projects, prototypes, internal tools | | 5-10 | Tier 2 - Standard | Small team projects, production apps, startups | | 11-18 | Tier 3 - Enterprise | Large teams, regulated industries, enterprise customers | | 19+ | Tier 4 - Mission-Critical | Financial systems, healthcare, critical infrastructure | --- ## Minimum Viable Review (15-Minute Quick Check) Use this for a rapid health assessment. These are the absolute essentials that apply to ANY project. ### Security Essentials (5 minutes) - No secrets in code: run `git log -p | grep -i "password\|secret\|api_key\|token"` — should return nothing - Dependencies not ancient: check for critical vulnerabilities (`npm audit`, `pip-audit`, etc.) - HTTPS only for all external communication - Input validated before use - Auth exists if there are users ### Code Health (5 minutes) - It builds: clean build with no errors - Tests exist and pass - No obvious duplication (no copy-pasted files or massive repeated blocks) - Readable: a new developer could understand the main flow ### Operations Essentials (5 minutes) - README exists with instructions on how to run it - Documented or automated deployment process - Application produces logs - Errors logged or sent somewhere visible - Config externalized (no hardcoded environment-specific values) **Quick Score: ___ / 15.** If you score <12, address the gaps before proceeding. --- ## Review Categories The full detailed checklist is in `references/detailed-checklist.md`. Here is an overview of all 16 review categories: ### 1. Architecture & System Design Architectural foundation, API design and contracts, service communication, data architecture. Evaluate whether the chosen patterns are appropriate for scale and team size. ### 2. Secrets, Credentials & Sensitive Data Active secret scanning, secret type inventory, AI tool configuration files, comment-aware credential scanning, secret management, preventive controls. This section is CRITICAL for all tiers. ### 3. Code Duplication & Reusability Duplication analysis, shared code and libraries, abstraction quality. ### 4. Code Quality, Efficiency & Optimization Basic code quality, algorithmic efficiency, database efficiency, memory and resource efficiency, concurrency and thread safety. ### 5. Clean Code & Software Engineering Principles Naming and readability, function design, SOLID principles, error handling, defensive programming. ### 6. Code Readability & AI/Human Maintainability Human readability, documentation, AI and automation friendliness. ### 7. Testing Test existence, coverage, test types (unit, integration, API, E2E, performance, security), test quality (verify tests actually test behavior, not just imports). ### 8. Security Authentication, authorization, input validation, data protection, dependency security. ### 9. Multi-Tenancy (Tier 3+) Tenant isolation, configuration, lifecycle. ### 10. Identity & SSO (Tier 3+) SSO support, session management. ### 11. Scalability & Performance (Tier 2+) Horizontal scaling, auto-scaling, response times, caching, CDN. ### 12. Reliability (Tier 2+) Fault tolerance, data durability, backups, disaster recovery. ### 13. Observability (Tier 2+) Logging, monitoring, alerting, distributed tracing. ### 14. Deployment & Operations Build and deploy documentation and automation, deployment strategy, configuration management. ### 15. Licensing & Legal Dependency licenses, intellectual property, attribution. ### 16. Developer Experience Getting started documentation, development workflow, CI speed. ### Addenda - **Open Source Software Addendum** — License, community docs, security policy, versioning, distribution, contribution workflow, project health, testing, documentation - **Proprietary Software Addendum** — Trade secret protection, vendor management, customer data protection - **Industry-Specific Addenda** — Financial services, healthcare, e-commerce, government/public sector --- ## Output Format ### Key Principle: Strengths Before Findings All reports lead with strengths before findings. Demonstrating that you understand what the team built well makes critical findings land as constructive guidance rather than an attack. ### Tier 1-2: Simplified Report ```markdown ## Codebase Review Summary **Project**: [Name] **Tier**: [1-Essential / 2-Standard] **Date**: YYYY-MM-DD ### Quick Health Check: Pass / Issues / Fail ### Strengths 1. [What the codebase does well] 2. [Notable good practices] ### Key Findings | # | Finding | Severity | Location | Fix | |---|---------|----------|----------|-----| | 1 | [Description] | Critical/High/Medium/Low | `path:line` | [Action] | ### Recommended Actions 1. [Top priority action] 2. [Second priority] 3. [Third priority] ``` ### Tier 3-4: Full Report Include executive summary with overall score, per-category scores, top strengths, top critical findings, detailed findings with severity/location/evidence/recommendation/effort, and a phased action plan (immediate, short-term, medium-term). ### Delta Review Mode When a prior review exists, use delta mode. A standalone review says "here are your problems." A delta review says "here is your trajectory." The second is far more useful for engineering leadership. For each finding from the prior review, classify its current status: | Status | Meaning | |--------|---------| | **Fixed** | Finding fully resolved | | **Partially Fixed** | Improvement made but not complete | | **Still Present** | No change — deferred or not yet addressed | | **Worse** | Finding has regressed or expanded in scope | | **New** | Finding not present in prior review | ### Deliverable Organization Date-stamp review deliverables in folders: ``` reviews/ ├── 2025-01-15/ │ ├── review-summary.md │ ├── detailed-findings.md │ └── executive-report.pdf ├── 2025-04-15/ │ ├── delta-review.md ← compares against 2025-01-15 │ ├── detailed-findings.md │ └── executive-report.pdf ``` --- ## Relationship to Other Verification Skills This skill evaluates the **entire system**. Four companion skills cover narrower scopes: - **synthesis-implementation-integrity** — verifies a single change is genuinely complete (self-review, run after every implementation) - **synthesis-code-audit** — systematic 10-dimension quality scan of a diff (run after implementation, as input to preflight or pr-review) - **synthesis-preflight** — branch readiness gate that orchestrates tests, types, audit, and commit hygiene into a go/no-go verdict (run before creating a PR) - **synthesis-pr-review** — evaluates a change proposed for merge (peer review, run on every PR) Together these five skills form a verification chain: implementation-integrity catches change-level gaps, code-audit measures quality across 10 dimensions, preflight gates the branch before it becomes a PR, pr-review catches what earlier checks missed through judgment-based evaluation, and this skill catches systemic patterns that no single change reveals. --- ## Key Principles 1. **Tier-appropriate rigor.** Do not apply Tier 4 scrutiny to a weekend project. Do not skip Tier 1 basics for an enterprise system. 2. **Evidence-based findings.** Every finding must cite specific file paths and line numbers with concrete remediation steps. 3. **Practical over theoretical.** Every checklist item should catch real issues found in real codebases. 4. **AI-friendly wording.** Checklist items should be clear enough for AI assistants to evaluate programmatically. 5. **Strengths first.** Understanding what the team did well is as important as finding problems. ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [synthesisengineering](https://github.com/synthesisengineering) - **Source:** [synthesisengineering/synthesis-skills](https://github.com/synthesisengineering/synthesis-skills) - **License:** Apache-2.0 Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-synthesisengineering-synthesis-skills-synthesis-codebase-review - Seller: https://agentstack.voostack.com/s/synthesisengineering - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.