agentleFS
ralfyishereralfyishere/rules-with-receipts/.claude/skills/code-reconnaissance/SKILL.md

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.

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
  1. Distinctive:

    Before implementing anything in a codebase not written in this session.

    line 14
  2. Distinctive:

    Before choosing where new code should live ("where does this belong?" is a recon question, not a taste question).

    line 15
  3. Distinctive:

    Before editing any function/module whose callers you can't name.

    line 16
  4. Distinctive:

    When the task says "do it the way the rest of the app does it" — explicitly or implicitly (it's always implicit).

    line 17
  5. Very specific:

    Don't let recon become stalling: the checklist below is minutes of reading, not a full codebase audit.

    line 23
  6. Distinctive:

    1 — Locate the territory: Search by the feature's vocabulary (user-facing terms, route names, domain nouns) to find where this concern …

    line 27
  7. Distinctive:

    6 — Establish the green baseline: Run the relevant tests (or build) *before* changing anything, and record the result.

    line 37
  8. Distinctive:

    No new helper was written that duplicates an existing one you could have found in two searches.

    line 45

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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-hygiene for 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-gate on existing-code tasks — recon findings are the plan's raw material.
  • live-state-truth is the underlying discipline (observe, don't assume); this skill is its directed, code-specific strategy.
  • change-control consumes the blast-radius map for risk classing; scope-fence keeps recon findings (adjacent mess) as flags, not detours.
  • debugging-playbook has 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.