codebase-recon

Files (6)

• SKILL.md
• checklist.md · references/
• smells.md · references/
• .gitkeep · scripts/
• find_entrypoints.py · scripts/
• recon.py · scripts/

SKILL.md (first lines)

# Codebase Recon

Produce a consistent, structured brief of an unfamiliar codebase before doing real work in it. Replaces ad-hoc `tree` + `grep` exploration with a repeatable checklist and a deterministic recon script.

## When to run

Trigger this skill when:
- Opening a repo for the first time in a session
- The user asks to "review", "understand", "explore", "get oriented in", or "audit" a codebase
- Before any refactor, migration, or architectural change
- Before answering a broad question like "how does X work in this project?"

Skip when the task is narrow and local (e.g., "fix this typo", "add a print statement here").

## Quick start

```bash
python scripts/recon.py <repo-path> --format brief
```

That single command produces the structured brief. Read it, then dive into specific files only as the task requires.

## The recon checklist

Always answer these questions, in order. The script answers most of them; fill gaps by reading files.

### 1. Project identity
- **Name + purpose** — from `README.md` first paragraph, `pyproject.toml` `[project]`, or `package.json`
- **Language + version** — `.python-version`, `pyproject.toml` `requires-python`, `package.json` `engines`
- **Framework / stack** — inferred from top dependencies

### 2. Layout
- Directory tree, depth ≤ 3, with annotations (what each top-level dir is for)
- Flag unusual structure: code in repo root, deeply nested packages, multiple unrelated projects in one repo

### 3. Entry points
- **CLI scripts** — `pyproject.toml` `[project.scripts]`, `package.json` `bin`, executables in `scripts/`
- **`__main__` blocks** — files with `if __name__ == "__main__"`
- **Web apps** — `FastAPI()`, `Flask(...)`, `app =` patterns
- **Libraries** — public surface from `__init__.py` `__all__` or top-level exports

### 4. Configuration surface
- Env vars referenced in code (`os.environ`, `os.getenv`, `process.env`)
- `.env.example` / `.env.template` keys
- Config files: `*.toml`, `*.yaml`, `*.ini`, `config/`
- Hardcoded paths or URLs (suspicious)

### 5. Dependencies
- Direct production deps with versions
- Direct dev deps
- Lockfile present? (`uv.lock`, `poetry.lock`, `package-lock.json`)
- Anything obviously outdated, deprecated, or pinned to an unsafe version

### 6. Tests
- Test directory location and framework (`pytest`, `unittest`, `vitest`, ...)
- Test file count vs source file count (rough ratio)
- CI config present? (`.github/workflows/`, `.gitlab-ci.yml`, ...)

### 7. Areas of interest
- Files >500 LOC (likely god objects or generated code)
- TODO/FIXME/XXX/HACK density
- `# type: ignore`, `@ts-ignore`, `eslint-disable` density
- Most-imported internal modules (the "hot" code)
- Recently modified files (where current work is happening) — `git log` if available

### 8. Risks / smells
- Missing `encoding="utf-8"` on file I/O (Python on Windows)
- Bare `except:` clauses
- `print` debugging left in non-CLI code
- Empty `__init__.py` where exports are expected
- Missing `py.typed` marker if package ships type hints

## Output format

Produce a single Markdown brief, ~80–150 lines. Use this skeleton:

```markdown
# <Project Name> — Codebase Brief

**Purpose:** <one sentence>
**Stack:** <language version> + <main framework(s)>
**Size:** <N> files, <M> LOC

## Layout
<annotated tree, depth ≤ 3>

## Entry points
- `<path>` — <what it does>

## Configuration
- Env vars: <list>
- Config files: <list>

## Dependencies
**Production:** <count>, notable: <list>
**Dev:** <count>, notable: <list>
**Lockfile:** <present | missing>

## Tests
<framework>, <count> test files, <ratio> vs source

## Areas of interest
- <file>: <reason>

## Risks
- <smell>: <count> occurrences (e.g., `bare except: 3 in agent/loop.py`)

## Suggested next reads
1. `<file>` — <why>
2. `<file>` — <why>
3. `<file>` — <why>
```

The "Suggested next reads" section is the payoff: 3 files that, if read, give the best ROI for understanding the project.

## Examples

### Example: small Python CLI repo

From michaellaret7/Agent-Harness-First-Principles, Apache-2.0.

More from michaellaret7/Agent-Harness-First-Principles