ai-codebase-review

Files (2)

• SKILL.md
• report-format.md · references/

SKILL.md (first lines)

You are a principal software engineer reviewing a production codebase. Produce a **surgical, evidence-based** report with only the most important findings — the few issues that materially affect scalability, reliability, correctness, latency, database load, queue/job throughput, external service pressure, operational cost, data consistency, and maintainability of critical paths.

This is distinct from `ai-code-review`, which reviews a single branch's diff. This skill scans the whole codebase (or a named flow/system within it).

## How to run the review

1. **Load the method and format.** Read `references/report-format.md` in full — it defines the inputs to focus on, the precision rules (evidence-backed findings, facts vs assumptions), the analysis method, the exact output structure, and the quality bar. Follow it exactly.
2. **Analyze the repository** currently available. If the user named a specific feature/flow/system, use it as the reference scenario; otherwise infer the most important production-critical flows and state your assumptions.
3. **Write the report** in the exact structure from the format file. Keep it to a maximum of 5 findings (prefer 2–4).
4. **Save it** to the vault and report the path.

## Output to Obsidian

All output goes to the user's Obsidian vault, written **directly on the local filesystem** (no MCP), grouped by project.

**Vault root:** `$OBSIDIAN_AI_VAULT` (defaults to `$HOME/Documents/obsidian/obsidian` if unset). Everything below lives under `<vault>/engineering/...`. Use the `Read`/`Write`/`Edit` tools (and `ls` via Bash) with the **absolute** path, e.g. `$OBSIDIAN_AI_VAULT/engineering/<project>/...`. Wikilink text inside notes stays vault-root-relative and unchanged (`[[engineering/...]]`) — never put the absolute path inside `[[...]]`.

**Commit to the vault repo (after writing).** Once this run's files are written (the note plus any `index.md` updates), delegate the vault commit to the `ai-commit` skill (see `ai-commit/SKILL.md`). Pass the commit message:

```
ai-codebase-review: <system>
```

`ai-commit` resolves the vault root from `$OBSIDIAN_AI_VAULT`, stages, commits, and pushes. Never run `git add` / `git commit` / `git push` directly here. If `ai-commit` reports nothing staged, no `origin`, or a push failure, report it briefly and finish — don't abort the skill. `ai-setup` configures the repo and its `origin`.

### Resolve the project base path

1. Run `git rev-parse --show-toplevel`; the basename is the project name.
2. If not a git repo, propose a name from `basename "$PWD"` (kebab-cased) and **confirm with the user**.
3. Base path: `engineering/<project>`.

### Write the file (one new file per review, never overwrite)

Every review creates a **new** file directly in `engineering/<project>/codebase-reviews/` — never a subfolder, and never overwriting a previous report.

Build the file name as `<timestamp>-<system>.md`:

1. `<timestamp>` = output of `date +%Y-%m-%d-%H%M%S` (e.g. `2026-05-29-143052`). The leading timestamp keeps the folder sorted chronologically.
2. `<system>` = a kebab-case slug for the feature/system reviewed (e.g. `dispatch-hot-path`), with every character outside `[A-Za-z0-9._-]` replaced by `-`.

Full path example: `<vault>/engineering/<project>/codebase-reviews/2026-05-29-143052-dispatch-hot-path.md`.

Write the file with the `Write` tool (it creates missing parent folders). The second-level timestamp makes each run a distinct file, so you never overwrite a previous report.

Below the report's H1, add a related-links blockquote: `> **Project:** [[engineering/<project>/index|<project>]]`.

### Maintain the index (keep the graph connected)

After saving, wire the note into the Obsidian graph with append-if-missing. Wikilinks use vault-root-relative paths + alias; use the filename without `.md` as both target and alias.

1. **Project index** — `engineering/<project>/index.md`: read it (if missing, create it with `# <project>` and a `↑ [[engineering/index|Engineering]]` back-link); add a bullet `- [[engineering/<project>/codebase-reviews/<timestamp>-<system>|<timestamp>-<system>]]` under a `## Codebase Reviews` heading with the `Edit` tool (each review is a new file, so always add one).
2. **Root index** — `engineering/index.md`: ensure a bullet `- [[engineering/<project>/index|<project>]]` exists under `## Projects` (create it if missing).

`ai-reindex` rebuilds all indexes deterministically; this step just keeps the graph live.

Report the final vault path when done.

From cristiano-pacheco/ai-tools, MIT.

More from cristiano-pacheco/ai-tools