Skip to content
Skills Library
Programming · Review & audit

codebase-recon

/codebase-recon

Use when investigating a feature area, doing an RCA, or auditing code across multiple repos and perspectives. Runs structured searches through 8 lenses (security, auth, data flow, error handling, config/secrets, test coverage, API surface, cross-repo consistency) and produces a findings table with evidence.

Licence
MIT
Last repository change
06.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 06.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use when investigating a feature area, doing an RCA, or auditing code across multiple repos and perspectives. Runs structured searches through 8 lenses (security, auth, data flow, error handling, config/secrets, test coverage, API surface, cross-repo consistency) and produces a findings table with evidence.

Original author description

Use when investigating a feature area, doing an RCA, or auditing code across multiple repos and perspectives. Runs structured searches through 8 lenses (security, auth, data flow, error handling, config/secrets, test coverage, API surface, cross-repo consistency) and produces a findings table with evidence.

How it works

  1. Reference index
  2. When to Use
  3. Phase 0: Scope & Anchor (5 min)
  4. Phase 1: Cross-Repo Entry Point Search (10 min)
  5. Phase 2: Run All 8 Lenses (30-45 min)
  6. Phase 3: Findings Table (10 min)
  7. Phase 4: Synthesis & Report (15 min)
  8. Anti-Patterns (MUST AVOID)
  9. Failure Modes
Original SKILL.md headings · 132 lines, 898 words
SKILL.md preview
---
name: codebase-recon
disable-model-invocation: true
source: superpowers-plus
augment_menu: true
triggers: ["/sp-codebase-recon", "investigate this feature area", "how does this work across repos", "find all the places that", "do an RCA", "RCA investigation", "RCA on", "wide-band investigation", "codebase reconnaissance", "what's the blast radius", "find all ungated paths", "audit this area"]
description: Use when investigating a feature area, doing an RCA, or auditing code across multiple repos and perspectives. Runs structured searches through 8 lenses (security, auth, data flow, error handling, config/secrets, test coverage, API surface, cross-repo consistency) and produces a findings table with evidence.
summary: "Use when: investigating across repos/perspectives — RCA, security audit, feature area exploration."
coordination:
  group: engineering
  order: 1
  requires: []
  enables: [surgical-fix]
  escalates_to: [progressive-harsh-review]
  internal: false
composition:
  produces: [investigation-report]
  consumes: [user-intent]
  capabilities: [codebase-search, git-blame, cross-repo-analysis]
  priority: 60
  optional: false
  requires_all: false
---

# Codebase Recon — Wide-Band Investigation

> **Purpose:** Systematic multi-lens investigation of a feature area, producing structured findings with evidence.

**Announce at start:** "I'm using the **codebase-recon** skill to investigate this area across 8 lenses."

## Reference index

Load `reference.md` for full grep commands and checklists behind each lens (section: `Lens Search Patterns`).

---

## When to Use

**Use codebase-recon when:**
- Root cause is UNKNOWN — you can't write "the bug is X in file Y because Z"
- The defect might span multiple repos or call chains
- You need to map blast radius before changing shared code
- The request is "how does this work?" or "find all places that..." — exploration, not a fix
- Pre-fix investigation to scope a `surgical-fix` (result: feeds directly into surgical-fix Phase 0)

> **Handoff:** codebase-recon → produces investigation report → surgical-fix Phase 0 consumes it. Do NOT switch without a written scope statement.

---

## Phase 0: Scope & Anchor (5 min)

1. **Define the investigation target** — a feature name, bug report, ticket, or area of concern.
2. **Identify all repos that could be involved.** Ask the user if unclear.
3. **Create a coverage map** — a table tracking what has/hasn't been searched:

```markdown
| Repo | Searched | Files checked | Findings |
|------|----------|---------------|----------|
| repo-a | ☐ | 0 | 0 |
| repo-b | ☐ | 0 | 0 |
```

4. **Set the output document location** (wiki page, local file, or inline).

---

## Phase 1: Cross-Repo Entry Point Search (10 min)

Run these searches across ALL repos in scope. Record every hit.

```bash
# Primary search — adapt KEYWORD to feature area, EXTS to language
grep -rn 'KEYWORD' --include="*.ts" --include="*.js" --include="*.py" REPO_PATH | head -50
```

**Output:** A ranked list of files by relevance. Open the top 5-10 in the viewer to understand data flow.

---

## Phase 2: Run All 8 Lenses (30-45 min)

Run each lens IN ORDER. Each lens has specific search patterns and a checklist. Record ALL findings in the master table (Phase 3 format). Full search commands: see `reference.md`.

### Lens 1: Authentication & Authorization
Find every entry point (public HTTP handlers, exported API routes) and verify auth enforcement and account scoping.

### Lens 2: Security — Injection & Secrets
Find SQL injection risks (parameterized queries absent), hardcoded API keys/secrets, and debug dump endpoints.

### Lens 3: Feature Gating & Entitlement
Verify feature visibility is gated by plan/tier/flag, not just by whether data happens to exist.

### Lens 4: Data Flow — Where Does Data Come From and Go?
Trace data from database queries → server → client → outbound integrations (HTTP calls, webhooks, etc.).

### Lens 5: Error Handling & Fail Mode
Determine what happens when things go wrong: gate queries must fail CLOSED, errors must be logged (not swallowed), users see graceful degradation, not stack traces.

### Lens 6: Test Coverage
Find test files: `find REPO_PATH -name "*test*" -o -name "*spec*" | grep -i 'KEYWORD'`.

### Lens 7: Cross-Repo Consistency
Verify identical behavior across repos: same data references, same gating logic, no diverged copy-pastes.

### Lens 8: Git Blame & Change History
Understand WHO introduced WHAT and WHEN. **Run AFTER** Lenses 1-7 are complete — collect findings first, then git-blame all of them in one pass.

---

## Phase 3: Findings Table (10 min)

```markdown
| # | Lens | File | Lines | Finding | Severity | Evidence |
|---|------|------|-------|---------|----------|----------|
| 1 | Auth | handler.ts | L41 | public route with no auth check | Critical | grep output |
| 2 | Security | query.ts | L71 | unsanitized user input in SQL | Critical | view L69-73 |
```

**Severity scale:** Critical (unauthenticated access, injection, tenant exposure) · High (missing gate, wrong-tier data) · Medium (hardcoded config, debug endpoint, missing error handling) · Low (missing tests, inconsistent patterns)

---

## Phase 4: Synthesis & Report (15 min)

1. **Group findings by theme** (not by lens — a single finding may span lenses)
2. **Write Bottom Line** — 3-5 sentences summarizing what's broken and what to do
3. **Create fix priority list** — P0 (today), P1 (this sprint), P2 (tech debt)
4. **Update coverage map** — mark what's been searched
5. **List open questions** — things you couldn't determine from code alone

**Quality Gate:** Run `progressive-harsh-review`. Score <6: remediate. 6-8: PASS_WITH_FIXES. >8: PASS.

### Handoff to surgical-fix

```
"Investigation complete. Handing off finding #X to surgical-fix for implementation."
```
Include: file(s), line(s), what's wrong, proposed fix approach.

## Anti-Patterns (MUST AVOID)

1. **Don't fix things during recon.** Record findings, don't edit code.
2. **Don't go deep on one file.** Breadth first, depth second.
3. **Don't skip repos.** Gaps in coverage are where bugs hide.
4. **Don't trust comments.** Verify files exist; don't assume conventional layout.
5. **Don't claim external CLI calls are correct by syntax alone.** If scope includes wrapper scripts invoking `gh`, `aws`, `kubectl`, `npm`, etc., escalate to `external-cli-audit` — bash control flow tells you nothing about scope/identity/persistence-layer flags.

## Failure Modes

| Failure | Recovery |
|---------|----------|
| Only searched one repo | Return to Phase 0 coverage map; search all in-scope repos |
| Skipped a lens as "probably clean" | All lenses are mandatory; complete in order |
| Claimed external CLI wrappers are correct without checking CLI defaults | Run `external-cli-audit` for each external CLI invoked |
Files in this package (2)
  • reference.md 4 KB
  • skill.md 7 KB

Versions

RepositoryScoreLicence
This page · bordenet/superpowers-plus100MIT
aniruddha-adhikary/skills100Apache-2.0
voyager67/Agent-Workbench90MIT

Database snapshot: 13.11.2026 · package version ed9d592b4ec2 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100apex-recon
    Engineering lead reconnaissance — inventory the project before planning. Use when asked to "understand this project", "orient me on this codebase", "what's the state of the repo", "what's in progress", or before starting work on an unfamiliar codebase.
  • 90rca
    Root-cause analysis for code. Use when a defect shipped and was caught after the fact, a run came back BLOCKED or a deliverable failed validation, a bug recurs after a prior fix, or the user says 'rca this', 'root cause this', 'postmortem this', or 'why did this break'. Produces…
  • 100cross-repo-refactor
    Coordinate a multi-repo refactor by fanning out subagents per repo onto one feature branch. Use for cross-repo changes that touch multiple repositories.
  • 90schema-recon
    Audit existing API schemas across a codebase — find inconsistencies and coverage gaps. Use when asked to "audit our API schemas", "find schema inconsistencies", or "check spec coverage".
  • 100repo-recon
    Use this skill when you need to map an unfamiliar codebase before changing anything. Runs a systematic five-step recon pass — read the map, learn the commands, trace one flow end-to-end, note conventions then match them, and write it down — so you understand architecture,…
  • 100hk-rca
    Interactive Root Cause Analysis enforcer. Guides you through the 7-step RCA protocol: Reproduce, Locate, Hypothesis, Failing Test, Fix, Verify Live, Document. Use when debugging a bug, investigating a failure, or when something unexpected happened. This skill gates each step —…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.