# Code Sanity Check Sub-Agent — Design Notes & Decisions

Notes from the initial build (March 2026).

## Purpose

A lightweight, readonly pre-build advisor. Reviews an approach before the main agent starts building and flags anything that would cause real pain. Most of the time, responds "lgtm."

## Why a sub-agent and not a prompt rule?

Two categories of issues this catches:

1. **Package freshness** — the main agent reaches for packages from training data that may be outdated or superseded. A prompt rule can't fix this because the agent needs to actually search the web to check. The sub-agent has `searchGoogle` and `fetchUrl`.

2. **Architecture/organization** — the main agent is optimized for execution velocity, which means it won't pause to reconsider file structure or schema design. A prompt rule saying "think about organization" would slow it down on every task. The sub-agent is called at specific moments (before big builds) so the cost is targeted.

## "Checked-out staff eng" personality

The prompt deliberately cultivates low-energy, high-signal energy. The failure mode we're avoiding: a conscientious reviewer that flags everything and becomes a bottleneck. The prompt explicitly says:

- "lgtm" is a complete response, use it often
- Tech debt is normal and sometimes useful
- Let nits, style preferences, and minor code smells slide
- A few sentences is ideal, never an essay

This prevents scope creep from the reviewer itself.

## Tools

Reuses the main agent's tools via `executeTool` passthrough — no duplicate tool implementations. Seven readonly tools: readFile, grep, glob, searchGoogle, fetchUrl, askMindStudioSdk, bash.

Bash is included for complex read operations (git history, package.json inspection, analysis scripts) with prompt guidance to use it for reading only.

## Second-person prompt (not third-person)

Unlike the product vision agent which uses third-person RP framing to break out of RLHF constraints, this agent benefits from the model's base personality: pragmatic, responsible, grounded. The second-person "you are" framing keeps it in its natural problem-solving mode, which is exactly what a sanity checker should be.

## "We/us" language in team.md

The team.md description of this agent uses collaborative language ("a schema decision that'll paint us into a corner") rather than corrective language ("you're about to make a mistake"). This avoids triggering ego-defensiveness in the main agent and frames the sanity check as a teammate, not a gatekeeper.

## Spec context

Spec files are injected into the system prompt via `loadSpecContext()` from `subagents/common/context.ts`. The agent sees the project's domain, data model, and design direction without the main agent needing to summarize.