Code Reconnaissance
Skill2 starsChanged 4 months agoMITView on GitHub
Understand the relevant code, conventions, and blast radius before writing or changing code in an existing project. Activate before implementing any feature, fix, or refactor in a codebase you didn't write this session - especially "add X to the app", "where should this go", "integrate with", or any multi-file change. Trigger signals: about to write new code without having looked for an existing implementation; about to edit a function without knowing its callers; unfamiliar project structure.
In this repository38 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- Adversarial VerifySkill
- Change ControlSkill
- Correction PropagationSkill
- Debugging PlaybookSkill
- Deep DecompositionSkill
- Delegation DisciplineSkill
- Disclosure Is Not A FixSkill
- Discovery LoopSkill
- Divergent IdeationSkill
- Effort CalibrationSkill
- Empirical ValidationSkill
- Error RecoverySkill
- Extract ApproachSkill
- Failure Mode AwarenessSkill
- ForesightSkill
- Frontier Workflow ModeSkill
- Human HandoffSkill
- Intent ClaritySkill
- Leverage FirstSkill
- Live State TruthSkill
- Memory HygieneSkill
- Open MandateSkill
- Output StructuringSkill
- Plan GateSkill
- Proactive RigorSkill
- Product ThinkingSkill
- Prompt EngineeringSkill
- Publish HygieneSkill
- Research MethodologySkill
- Ruthless EditorSkill
- Scope FenceSkill
- Security Pattern ReviewSkill
- Self-Improvement LoopSkill
- Session OrientationSkill
- Structured ReasoningSkill
- Verification DisciplineSkill
The file
We split this skill into the rules it gives an agent
8 rules. About 0 are common, 7 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈7
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 14
Before implementing anything in a codebase not written in this session.
- Distinctive: line 15
Before choosing where new code should live ("where does this belong?" is a recon question, not a taste question).
- Distinctive: line 16
Before editing any function/module whose callers you can't name.
- Distinctive: line 17
When the task says "do it the way the rest of the app does it" — explicitly or implicitly (it's always implicit).
- Very specific: line 23
Don't let recon become stalling: the checklist below is minutes of reading, not a full codebase audit.
- Distinctive: line 27
1 — Locate the territory: Search by the feature's vocabulary (user-facing terms, route names, domain nouns) to find where this concern …
- Distinctive: line 37
6 — Establish the green baseline: Run the relevant tests (or build) *before* changing anything, and record the result.
- Distinctive: line 45
No new helper was written that duplicates an existing one you could have found in two searches.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Code Reconnaissance
Purpose
Code written without reconnaissance is foreign tissue: it duplicates helpers that already exist, violates conventions the rest of the codebase follows, and breaks callers the author never saw. Fifteen minutes of directed reading turns a plausible change into a native one. This is the comprehension strategy that runs before any plan for changing existing code — live-state-truth says "read before you edit"; this skill says what to read and what to extract from it.
When to use this skill
- Before implementing anything in a codebase not written in this session.
- Before choosing where new code should live ("where does this belong?" is a recon question, not a taste question).
- Before editing any function/module whose callers you can't name.
- When the task says "do it the way the rest of the app does it" — explicitly or implicitly (it's always implicit).
When NOT to use this skill
- Greenfield code with no surrounding conventions to honor.
- Code you wrote or fully mapped earlier in this session and haven't been away from (see
memory-hygienefor when that expires). - Don't let recon become stalling: the checklist below is minutes of reading, not a full codebase audit. Depth follows
effort-calibration.
Operating procedure
1 — Locate the territory. Search by the feature's vocabulary (user-facing terms, route names, domain nouns) to find where this concern already lives. Entry points first: routes, CLI commands, main modules, exported APIs.
2 — Find an exemplar. Locate one existing implementation of the same kind of thing you're about to build (another endpoint, another validator, another migration). This is the single highest-value recon artifact — it answers naming, structure, error handling, and test placement in one read.
3 — Check for prior art before writing anything new. The helper you're about to write probably exists. Search for it by behavior, not just name (utils, shared libs, an existing dependency that does it). Writing a second formatDate is how codebases rot.
4 — Inventory the local conventions. From the exemplar and neighbors: naming style, error-handling pattern (exceptions vs. results), logging idiom, how dependencies are injected, where types/interfaces live, test file layout. You will match these even where you'd prefer otherwise (change-control: consistency beats taste).
5 — Map the blast radius. For anything you'll modify: who calls it, who imports it, what tests cover it. A grep for the symbol name is the minimum. Shared code with unknown callers is an R2+ change by default.
6 — Establish the green baseline. Run the relevant tests (or build) before changing anything, and record the result. Otherwise you cannot distinguish your breakage from pre-existing failure — a distinction you will need within the hour.
7 — Then plan. Feed the findings into plan-gate: the exemplar shapes the design, the blast radius shapes the risk section, prior art shrinks the work.
Quality bar
- You can name: the exemplar you're following, the callers of anything you'll touch, and the baseline test state — before the first edit.
- New code is indistinguishable in style from its neighbors.
- No new helper was written that duplicates an existing one you could have found in two searches.
Common failure modes
- Convention blindness: correct code in a foreign idiom — camelCase in a snake_case codebase, exceptions where everything else returns results. Reviewers reject it; future readers curse it.
- Duplicate implementation: rebuilding an existing util because searching felt slower than writing. It wasn't.
- Invisible callers: "improving" a shared function's behavior for your use case, breaking three others you never listed.
- Baseline skipped: discovering 12 failing tests after your change and burning an hour proving 9 were already failing.
- Recon as procrastination: mapping the whole architecture when the task needed one exemplar and one grep. Scope the recon to the change.
Example
Task: "Add a rate-limit config option to the API."
Recon (8 minutes): grep config → found config/schema.ts with a Zod schema — every option is declared there with a default and description (exemplar). Grep rateLimit → a middleware/rateLimit.ts already exists reading a hardcoded constant (prior art: the feature is half-built; the task is wiring, not building). Callers of the constant: one. Tests: config.test.ts has a table-driven pattern for each option; suite currently green (baseline). Plan shrinks from "build rate limiting" to "add schema field + thread it to the middleware + one table row in tests," in the house style.
Works with sibling skills
- Runs before
plan-gateon existing-code tasks — recon findings are the plan's raw material. live-state-truthis the underlying discipline (observe, don't assume); this skill is its directed, code-specific strategy.change-controlconsumes the blast-radius map for risk classing;scope-fencekeeps recon findings (adjacent mess) as flags, not detours.debugging-playbookhas its own investigation flow for defects; use that when something is broken, this when something is being built.
Provenance and maintenance
Added 2026-07 in the expansion pass: the core pack governed how to change code but not how to understand it first — the gap behind duplicate helpers, foreign-idiom diffs, and broken callers. No repo-specific claims. Re-verify by reviewing recent diffs in real projects: convention mismatches or duplicated utilities appearing in merged work mean steps 2–4 are being skipped.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

