codebase-scan

Files (1)

• SKILL.md

SKILL.md (first lines)

<!-- 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.

From xoai/sage, MIT.

More from xoai/sage