@sitar_fiercer4c/skills 0.1.0

package/skills/backend-code-review/SKILL.md

@@ -0,0 +1,386 @@
+---
+name: backend-code-review
+description: Review an MVCS backend's HTTP routes against the repo's own code-rules.md, producing a severity-graded report organised by the layering that rules file defines. Use this skill whenever the user asks to review, audit, or critique backend code against architecture or code rules — "review the routes", "check this against code-rules", "audit the API surface", "does this follow our MVCS structure", "is the routes layer clean" — and whenever they point at a code-rules.md, an architecture-rules file, or a routes/ directory and ask what is wrong with it. Also use it when the user asks for a security or layering pass over an Express API, or asks which endpoints lack auth, validation, or rate limiting. Only the routes layer has an established methodology; see Scope.
+---
+
+# Backend code review
+
+## What this produces
+
+One markdown file: a review of a backend's HTTP routes, judged against that repo's own
+`code-rules.md`, organised by the layering that file defines. Severity counts and a route
+inventory at the top, per-file and per-route finding tables in the middle, a prioritised fix
+list at the bottom.
+
+`references/report-format.md` is the output contract — read it before writing anything. It
+carries the skeleton, the severity model, the table columns, and worked example rows showing the
+level of specificity expected.
+
+Write the file, report the path, stop. Do not also summarise the findings in chat: the report is
+long and a chat summary either duplicates it or quietly becomes the thing the user reads instead,
+which defeats the point of a document they can return to and check.
+
+## Scope
+
+**Only the routes layer has an established methodology.** It was worked out against a real
+codebase and revised until a reader was satisfied with it.
+
+The other sections a `code-rules.md` typically names — services, controllers, models, config,
+utils, validators, middleware — do not have one yet. If asked to review those, say so plainly and
+offer to work one out together, the way the routes methodology was worked out. Then stop.
+
+Improvising a methodology and shipping it under this skill's name is worse than an honest gap.
+The user cannot tell, from the output, which parts of the approach were validated and which were
+invented on the spot, so the unvetted section contaminates their trust in the reviewed one.
+
+This does not mean ignoring those layers. Reviewing a route *requires* reading the service it
+calls — see "Trace every route to its floor". The boundary is about which layer the findings are
+organised around and which layer gets a systematic pass, not about which files you may open.
+
+## The protocol
+
+### 1. Read `code-rules.md` first, before any code
+
+It is the specification, not background. It gives you two things:
+
+- **The section list**, in order — these become the report's H2 headings. Take them from the file,
+  not from a fixed list, so a repo naming `jobs` or `adapters` gets those headings.
+- **The rule for each layer** — what routes are allowed to do, what belongs in controllers versus
+  services, what validators are for, and any explicit DOS/DONTS.
+
+Every finding names the rule it is judged against. That is what makes this a review against *this
+repo's stated architecture* rather than a stream of generic advice the user did not ask for. A
+criticism that cannot be tied to a rule, and is not a security or correctness issue, is a
+preference — leave it out.
+
+If there is no rules file, ask for one or ask which conventions to review against. Do not
+substitute your own idea of good layering; the user chose theirs.
+
+Also check whether this code has been reviewed before — an existing review document, a decisions
+record, PR threads on a previous round. Maintainers reject findings for reasons that are not
+visible in the code, and a reviewer who re-raises a settled point spends credibility needed for
+the real findings. Where a prior decision exists, honour it or argue against it explicitly; do
+not silently re-litigate it.
+
+### 2. Build the route inventory mechanically
+
+```bash
+python3 scripts/list_routes.py <backend>/src
+```
+
+This resolves each route's **real** path by combining the router's mount prefix from the app
+entrypoint with the path in the route file, and it flags routes defined inline in the entrypoint
+and middleware applied by path prefix.
+
+Run it rather than assembling the inventory by hand. Deriving paths by reading is where reviews
+go wrong before they start, in two specific ways:
+
+- **Doc comments naming a route's path drift from the mount point and are frequently wrong.** In
+  one backend, nine comments across a single controller named a URL segment that did not exist —
+  the router was mounted a level up from what every comment claimed. A whole review was drafted
+  from those comments before anyone opened the entrypoint.
+- **Hand-counting gets the aggregate wrong.** The derived statistics — how many routes carry a
+  validator, how many carry auth — are the lines a reader is most likely to quote, and the most
+  embarrassing to get wrong. A hand-built inventory of one backend reported four routes with
+  validators; the script found three, because a route with `auth` middleware had been miscounted.
+
+Treat the output as a scaffold, not a finding. Regex parsing misses dynamic mounts, conditionally
+registered routes, and re-exported routers. Confirm each row against the file as you trace it.
+
+Two things in the script's output are findings in their own right, worth checking before you go
+further:
+
+- **Routes defined inline in the entrypoint**, marked `(inline)`. `code-rules.md` files that name
+  a `routes` section almost always mean endpoints live there. An inline handler typically has no
+  controller, no validator, and its own ad-hoc error envelope that bypasses the error middleware.
+- **Middleware applied by path prefix**, listed separately. `app.use('/some/path', limiter)` is
+  invisible when reading the route file, and it matches all methods and all subpaths — so a
+  limiter meant for `POST /login` also throttles `GET /login/anything`.
+
+**Then walk the inventory once for cost, before you start tracing.** Take the full route list —
+every row, in order — and mark each one that reaches a third-party billed call, a subprocess, an
+LLM or OCR service, or heavy CPU. Cross that column against the limiter column. This is a pass
+over a list, not a recall exercise, and it has to be done that way: a review that names the
+throttling gaps it happened to notice reads as an exhaustive list to the person acting on it, so
+the endpoint it skipped is the one that stays unprotected. One review missed
+`POST /api/messages/:messageId/attachments/:attachmentId/quotation` — a paid extraction call —
+entirely, while correctly listing four cheaper siblings.
+
+### 3. Sweep the tree for what reading cannot see
+
+```bash
+python3 scripts/sweep.py <backend>/src --repo-root <backend>
+```
+
+Tracing a route down through its layers is how you find what a single file does wrong. It is
+structurally blind to a second class of finding, the kind that exists only across files: an
+environment variable declared in `.env` that nothing reads, a helper defined identically in two
+config modules, an export with no importer, a block of code pasted at three sites. Nobody spots
+those by reading carefully, because every individual file looks fine. You spot them by counting.
+
+This matters more than it sounds. An earlier version of this skill relied on careful reading
+alone and rediscovered a *different subset* of these findings on each run — the same review, run
+twice, would report the unused credentials one time and the duplicated helper the next. Coverage
+that depends on what you happened to notice is sampling, not review. The sweep makes it
+repeatable.
+
+Five sections come back:
+
+- **`ENV`** — every `process.env` read with its site, against what the `.env` files declare.
+  `DECLARED-NEVER-READ` is often a stale credential sitting in a checked-in file with no consumer.
+  `READ-NEVER-DECLARED` is a tunable no one can discover. `READS-OUTSIDE-CONFIG` is the layering
+  question, if the rules file gives config ownership of environment access.
+- **`EXPORTS`** — for each exported identifier, its in-file reference count and its external
+  importers. The distinction between the two numbers is the whole point; see "no importer is not
+  the same as no caller" below. A separate `same-name-elsewhere` line lists files that merely
+  contain the word — that is a duplicate-definition lead, not an importer.
+- **`REQUEST INPUTS`** — every request-derived key name in the tree, each marked `MASKED` or
+  `UNMASKED` against the masking array the sweep finds, plus the sites that log or pass a whole
+  `req.query`/`req.body` object.
+- **`DUPES`** — the same identifier defined at top level in more than one file.
+- **`BLOCKS`** — normalised line windows appearing verbatim in more than one place.
+
+Every row is a lead, not a finding. The parsing is regex-based, so it mis-handles dynamic property
+access, re-exports, and identifiers built from strings, and a name appearing in two files is
+sometimes two unrelated things. Open the file and confirm before any of it goes in the report.
+
+**`REQUEST INPUTS` exists because the natural grep misses keys.** A masking list is only correct
+if it covers every sensitive key the app actually receives, and that set is not greppable: a
+callback handler often never writes `req.query.code` at all — the controller passes the whole
+`req.query` object into a service, which destructures `{ state, code, error }` out of its own
+parameter, a file and a layer away. The sweep follows that one hop. In one backend this was the
+difference between reporting two unmasked keys and reporting three; the third, `t`, was a signed
+image-proxy token read on a different route entirely. Take the enumeration from this output rather
+than from what you remember reading.
+
+**Then cross-reference your own notes.** Some of the best findings are two ordinary observations
+that only mean something together, and depth-first reading files them in separate sections where
+they never meet. One review noted that a config module's header comment cites another file as the
+model lazy-environment pattern, and noted elsewhere that this same file reads its environment at
+module load — the bug the comment holds up as the fix. Both facts were in the document; the
+finding was not. Before writing, reread what you have collected and look for pairs like that: a
+comment that claims something you disproved elsewhere, a helper recommended in one section that
+you flagged in another, a guard present on one route and absent on its sibling.
+
+### 4. Trace every route to its floor
+
+For each route, follow the whole chain: route → middleware → validator → controller → service(s)
+→ utils and models. Judge each layer against its own rule.
+
+**Violations hide one layer below where they appear.** A controller can look perfectly thin while
+the service it delegates to does another layer's job — reaching into a model it should not own,
+or running two hundred lines of input sanitisation that the rules file says belongs in
+`validators/`. A review that reads the route file and the controller and stops will miss most of
+what is actually there, and will read as superficial to anyone who knows the code.
+
+This is the expensive step and there is no shortcut. Budget for it.
+
+When two routes share a handler shape — paired exports, paired list endpoints — read both rather
+than assuming symmetry. Near-duplicate handlers are where copy-paste divergence lives, and the
+duplication itself is usually worth a finding.
+
+### 5. Judge, and record what holds
+
+Severity model:
+
+| Marker | Means |
+|---|---|
+| 🔴 | Rule violation, security defect, or correctness bug |
+| 🟡 | Rule drift, duplication, fragile coupling |
+| ⚠️ | Observation, nit, inconsistency |
+| ✅ | Verified correct — worth keeping as-is |
+
+**Before you write 🔴 or 🟡 on any row, answer this out loud in your notes:**
+
+> **Does the harm require a fact that is not in this repository?**
+
+Facts that are not in the repository include: the `NODE_ENV` value the deployment actually sets,
+the number of proxies in front of the app, whether a permissive default someone explicitly wrote
+down was intended, which hosts are on the allow-list at the load balancer.
+
+If the answer is **yes**, the row is capped at ⚠️ and phrased as **"confirm X"**, never "change X".
+If the answer is **no** — the harm follows from code that is in front of you, at any deployment —
+grade it on its merits.
+
+Worked through the cases this exists for:
+
+| Candidate | Requires an outside fact? | Grade |
+|---|---|---|
+| TOTP printed to stdout behind a `NODE_ENV !== 'production'` gate | Yes — what `NODE_ENV` is set to | ⚠️ "confirm production sets it" |
+| `CORS_ORIGIN='*'` written into both `.env` and `.env.example` | Yes — whether the deployed value is the example one | ⚠️ "confirm the deployed origin" |
+| `app.set('trust proxy', 1)` | Yes — how many proxies are actually in front | ⚠️ "confirm the hop count" |
+| One global secret signs password-reset tokens | No — true at every deployment | 🔴 |
+| `/api/health/officecli` reachable unauthenticated | No — no middleware on the route, full stop | 🔴 |
+| One `JWT_SECRET` signs both session and image-proxy tokens | No — visible in the two signing sites | 🔴 |
+
+The reason this is a gate and not advice: the rest of this skill sharpens security instincts hard,
+and a paragraph asking for restraint loses to them every time. The question has a yes/no answer
+and a forced consequence, so it survives the pull. A reader who dismisses three re-opened
+decisions reads the fourth finding — the real one — with less attention, and that is the cost.
+
+A ⚠️ "confirm" row is not a weaker finding. It is the accurate one: you found something whose
+safety depends on a value you cannot see, and the useful output is to name the value.
+
+**A `✅` is a claim that you checked the thing that could go wrong.** Not that the code reads well,
+and not that the mechanism is clever. The happy path working is not evidence; it is the default.
+So say which failure path you followed — the catch block, the second concurrent caller, the
+missing-config case, the malformed input — and what you found there. If you did not follow one,
+that is not a `✅`. Leave it out. Silence is honest; a `✅` is a promise.
+
+The reason to be strict here is that `✅` is sold to the reader as "examined and sound", so a wrong
+one is worse than no row at all — it actively stops the next person from looking. Real examples
+from a review of this kind: a streaming proxy marked `✅` for "handling its failure mode well",
+where the mechanism was indeed careful but the `catch` around it collapsed credential, network and
+permission errors alike into `404 Image not found`. A counter marked `✅` for sound concurrency
+reasoning, where the increment was genuinely atomic but the caller sat on a `GET` path and threw
+the reserved number away on every conflict. In both, the praise was accurate about the mechanism
+and blind to the code immediately around it. A `✅` covers what you examined and nothing adjacent.
+
+`✅` rows still matter and should be there. A review listing only faults leaves the reader unable
+to tell "examined and sound" from "not examined", and that ambiguity is worst exactly where the
+stakes are highest. Record the non-obvious things you actually probed: a security control you
+tried to get past, a guard you confirmed runs before the expensive work, an idempotency mechanism
+you traced through a retry.
+
+## What to look for below the route file
+
+Route files are short and mostly fine. The findings are underneath. This list is where the
+non-obvious ones came from — treat it as prompts to check, not a checklist to fill.
+
+- **Writes on a `GET` path.** Lazy backfills, self-healing migrations, cache warming, counters
+  consumed to build a display value. `GET` is meant to be safe and idempotent; concurrent reads
+  then race each other into writes, and work reserved on a read path is usually work discarded.
+- **Whole documents serialised to the client.** A `.lean()` or a raw `res.json(doc)` bypasses the
+  model's own `toJSON`, so fields that transform strips — buffers, hashes, internal state — go out
+  on the wire. Check what the model deletes and whether the query path honours it.
+- **One secret signing two different token types.** Session tokens and image-proxy or download
+  tokens signed with the same key. Often safe only by payload-shape coincidence — one verifier
+  requires a field the other's tokens lack. That is not a documented boundary, so a future
+  payload change breaks it silently.
+- **Credentials in logs.** Request loggers that dump `req.query` capture OAuth authorization
+  codes on callback routes and signed tokens on proxy routes. Check whether the masking helper
+  the codebase already has is actually applied at the outermost layer, not just deep in a service.
+  Take the unmasked key list from `sweep.py --section request-inputs`, not from reading — the keys
+  that leak are exactly the ones no grep finds, because they are destructured a layer away from
+  where the request object is read.
+- **Error handlers that flatten distinct failures into one status.** A `catch` mapping everything
+  to `404` or `400` hides credential and network failures from whoever has to debug them. Check
+  what the handler discriminates on, not just that it has a handler.
+- **Validation living in services.** Length caps, allow-lists, bounds checks, recipient parsing
+  inside a service function, when the rules file has a `validators` section. Note where it is and
+  how much of it there is; the volume is the argument.
+- **Expensive or paid-API endpoints left unthrottled** — the cost/limiter cross-product from
+  step 2. Also check whether a `force`-style query flag bypasses an idempotency short-circuit,
+  which converts a bounded operation into unbounded spend.
+- **A helper that exists to consolidate a pattern, bypassed by one caller.** Codebases grow a
+  `withX` wrapper and then leave the oldest call site hand-rolling the same sequence. The
+  wrapper's own comment often claims universal use — check it.
+- **Redundant round-trips to an external API** inside a single request, usually from a controller
+  calling two service functions that each independently fetch the same remote object.
+- **Auth applied inconsistently across sibling routes** — and, where a route deliberately has no
+  auth middleware, what actually authorises it. A signed token in a query string can be a correct
+  design; say so and explain the trail rather than reporting it as missing auth.
+
+## Verify before you write
+
+Every claim is checkable, and a reader who finds one wrong claim discounts the rest of the
+report. Four failure modes to guard against specifically:
+
+**Comments are claims, not facts.** An export block commented "exported for unit testing" is a
+hypothesis. Grep for the identifiers across `src`, tests, and scripts before repeating it — in one
+backend none of the six such exports was imported anywhere, so the comment was simply false.
+
+**"No importer" is not the same as "no caller."** That same finding once produced advice that
+would have broken the file: the review concluded the six exports were dead and said deleting them
+was safe, when every one had four or five callers *inside its own module*. They were over-exported,
+not unused. The repair for an identifier with no external importer is to narrow the export list;
+the repair for one with no references anywhere is to delete the definition. `sweep.py` reports
+both counts side by side precisely because the two look identical from outside the file and the
+remedies are opposite. Check the in-file count before you recommend a deletion.
+
+**Sameness is measurable, so measure it.** "Identical", "the same twelve phrases", "differs only
+by X" — these are the claims a duplication finding rests on, and they are the reader's entire
+reason to consolidate. Diff the two sites rather than eyeballing them. A review that reported two
+keyword lists as covering the same phrases, when one had eleven entries and the other twelve, gave
+its reader a merge that would silently drop a case. The same goes for arithmetic in prose: if you
+write "15 of 31", the remainder is 16, and a reader who spots the slip stops trusting the counts
+that matter.
+
+**Follow the value to its sink before reporting an injection or traversal.** A path segment
+interpolated into a key looks alarming; if the result is compared for equality against a
+signature-verified payload, it is closed, and reporting it as traversable is the kind of error
+that costs the reader's trust in everything else. Trace it, then either report it as a real
+finding or record it as a `✅` with the reason it holds.
+
+Cite `file.js:LINE` for everything, and confirm the line still holds what you say before it goes
+in. Duplication findings cite every site, with line ranges — "this is duplicated" with one
+citation is unactionable and unverifiable.
+
+**A citation carries two claims, and checking one does not check the other.** The line number is
+one claim; the assertion riding on it is the other. Confirming that `excel.service.js:10–32`
+exists is not confirming that the function there has no `return results;` — in the review that
+made exactly that mistake, `return results;` was line 33, one past the cited range, and the range
+itself stopped mid-function with an unclosed brace. Nothing about the line check would catch it,
+because the line check passed. So verify the claim against the construct, then cite it.
+
+This is sharpest on **negative claims** — "no return", "never calls", "lacks a guard", "no
+importer". An absence is only observable over a complete construct: if your range ends before the
+closing brace, the thing you say is missing may be on the next line. Cite the construct's full
+extent, and quote the closing lines or the command that establishes the absence.
+
+### The last thing you do before the report is finished
+
+```bash
+python3 scripts/verify_citations.py <report>.md --root <backend> --problems
+```
+
+It resolves every `file:LINE` and `file:LINE–LINE` in the document, prints the real source back,
+and flags three things: `NOT-FOUND` (the path or line does not resolve), `AMBIGUOUS` (a bare
+filename matching several files — say which), and `TRUNCATED-CONSTRUCT` (a range on a row that
+claims an absence, where the braces do not balance across it).
+
+Every flag is a row to reopen. `TRUNCATED-CONSTRUCT` in particular is not a formatting nit; it is
+the script telling you the evidence for that row does not cover the claim. Some will be fine on
+inspection — a row citing "9 sites across `:19–176`" is a span, not a construct — but you have to
+look, because this is the one failure mode that reads as authoritative when it is fabricated.
+
+Run it against the finished document, fix what it finds, and run it again.
+
+## Writing the findings
+
+Each finding carries four things in order: a **bold claim in a few words**, the evidence, the
+consequence, and the repair. The reader is scanning a wide table; the bold clause is what they
+read first and it has to carry the point on its own.
+
+**The repair is the part reviews drop, and it is the part the reader needs most.** You have just
+spent an hour tracing this code. They have not. A finding that stops at the consequence hands the
+hardest question — what do we actually do — back to the person with the least context to answer
+it, and a finding nobody can act on is one nobody can schedule or argue with either. Name the
+function to extract, the module to create, the import to delete, the signature to change, the
+config key to add. "This is duplicated across three files" is a diagnosis; "extract it to
+`utils/fileName.util.js` and import it at all three" is a review.
+
+Where the right repair is genuinely contested, say so *and still give the reader something*: name
+the two options and what each costs, then say which one the rules file favours. That is a repair.
+"Whether it should move is a judgement call" is where the reviewer stopped working.
+
+The prioritised fix list at the bottom is not a substitute. Readers work from the tables, and a
+row whose fix lives forty lines away in another section reads as a complaint.
+
+**Repair the whole finding, not the instance you noticed.** If the claim is that a block appears
+at three sites, the repair addresses all three — a fix that folds two of them leaves the third
+behind and reads as complete, so nobody comes back for it. If the finding names three concerns in
+one place — a value read, validated, and normalised in the wrong layer — the repair moves all
+three. Partial repairs are how the leftover site survives the cleanup.
+
+Prefer naming a place in the same codebase that already does the thing correctly over
+recommending an abstract fix. If one module uses a dedicated secret and another reuses the shared
+one, the fix is "follow `oauthState.js`" — concrete, obviously correct, and already approved by
+whoever wrote it.
+
+State consequences in terms of what it costs: unbounded spend, an hour of unrevocable access, a
+credential in a log file. Not "this is bad practice".
+
+Close with the prioritised fix list. The tables are organised for lookup, not for action — rank
+the fixes by exploitability and blast radius, so an unauthenticated remote issue outranks an
+internal layering violation even when both are 🔴.