rsc-universal 0.1.1

package/skills/code-review/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: code-review
+description: "Use when you have a concrete diff, branch, or GitHub PR to judge on its own merits and there is no rsc-SDD spec/plan/constitution chain to key off — the standalone, spec-less giving pass behind the executable /code-review. Triggers: 'review this PR before I merge', 'revisa este diff', 'revísame el PR', 'què està malament en aquest canvi', 'tear apart the contractor's branch', 'is this PR safe to merge', 'is this dependency bump safe', '/code-review --comment 1432', 'high-signal review of this change'. Scales coverage by effort (low/medium = fewer high-confidence findings; high/max = broader, may surface uncertain ones labelled [question]); read-only by default, posts comments only with --comment and edits only with --fix. NOT the SDD review gate keyed to 02-DOCS/wiki/sdd/ that also processes incoming comments and pushes back (that is review)."
+tags: [code-review, pr-review, quality, correctness]
+recommends: [review, secure-coding, verify]
+origin: risco
+---
+
+# Code review — standalone, spec-less diff judgment
+
+You are reviewing a concrete change — a `git diff`, a branch, a GitHub PR, a pasted patch — on its own merits. No rsc-SDD spec/plan/constitution chain is required and you should not pretend one exists. This is the doctrine behind the executable `/code-review` slash command: same evidence bar, written as a discipline you run by hand.
+
+> **The one-line disambiguator:** `review` needs `02-DOCS/wiki/sdd/` (spec + plan + constitution) and owns the *receiving* loop. `code-review` needs only the diff. If the user is mid-SDD and wants to process incoming comments, route to `../review/SKILL.md`. If they hand you a naked diff or an inbound third-party PR, this skill.
+
+**The north star is signal-to-noise.** Report only findings you would stake your name on. A clean diff is `APPROVE`, not a manufactured nit. High-false-positive review gets tuned out by humans in about two weeks; the bar to aim for is the logic-error review where under 1% of findings come back marked wrong. Padding does not make you look thorough — it trains the reader to ignore you.
+
+## Get the change and its intent first
+
+Three inputs, in this order: **the diff**, **its stated purpose**, and **the touched surface** (the files around the hunks, not just the hunks).
+
+```bash
+# A GitHub PR
+gh pr diff 1432
+gh pr view 1432 --json title,body,files,additions,deletions
+
+# A local branch against the trunk
+git diff main...HEAD
+git diff --stat main...HEAD   # see blast radius before reading
+
+# A pasted patch — read it as given
+```
+
+A review with no notion of intent is a review of vibes. If no purpose is stated, **infer it from the diff and say what you assumed** ("Assuming this is meant to add idempotency to the webhook handler…") so the reader can correct a wrong premise. Then read the *whole* changed file, not just the green/red lines — the structural failure of standalone review is judging a hunk without its context and shipping generic pattern-matched suggestions.
+
+## The pass order
+
+Run these in order. Passes 1–5 are correctness/safety and are blocking-eligible; pass 6 is cleanup and is usually `[should-fix]` or `[nit]`. **A clean pass is a reportable result** ("contracts: nothing changed shape, no finding"), not a pass you silently skip.
+
+| # | Pass | The question | Typical defects |
+|---|------|--------------|-----------------|
+| 1 | Intent fidelity | Does it do what it claims? | Wrong behaviour, missing case from the stated goal, scope creep |
+| 2 | Correctness & boundaries | Right on the edges? | Off-by-one, null/empty/unicode, overflow, timezone, concurrency, swallowed errors |
+| 3 | Contracts & data | Do callers/data still hold? | Broken API shape, migration without backfill, nullable made non-null, enum drift |
+| 4 | Security boundary | Untrusted input → dangerous sink? | Unsanitized input to query/shell/template, authz gap, secret in code/log |
+| 5 | Tests as evidence | Do the tests prove the change? | Tests assert nothing, test the mock, miss the new branch, were deleted to go green |
+| 6 | Reuse / simplification / efficiency | Could existing code do this? | Reimplemented helper, copy-paste divergence, N+1, needless allocation in a hot loop |
+
+Pass 4 is a **boundary** pass — trace untrusted input to its sink and flag the reachable ones. For a real STRIDE/OWASP threat model with exploitability ranking and vulnerable→fixed diffs, hand off to `../secure-coding/SKILL.md`.
+
+## Confidence floor and the false-positive skip-list
+
+**The 80% rule:** if you are not at least ~80% sure a finding is real, you have two moves — trace the code until you *are* sure, or downgrade it to `[question]`. Never ship a guess dressed as a defect.
+
+Skip these common false positives outright (or demote to `[question]`/`[nit]`):
+
+- **Guarded upstream** — the "missing" check happens in the caller you can see; trace before you flag.
+- **Framework-enforced** — the framework already does it (e.g. an ORM that parameterizes, a router that validates).
+- **Behind an off-everywhere flag** — real but unreachable in any deployed config → `[nit]`, not blocking.
+- **Test-only / generated code held to the prod bar** — don't demand prod-grade error handling in a fixture or a generated client.
+- **Style the linter owns** — quotes, import order, line length. If a tool enforces it, don't spend a finding on it.
+
+**No severity inflation.** Rank by `blast radius × reachability`, not by how clever the catch was. A typo in a log string is a nit even if it took effort to spot.
+
+## Severity and finding format
+
+- `[blocking]` — wrong/unsafe; merging causes a real defect. Must be fixed.
+- `[should-fix]` — a real problem with bounded blast radius; fix it or consciously accept it.
+- `[nit]` — minor; the reader may ignore it without consequence.
+- `[question]` — you suspect an issue but cannot prove reachability; asking, not asserting.
+
+Every finding carries **where / why / repro / fix**:
+
+```text
+[should-fix] api/orders.py:88 — duplicated total logic
+  where:  `subtotal = sum(i.price * i.qty for i in items)` re-implements
+          `cart.compute_subtotal()` (cart/totals.py:14), which also applies
+          per-item discounts this copy silently drops.
+  why:    discounted items now bill at full price on this path only;
+          the two implementations will drift on the next discount change.
+  repro:  order containing any item with `discount_pct > 0` → charged the
+          undiscounted amount; covered by no test.
+  fix:    call `cart.compute_subtotal(items)` instead of inlining the sum.
+```
+
+**Rule: no repro or stated mechanism → it is a `[question]`, not a blocker.** "This could overflow" with no path is a question; "n*1000 with n up to 3M exceeds int32 at orders.py:51" is a finding.
+
+## Verify before you flag
+
+Read the surrounding code, trace the *value*, confirm the path is reachable.
+
+- **Bad:** "Looks like SQL injection." (pattern-match)
+- **Good:** "`search()` interpolates `req.query.q` straight into `db.execute(\`… WHERE name='${q}'\`)` at search.ts:22; `q` is unvalidated user input → injection." (traced)
+
+If you cannot trace it to a concrete value and a reachable sink, you do not yet have a finding.
+
+## The verdict
+
+End every review with exactly one, plainly — no mushy middle:
+
+- **APPROVE** — no blockers, no should-fix. Point the user to `../ship/SKILL.md` to merge.
+- **APPROVE WITH NITS** — mergeable; nits listed but none gate the merge.
+- **CHANGES REQUESTED** — at least one `[blocking]`. List precisely what unblocks it, so the author knows when they are done.
+
+## Effort dial
+
+Mirror the slash command's effort level: **low/medium** → fewer, high-confidence findings (raise the confidence floor, focus on passes 1–4). **high/max** → broader coverage; you may surface uncertain findings, but they must be labelled `[question]`, never inflated into blockers. This is *coverage vs precision* and is distinct from the harness L0..L3 accompaniment dial, which sets how much you narrate, not how rigorous you are.
+
+## Emitting comments and applying fixes
+
+**Read-only by default.** You produce findings + a verdict and stop there. Two opt-in modes:
+
+- `--comment` → post the findings as an inline-anchored review on the PR.
+- `--fix` → apply the agreed findings to the working tree.
+
+```bash
+# Summary review (the verdict)
+gh pr review 1432 --request-changes -b "CHANGES REQUESTED — see inline. Blocker: orders.py:88 …"
+gh pr review 1432 --approve -b "APPROVE — correctness and contracts clean."
+```
+
+Inline line-anchored comments go through the GitHub REST API — see `references/pr-workflow.md` for the JSON shape, fork-PR handling, and large-diff strategy. If `--fix` puts you on the default branch, **branch first**; commit or push **only when the user asks**; git authorship is **Eric** (no Claude co-author or generated footer).
+
+## Anti-patterns → STOP
+
+| Rationalization | Reality |
+|---|---|
+| "It compiles and the tests pass, so it's correct." | Tests prove green, not correct. Pass 5 asks whether the tests actually exercise the new branch — green for the wrong reason is a finding. |
+| "I'll list everything I'd have done differently." | That is noise. Report defects and reuse wins you can defend; preference is not a finding. |
+| "This looks like a bug." | Looks-like is not a finding. Trace the value to a reachable sink, or file it `[question]`. |
+| "More findings = more thorough." | False positives get you tuned out in two weeks. Signal-to-noise is the metric; one real blocker beats ten nits. |
+| "No PR description, so I'll guess the intent silently." | State the intent you assumed. A wrong silent premise produces a confidently wrong review. |
+| "It's just a dependency bump, skim it." | Bumps carry supply-chain and transitive risk and behaviour changes. Check the changelog/lockfile diff, not just the version string. |
+| "Apply every nit to be safe." | Each unrequested edit is scope creep and a regression surface. With `--fix`, apply the agreed findings only. |
+
+## See Also
+
+- `../review/SKILL.md` — the rsc-SDD penultimate gate keyed to `02-DOCS/wiki/sdd/`, and the *receiving* loop (process comments, push back with proof).
+- `../secure-coding/SKILL.md` — deep STRIDE/OWASP threat model with vulnerable→fixed diffs; the depth pass 4 defers to.
+- `../verify/SKILL.md` — run lint/type/test/`verify.sh` and prove green (code-review judges whether green is correct).
+- `../debug/SKILL.md` — root-cause one confirmed failure (code-review surveys for latent ones).
+- `../analyze/SKILL.md` — consistency across spec/plan/tasks *before* code exists.
+- `../ship/SKILL.md` — PR/merge/close after approval; consumes this skill's verdict.
+- Stack idiom for the change under review: `../nextjs/SKILL.md`, `../fastapi/SKILL.md`, `../go/SKILL.md`, `../typescript/SKILL.md`, `../python/SKILL.md`.

package/skills/code-review/evals/README.md

@@ -0,0 +1,3 @@
+# code-review evals — how to run
+
+These cases are routing + capability checks for the `code-review` skill; there is no automated runner. Run them manually or via an orchestrator. For routing, read each `should_trigger` prompt and confirm the skill's description would fire on it (especially the spec-less diff/PR cases and the non-obvious dependency-bump one), then read each `should_not_trigger` prompt and confirm the description routes it to the named sibling — the load-bearing boundary is `review` vs `code-review` (review needs `02-DOCS/wiki/sdd/` and owns the receiving loop; code-review needs only the diff). For capability, hand an agent the scenario diff and score the response against the rubric: the planted-non-bug line is the real test — a review that flags the guarded-upstream SQL call as a blocker fails on signal-to-noise even if it caught the real bug. Also confirm it stayed read-only since no `--comment`/`--fix` was passed.

package/skills/code-review/evals/cases.yaml

@@ -0,0 +1,55 @@
+skill: code-review
+
+should_trigger:
+  - prompt: "review this PR before I merge it"
+    why: Core diff/PR review on its own merits with no SDD spec/plan chain — the spec-less giving pass.
+  - prompt: "revisa este diff, ¿está bien?"
+    why: Spanish phrasing for a standalone diff judgment with no project artifact chain.
+  - prompt: "què està malament en aquest canvi?"
+    why: Catalan phrasing — judge a concrete change for defects, no spec required.
+  - prompt: "is this dependency bump safe to merge?"
+    why: Non-obvious — a diff with almost no code still needs supply-chain/transitive review; this is the giving pass on a bump.
+  - prompt: "a contractor pushed a branch, tear it apart"
+    why: Inbound external change where you have only the diff + stated intent, no rsc-SDD artifacts to key off.
+  - prompt: "/code-review --comment 1432"
+    why: Running the executable discipline by hand, in comment-posting mode.
+  - prompt: "give me a high-signal review of this change, no nitpicks"
+    why: Names the signal-to-noise north star directly — exactly this skill's defining trait.
+
+should_not_trigger:
+  - prompt: "the reviewer left comments — do I have to make these changes?"
+    route_to: review
+    why: That is the receiving loop keyed to the SDD review gate, which review owns; code-review is giving-only.
+  - prompt: "run the lint, type-check and test gate and make it green"
+    route_to: verify
+    why: Running the gates to prove green is the verify phase; code-review judges whether green is correct.
+  - prompt: "threat-model this upload endpoint for OWASP issues with fixed diffs"
+    route_to: secure-coding
+    why: A deep STRIDE/OWASP exploitability pass with vulnerable→fixed diffs is secure-coding; code-review does only a boundary pass.
+  - prompt: "this test is flaky, find the root cause"
+    route_to: debug
+    why: Root-causing one confirmed failure is debug; code-review surveys a change for latent defects.
+  - prompt: "open the PR and merge it now that it's approved"
+    route_to: ship
+    why: PR/merge/close after approval is ship; code-review only produces the verdict ship consumes.
+  - prompt: "cross-check the spec, plan and tasks before we write any code"
+    route_to: analyze
+    why: Pre-code consistency across SDD artifacts is analyze; code-review reads the diff after code exists.
+
+capability:
+  - scenario: |
+      Review a PR diff for a checkout service that contains TWO things:
+      (a) a real correctness bug — the new code re-implements an existing
+      `cart.compute_subtotal()` helper inline as `sum(i.price * i.qty ...)`,
+      silently dropping the per-item discount the helper applies; and
+      (b) a planted non-bug — a call that interpolates a value into a SQL
+      string and *looks* like injection, but the value is a server-derived
+      enum already validated upstream in the same function (guarded upstream).
+      The user asked for a review and did NOT pass --comment or --fix.
+    must_include:
+      - Flags the duplicated/discount-dropping logic as [blocking] or [should-fix] with where/why/repro/fix.
+      - Does NOT flag the guarded SQL call as a blocker — either omits it or labels it [question] only after stating it traced the value to an upstream validation (signal-to-noise discipline).
+      - Emits exactly one verdict — APPROVE, APPROVE WITH NITS, or CHANGES REQUESTED.
+      - Ranks findings by blast radius × reachability with no severity inflation.
+      - Stays read-only — posts no PR comment and applies no fix, since neither --comment nor --fix was requested.
+      - States the assumed intent when reasoning about the change.

package/skills/code-review/references/pr-workflow.md

@@ -0,0 +1,67 @@
+# PR review workflow — `gh` mechanics
+
+Tooling depth for fetching a diff and posting review feedback end to end. Nothing here is posted or applied unless the user passed `--comment` or `--fix`. The body's pass order and confidence floor still govern *what* you report; this file is only *how*.
+
+## Fetch the diff
+
+```bash
+# By PR number in the current repo
+gh pr diff 1432
+gh pr view 1432 --json title,body,files,additions,deletions,baseRefName,headRefName
+
+# A PR in another repo (e.g. an OSS contribution you're reviewing)
+gh pr diff 1432 --repo owner/name
+
+# Fork PRs: the head branch lives on the contributor's fork. `gh pr diff`
+# resolves it for you — no manual remote add needed. To check out locally:
+gh pr checkout 1432
+
+# A local branch with no PR yet
+git diff main...HEAD          # everything since the branch diverged
+git diff --stat main...HEAD   # blast radius first
+```
+
+Read the whole touched file, not just the hunk. `gh pr diff` shows only changed lines; open the file when a hunk's correctness depends on surrounding code.
+
+## Post the verdict (summary review)
+
+```bash
+gh pr review 1432 --request-changes -b "CHANGES REQUESTED — 1 blocker, 2 should-fix. See inline."
+gh pr review 1432 --approve        -b "APPROVE — correctness, contracts and security boundary clean."
+gh pr review 1432 --comment        -b "APPROVE WITH NITS — non-blocking; see inline nits."
+```
+
+Pick exactly one of `--approve` / `--request-changes` / `--comment` to match the body's verdict. Note: you cannot `--approve` your own PR; on your own branch use `--comment`.
+
+## Post inline line-anchored comments
+
+Inline (line-anchored) comments beat PR-level prose for actionable feedback — they land on the exact line. The GitHub REST API takes one comment per call:
+
+```bash
+gh api repos/{owner}/{repo}/pulls/1432/comments \
+  -f body='[should-fix] re-implements `cart.compute_subtotal()` and drops per-item discounts. Call the helper instead.' \
+  -f commit_id="$(gh pr view 1432 --json headRefOid -q .headRefOid)" \
+  -f path='api/orders.py' \
+  -F line=88 \
+  -f side='RIGHT'
+```
+
+- `path` is the file path as it appears in the diff.
+- `line` is the line number in the file at `commit_id`.
+- `side`: `RIGHT` for the new version (additions/context), `LEFT` for the old.
+- Multi-line span: add `-F start_line=85 -f start_side='RIGHT'`.
+
+To batch several inline comments into one pending review with a single verdict, use `POST /pulls/{n}/reviews` with a `comments[]` array and an `event` of `REQUEST_CHANGES` / `APPROVE` / `COMMENT` — see the GitHub "Create a review for a pull request" API. Otherwise individual `pulls/{n}/comments` calls post immediately and unbatched.
+
+## Large-diff strategy
+
+When the diff is too big to hold in one pass:
+
+1. `git diff --stat` (or the `files` array from `gh pr view`) to rank files by churn.
+2. Review by file or by commit (`gh pr diff` per commit SHA), hot paths first — auth, money, data migrations, anything user-input-facing.
+3. Generated/vendored files (lockfiles, snapshots, `dist/`) get a structural skim for surprises, not a line-by-line read.
+4. Carry findings across files: a contract change in one file is only a finding if a caller in another file breaks — confirm the caller.
+
+## Read-only default
+
+The review itself touches nothing. Posting (`--comment`) and editing (`--fix`) are explicit opt-ins. With `--fix`, branch first if you are on the default branch, apply only the agreed findings, and commit/push only when the user asks. Git authorship is Eric — no Claude co-author or generated footer on any commit or PR body.

package/skills/codebase-onboarding/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: codebase-onboarding
+description: "Use when you land in an unfamiliar or inherited codebase and must get productive fast — map the entry points, the request/data flow, who owns the business logic, the hidden side effects (cron, webhooks, workers, listeners) and the hotspot files, before you touch anything. Triggers: 'I just cloned this repo and don't know where anything is', 'I inherited this project, map it before I change something', 'where does the business logic actually live', 'what happens behind the scenes when a request hits /checkout', 'which files are the dangerous ones nobody understands', 'acabo de heredar este repo y no sé por dónde empezar, mápamelo', 'mapea este codebase'. NOT a deep correctness/security audit of one module (that is analyze)."
+tags: [onboarding, codebase, code-mapping, legacy-code, architecture, reverse-engineering, hotspots]
+recommends: [analyze, debug, decision-records, harness, init, knowledge-ops]
+origin: risco
+---
+
+# Codebase onboarding — get oriented fast, leave a map
+
+You have just landed in a codebase you did not write: a fresh clone, an inherited project, an acquired repo, an abandoned side project someone handed you. The instinct is to start reading files top-to-bottom. Resist it. That is how a week disappears and you still cannot answer "where does X happen". This skill runs a disciplined **breadth-first reconnaissance pass** and produces one durable artifact: a map a teammate can trust and you can re-read tomorrow.
+
+The payoff is measured. Engineers using AI to onboard reach the same milestones roughly **2x faster** — productive in 1–2 weeks instead of 4–6 — and the biggest gains are exactly in *searching for code, decoding undocumented patterns, and tracing data flows* (super-productivity.com, accessed 2026-06-02). That is what the recon pass below targets, in order.
+
+## Lead with the deliverable
+
+Before you grep a single line, know the target: a single living file, `CODEBASE-MAP.md`, committed at the repo root. You work *backward* from its sections — every recon step fills one. Minimal schema:
+
+```markdown
+# CODEBASE-MAP.md — <repo name>
+
+## Stack          # languages, framework + versions, package manager, run scripts
+## Entry points   # main / server bootstrap / route registration / CLI commands
+## Request flow   # one real path traced transport -> business logic -> persistence
+## Module ownership   # who owns transport / business logic / persistence / UI
+## Hidden behavior    # cron, webhooks, queue workers, event listeners, env branches
+## Hotspots       # most-churned + most-complex files = highest risk
+## How to run     # the exact commands to boot it and hit one path locally
+```
+
+Why a file and not a chat answer: a map that lives only in the conversation dies when the session ends, and the next agent re-does the work. The artifact is the point. `verify.sh` checks these sections exist (structure, not content).
+
+## Two operating rules
+
+1. **Breadth before depth.** First pass maps *where things are*, not *how they work*. You are drawing the subway map, not reading every passenger's diary. Depth is `analyze`/`debug` work, on demand, later. — Reading everything is the failure mode onboarding exists to replace.
+2. **Hypothesis before answer.** Spend ~5 minutes forming your own guess ("auth probably lives in `src/middleware`"), then grep to confirm or kill it. — Verifying a hypothesis builds the mental model that makes you fast; a handed-to-you answer does not stick (martinfowler.com, Böckeler, accessed 2026-06-02).
+
+## The recon pass — ordered
+
+Run these in order. Each step writes one map section. Stop escalating the moment the section is answerable.
+
+**a. Orient — read the manifest, size the repo.**
+Read the manifest(s) and lockfile, not the README first: `package.json` / `pyproject.toml` / `go.mod` / `Gemfile` / `pom.xml` tell you the real stack, framework version and run scripts; the lockfile tells you what is actually installed. Then size it:
+
+```bash
+scc --by-file --sort lines .   # LOC, complexity, COCOMO estimate per file
+```
+
+`scc` (Sloc Cloc and Code, pure-Go, v3.7.0 Apr 2026) is the fast structural counter of record — materially faster than cloc/tokei and it reports per-file complexity, which you reuse for hotspots. Why manifest-first: the README describes intent (often stale); the manifest describes reality.
+
+**b. Find the entry points.**
+Where does execution start? Look for `main`, the server bootstrap, route registration, CLI command definitions. Let the framework's convention guide you (Next.js `app/`/`pages/`, Express `app.use`/router mounts, Django `urls.py`, FastAPI `@app`/`APIRouter`, Rails `routes.rb`, Spring `@RestController`). See `references/recon-playbook.md` for per-ecosystem patterns.
+
+**c. Trace one real request end-to-end.**
+Pick a single meaningful path (a login, a checkout, the main CLI command) and follow it: transport (route/handler) → business logic → persistence → response. One path traced beats ten skimmed. This is the spine of the map.
+
+**d. Map module ownership.**
+For the directories `scc` flagged as large, label each: transport, business logic, persistence, UI, shared/util. You are answering "if I need to change pricing, which folder do I open" — the question teammates actually ask.
+
+**e. Hunt hidden behavior.**
+The bugs live in what runs *without* a request. Grep for cron schedules, webhook receivers, queue/background workers, event listeners and env-driven branches (see the appendix). Why this step is non-negotiable: side effects are invisible in a top-down read and they are where inherited codebases bite.
+
+**f. Rank hotspots.**
+Git churn is the cheapest risk signal — no extra tooling, and high-churn files are a proxy for "lacks tests/abstraction":
+
+```bash
+git log --format=format: --name-only --since=12.month \
+  | grep -v '^$' | sort | uniq -c | sort -nr | head -50
+```
+
+The richer move is **churn × complexity**: the top-right quadrant (changes constantly *and* is hard to read) is your real danger zone (understandlegacycode.com Hotspots, accessed 2026-06-02). Escalate to that — or to a tree-sitter dependency graph — only when grep + churn is not enough; see the playbook.
+
+**g. Confirm hands-on.**
+Run the app, walk one end-user journey, send a real request, watch the logs. Reading alone leaves the map unverified; a single real request validates the whole trace in step c.
+
+## Scope the effort
+
+Match the pass to the repo. Do not stand up heavy tooling on a small project.
+
+| Repo shape | Map fully | Skip / defer | Escalate to a graph tool? |
+| --- | --- | --- | --- |
+| Tiny (<20 files) | a, b, c, g | churn, ownership table | No — grep is faster than setup |
+| Single-service app | all a–g | — | Only if ownership is unclear after grep |
+| Large monorepo | a, b, then per-package c–f | mapping every package at once | Yes — codegraph PageRank to find the load-bearing packages |
+| Polyglot | a, b, c per language boundary | one unified flow diagram | Yes, if cross-language calls obscure the flow |
+
+## Command appendix
+
+Language-tagged, copy-ready. Per-ecosystem depth lives in `references/recon-playbook.md`.
+
+```bash
+# Size + complexity (reuse the complexity column for hotspots)
+scc --by-file --sort complexity .
+
+# Route registration (adjust per framework)
+rg -n "app\.(get|post|put|delete|use)\(|@app\.(get|post)|APIRouter|router\.(get|post)" --type-add 'web:*.{js,ts,py}' -tweb
+
+# Cron / scheduled jobs
+rg -n "cron|schedule|@scheduled|setInterval|celery\.beat|node-cron" -i
+
+# Webhook receivers
+rg -n "webhook|/hooks/|stripe.*signature|x-hub-signature" -i
+
+# Queue / background workers
+rg -n "queue|worker|bull|sidekiq|celery|sqs|rabbitmq|kafka|@task" -i
+
+# Env-driven branches (hidden config-conditional behavior)
+rg -n "process\.env\.|os\.environ|ENV\[|getenv" 
+
+# Hotspots: churn over the last year
+git log --format=format: --name-only --since=12.month | grep -v '^$' | sort | uniq -c | sort -nr | head -50
+```
+
+## Writing & maintaining the map
+
+- **Commit it.** `CODEBASE-MAP.md` at the repo root, in version control. A map outside the repo rots silently.
+- **Keep it living.** When the recon reveals you guessed wrong, fix the line — the map is the record of what is *true now*, not your first impression.
+- **Link out, do not duplicate.** The map says *what is*. For *why a choice was made*, write an ADR (`../decision-records/SKILL.md`). To scaffold project tooling and a wiki, that is `../harness/SKILL.md`. To write the agent-memory `CLAUDE.md`, that is `../init/SKILL.md` — onboarding is the broader recon that feeds it. For generic note/wiki capture, `../knowledge-ops/SKILL.md`.
+- **Hand off to depth tools.** Once the map exists, a deep correctness/security read of one module is `../analyze/SKILL.md`; chasing a specific failure through the system is `../debug/SKILL.md`. Onboarding builds the map you debug *with*.
+
+## Anti-patterns
+
+| Bad | Why it bites | Good |
+| --- | --- | --- |
+| Read every file top-to-bottom | Burns the week; you finish exhausted and still can't trace one request | Breadth-first: map locations first, depth on demand |
+| Trust the README over the code | READMEs drift; the manifest and the routes are the truth | Read manifest + lockfile first, confirm by grep |
+| Map everything at full depth | Analysis paralysis on a monorepo; you map dead modules | Trace one real flow end-to-end; expand only where needed |
+| Skip the run step | An unverified map is a hypothesis, not a map | Boot it, hit one path, watch logs before you trust the trace |
+| Map lives only in chat | Dies with the session; next agent redoes it | Write & commit `CODEBASE-MAP.md` |
+| Guess instead of grep | Confident-wrong is worse than slow-right | Form the hypothesis, then `rg` to confirm or kill it |
+| Stand up a tree-sitter MCP graph on a 5-file repo | Setup costs more than the whole recon | Reserve graph tools for large monorepos; grep + churn first |
+
+See `references/recon-playbook.md` for per-ecosystem entry points and side-effect patterns, the churn×complexity recipe (code-maat), and when a tree-sitter graph (codegraph PageRank, FileScopeMCP) earns its setup cost.

package/skills/codebase-onboarding/evals/README.md

@@ -0,0 +1,3 @@
+# Evals — codebase-onboarding
+
+These cases are split into routing checks and a capability rubric, run through the repo's standard skill-eval harness. The `should_trigger` and `should_not_trigger` prompts validate the description's routing: each `should_trigger` prompt must select this skill (including the non-obvious hotspot/hidden-behavior and Spanish phrasings), and each `should_not_trigger` prompt must route to the named sibling (`analyze`, `harness`, `decision-records`, `debug`, `init`) instead — that is how we confirm the boundary lines hold. The `capability` block is graded by a model against the `must_include` rubric, not asserted by a script: given an unfamiliar Node/Express + Postgres repo, the run is judged on whether it produced a breadth-first map (stack, entry points, one traced flow, ownership, a hidden side effect, churn hotspots, run instructions) written to `CODEBASE-MAP.md` — and crucially did *not* read the repo line-by-line. Run the whole file with the harness; there is no separate setup.

package/skills/codebase-onboarding/evals/cases.yaml

@@ -0,0 +1,69 @@
+skill: codebase-onboarding
+
+# Prompts that MUST load `codebase-onboarding`. This is the breadth-first
+# reconnaissance skill: it maps an unfamiliar/inherited codebase (entry points,
+# request/data flow, module ownership, hidden side effects, hotspots) into a
+# committed CODEBASE-MAP.md. Several prompts deliberately avoid "onboarding" to
+# test that the intent — orientation in code you didn't write — is the trigger.
+should_trigger:
+  - prompt: "I just cloned this repo and have no idea where anything is — help me get oriented."
+    why: "Canonical cold-start: fresh clone, no mental model, needs breadth-first orientation — the core job."
+
+  - prompt: "I inherited this project from a dev who left. Map it out before I change anything."
+    why: "Inherited/legacy framing with the explicit 'map before touching' instinct this skill enforces."
+
+  - prompt: "Where does the business logic actually live in this codebase, versus the transport layer?"
+    why: "Module-ownership question (recon step d) phrased without naming the skill."
+
+  - prompt: "What happens behind the scenes when a request hits /checkout — any cron jobs or webhooks involved?"
+    why: "Non-obvious hidden-side-effects framing (step e) plus a request trace (step c); side effects are invisible in a top-down read."
+
+  - prompt: "acabo de heredar este repo y no sé por dónde empezar, mápamelo."
+    why: "Spanish, inherited codebase, explicit 'map it' — same cold-start intent in another language."
+
+  - prompt: "Which files are the dangerous ones here — the stuff that changes constantly and nobody understands?"
+    why: "Hotspot/churn×complexity framing (step f); 'changes constantly' is the churn signal, 'nobody understands' is complexity."
+
+  - prompt: "Give me a high-level architecture map of this monorepo so I can find the load-bearing packages."
+    why: "Large-monorepo recon that escalates to a structural-importance graph — the decision-table large-repo row."
+
+# NEAR-MISS prompts that must NOT load `codebase-onboarding`. Each routes to the
+# genuinely correct sibling. The recurring trap: anything that audits depth,
+# scaffolds tooling, records a decision, or chases a specific failure rather than
+# building breadth-first orientation.
+should_not_trigger:
+  - prompt: "Review this PR diff for correctness bugs before we merge."
+    route_to: "analyze"
+    why: "Depth audit of a specific change, not breadth orientation of an unfamiliar repo."
+
+  - prompt: "Set up 01-TOOLS and 02-DOCS and generate the root CLAUDE.md for this workspace."
+    route_to: "harness"
+    why: "Operational tooling/wiki scaffolding, not understanding — onboarding produces a map, not a tooling layer."
+
+  - prompt: "Write an ADR for why we picked Postgres over Mongo."
+    route_to: "decision-records"
+    why: "Capturing the 'why' of a decision; the map captures 'what is', not the rationale."
+
+  - prompt: "The login flow throws a 500 intermittently — find the bug."
+    route_to: "debug"
+    why: "Chasing a specific failure through the system; onboarding builds the map you debug with, it does not root-cause."
+
+  - prompt: "Create the initial CLAUDE.md memory file for this repo."
+    route_to: "init"
+    why: "Narrow single-file agent memory; onboarding is the broader recon that feeds init, not the file write itself."
+
+capability:
+  - scenario: >
+      Given an unfamiliar Node/Express + Postgres repo (no prior context), produce
+      the onboarding map without reading every file line-by-line.
+    must_include:
+      - "Identifies stack + framework version from package.json and the lockfile, not the README first"
+      - "Sizes the repo with scc (per-file LOC/complexity)"
+      - "Locates the entry point and route registration (app.get/post/use or router mounts)"
+      - "Traces one real request end-to-end: transport handler -> business logic -> persistence"
+      - "Labels module ownership (transport / business logic / persistence / UI)"
+      - "Surfaces at least one hidden behavior (cron / webhook / queue worker / listener) via ripgrep"
+      - "Ranks hotspots using the git churn one-liner (and notes churn×complexity as the richer move)"
+      - "States the exact commands to run it locally and hit one path"
+      - "Writes results into CODEBASE-MAP.md with the required sections (Stack, Entry points, Request flow, Module ownership, Hidden behavior, Hotspots, How to run)"
+      - "Does NOT attempt a line-by-line full read; works breadth-first"

package/skills/codebase-onboarding/references/recon-playbook.md

@@ -0,0 +1,57 @@
+# Recon playbook — per-ecosystem patterns & escalation
+
+Offloaded depth for the recon pass in `../SKILL.md`. Pull the rows you need; do not run them all.
+
+## Entry points & hidden side effects by ecosystem
+
+### Node / Express / Next.js
+- **Entry**: `package.json` `scripts.start`/`dev` → the bootstrap file (`server.js`, `src/index.ts`). Next.js: routes are files under `app/` (route handlers `route.ts`) or `pages/api/`.
+- **Routes**: `rg -n "app\.(get|post|put|delete|use)\(|router\.(get|post|use)\(" src`
+- **Side effects**: `setInterval`, `node-cron`, BullMQ (`new Queue`/`Worker`), `EventEmitter.on(`, Next.js `middleware.ts`, `instrumentation.ts`, and `next.config` rewrites/redirects.
+
+### Python / Django / FastAPI
+- **Entry (Django)**: `manage.py` → `settings.ROOT_URLCONF` → `urls.py` trees. **FastAPI**: the `FastAPI()` instance + `APIRouter` includes; `uvicorn` target in the run command.
+- **Routes**: `rg -n "@app\.(get|post|put|delete)|APIRouter|path\(|re_path\(|router\.register" .`
+- **Side effects**: Celery (`@shared_task`, `celery.beat` schedule), Django signals (`@receiver`, `post_save`), management commands (`management/commands/`), `apps.py` `ready()`, middleware list in settings.
+
+### Ruby / Rails
+- **Entry**: `config/routes.rb`, `config/application.rb`, initializers in `config/initializers/`.
+- **Side effects**: Sidekiq/ActiveJob workers (`app/jobs`, `*_worker.rb`), `whenever` cron schedule, ActiveRecord callbacks (`after_save`, `before_create`), `config/schedule.rb`.
+
+### Go
+- **Entry**: `func main()` (find with `rg -n "func main\(\)"`), the router setup (`chi`, `gin`, `mux`, stdlib `http.HandleFunc`).
+- **Side effects**: goroutines launched at boot (`go func()`), `time.Ticker`/`cron`, `init()` functions (run before main, easy to miss).
+
+### JVM / Spring Boot
+- **Entry**: the `@SpringBootApplication` main class; `application.yml`/`.properties` for active profiles.
+- **Routes**: `rg -n "@RestController|@RequestMapping|@GetMapping|@PostMapping" src`
+- **Side effects**: `@Scheduled`, `@EventListener`, `@PostConstruct`, `@KafkaListener`/`@RabbitListener`, `@Async`.
+
+### PHP / Laravel
+- **Entry**: `routes/web.php`, `routes/api.php`, `public/index.php`.
+- **Side effects**: `app/Console/Kernel.php` schedule, jobs in `app/Jobs`, model events/observers (`app/Observers`), event listeners in `EventServiceProvider`.
+
+## Churn × complexity (the richer hotspot signal)
+
+Git churn alone ranks files by change frequency. Multiply by complexity to find the true danger zone — files that change constantly *and* are hard to read.
+
+```bash
+# 1. Churn (revisions per file) over a year, via code-maat
+git log --pretty=format:'[%h] %an %ad %s' --date=short --numstat --since=12.month > /tmp/log.txt
+java -jar code-maat.jar -l /tmp/log.txt -c git2 -a revisions > /tmp/churn.csv
+
+# 2. Complexity per file (reuse scc, or indentation as a cheap proxy)
+scc --by-file --format csv . > /tmp/complexity.csv
+```
+
+Join the two CSVs on filename; the **top-right quadrant** (high revisions, high complexity) is where bugs concentrate and where tests are missing. Start refactoring/test-writing there, not in the file that merely looks ugly. (adamtornhill/code-maat; understandlegacycode.com Hotspots Analysis; accessed 2026-06-02.)
+
+## When to bring in a tree-sitter dependency graph
+
+Grep + churn answers most first-pass questions. Reach for a structural graph only when the codebase is large enough that "who depends on this" is no longer obvious by eye.
+
+- **codegraph** (tree-sitter + PageRank, no embeddings/GPU): one-shot ranking of files by structural importance, biased toward query keywords. Prefer this one-shot rank for onboarding — it is fast and stateless. (github.com/tarunms7/codegraph)
+- **FileScopeMCP**: scores each file 0–10 by how many things depend on it — a quick "what is load-bearing" lens. (github.com/admica/FileScopeMCP)
+- **Heavier MCP-native graphs** (codegraph-ai/CodeGraph: ~42 MCP tools across 38 languages; tree-sitter-analyzer): full function/class/import + call/inheritance graphs. Powerful, but standing up a persistent MCP graph server during *first-pass* onboarding is usually overkill — defer until the map exists and you have a concrete deep-dive question. (accessed 2026-06-02.)
+
+**Rule of thumb**: if the repo is under a few hundred files, a tree-sitter graph costs more setup than it saves. Use it for monorepos and for finding the load-bearing packages, not for a service you can grep through in ten minutes.

package/skills/codebase-onboarding/scripts/verify.sh

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+# verify.sh — structural check for the codebase-onboarding artifact.
+#
+# Validates that a CODEBASE-MAP.md contains the required sections. This is a
+# STRUCTURE check, not a content-correctness check (this is a process skill;
+# its real rigor is the capability eval). Read-only: it never writes or edits.
+#
+# Usage:   verify.sh [path-to-map]      (default: ./CODEBASE-MAP.md)
+# Exit 0:  map present with all required sections, OR no map yet (nothing to
+#          check — an empty/clean target must not produce a false failure).
+# Exit 1:  map present but missing one or more required sections.
+
+set -euo pipefail
+
+MAP="${1:-CODEBASE-MAP.md}"
+
+# No artifact yet => nothing to validate. Clean target, exit 0 (no false fail).
+if [[ ! -f "$MAP" ]]; then
+  echo "OK: no $MAP yet — nothing to verify (run the recon pass to produce one)."
+  exit 0
+fi
+
+# Required section headers. Each entry is an extended-regex alternation so that
+# reasonable wording variants (e.g. "Request flow" / "Data flow") still pass.
+declare -a SECTIONS=(
+  "Stack"
+  "Entry points?"
+  "Request flow|Data flow"
+  "Module ownership"
+  "Hidden behavior|Hidden behaviour|Side effects?"
+  "Hotspots?"
+  "How to run|Running locally"
+)
+
+missing=()
+for pat in "${SECTIONS[@]}"; do
+  # Match a markdown heading line (## ...) containing the pattern, case-insensitive.
+  if ! grep -Eiq "^#{1,6}[[:space:]].*(${pat})" "$MAP"; then
+    # Use the first alternative as the human-readable label.
+    missing+=("${pat%%|*}")
+  fi
+done
+
+if (( ${#missing[@]} > 0 )); then
+  echo "FAIL: $MAP is missing required section(s):" >&2
+  for m in "${missing[@]}"; do
+    echo "  - $m" >&2
+  done
+  echo "Required: Stack, Entry points, Request flow, Module ownership, Hidden behavior, Hotspots, How to run." >&2
+  exit 1
+fi
+
+echo "OK: $MAP has all required sections."
+exit 0