codebase-scan

<!-- sage-metadata cost-tier: haiku activation: auto tags: [analysis, context, conventions, reconnaissance] inputs: [codebase] outputs: [codebase-context] --> # Codebase Scan Understand the codebase BEFORE you plan or build anything. Agents that skip reconnaissance duplicate existing code, break established patterns, and introduce inconsistencies. **Core Principle:** Look before you leap. Five minutes of scanning prevents five hours of rework. ## When to Use At the START of any BUILD or ARCHITECT workflow, before elicitation or planning. Also when resuming a session in an unfamiliar part of the codebase. ## Process ### Step 1: Project Structure (30 seconds) Examine the top-level directory structure. Identify: - **Language/framework:** What stack is this? (package.json, requirements.txt, go.mod, etc.) - **Project layout:** Monorepo? Standard framework layout? Custom structure? - **Entry points:** Where does execution start? Where do tests live? ### Step 2: Relevant Area (60 seconds) Based on the task, identify the specific area of the codebase that will be affected. Examine: - **Existing code in the area:** What files exist? What do they do? - **Patterns used:** How are similar things implemented in this project? - **Naming conventions:** How are files, functions, classes, variables named? - **Test patterns:** What testing framework? How are tests structured? - **Import conventions:** How are dependencies organized? ### Step 3: Dependencies and Boundaries (30 seconds) Identify: - **What depends on the area being changed?** Breaking changes affect these. - **What does the area depend on?** These are the interfaces you must respect. - **Configuration:** Environment variables, config files, feature flags relevant to the change. ### Output: Codebase Context Produce a concise summary (NOT a full report — just what's relevant to the task): ``` CODEBASE CONTEXT: Stack: [language, framework, version] Area: [files/directories relevant to the task] Patterns: [established conventions this task must follow] Dependencies: [what will be affected by changes] Test setup: [framework, how tests are structured here] Concerns: [anything that could complicate the task] ``` This output feeds into elicitation (so you don't ask about things you already know) and planning (so the plan follows existing patterns). ## Rules **MUST (violation = missed context or wasted time):** - MUST NOT spend more than 2 minutes on scanning. This is reconnaissance, not a full audit. - MUST NOT skip this in BUILD/ARCHITECT mode. Even for "simple" changes, understanding context prevents breaking things. - MUST note existing patterns. The plan MUST follow them unless the spec explicitly documents a reason to deviate. **SHOULD (violation = incomplete picture):** - SHOULD read the `.sage/conventions.md` if it exists — it captures previously discovered patterns. - SHOULD focus on the relevant area + nearby examples, not every file in the project. **MAY (context-dependent):** - MAY skip for FIX mode if the bug location is already known and isolated. ## Failure Modes - **Empty project (greenfield):** Report that. No conventions to follow — the first implementation sets the pattern. Note this so elicitation and planning account for it. - **Massive monorepo:** Focus ONLY on the relevant area. Don't try to understand the whole thing. Use directory structure and imports to scope your scan. - **No tests exist:** Flag this as a risk. The plan should include setting up the test infrastructure as a prerequisite task.