@gallopsystems/agent-skills 1.31.2 → 1.33.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (48) hide show
  1. package/README.md +24 -0
  2. package/package.json +1 -1
  3. package/plugins/gallop-ui/skills/gallop-ui/SKILL.md +1 -1
  4. package/plugins/gallop-ui/skills/gallop-ui/api-principles.md +5 -2
  5. package/plugins/gallop-ui/skills/gallop-ui/finding-a-component.md +5 -0
  6. package/plugins/gallop-ui/skills/gallop-ui/pitfalls.md +5 -0
  7. package/plugins/gallop-ui/skills/gallop-ui/pulling-updates.md +14 -3
  8. package/plugins/gallop-ui/skills/gallop-ui/using-in-an-app.md +15 -0
  9. package/plugins/generate-documentation/.claude-plugin/plugin.json +8 -0
  10. package/plugins/generate-documentation/skills/generate-documentation/SKILL.md +186 -0
  11. package/plugins/generate-documentation/skills/generate-documentation/bin/capture-example.mjs +53 -0
  12. package/plugins/generate-documentation/skills/generate-documentation/bin/render.mjs +82 -0
  13. package/plugins/generate-documentation/skills/generate-documentation/bin/shots.mjs +139 -0
  14. package/plugins/generate-documentation/skills/generate-documentation/formats.md +71 -0
  15. package/plugins/generate-documentation/skills/generate-documentation/templates/guide.html +116 -0
  16. package/plugins/kysely-postgres/skills/kysely-postgres/SKILL.md +17 -3
  17. package/plugins/kysely-postgres/skills/kysely-postgres/references/common-pitfalls.md +91 -0
  18. package/plugins/kysely-postgres/skills/kysely-postgres/references/concurrency-and-transactions.md +155 -0
  19. package/plugins/kysely-postgres/skills/kysely-postgres/references/full-text-and-grouping.md +13 -0
  20. package/plugins/kysely-postgres/skills/kysely-postgres/references/migrations-and-codegen.md +50 -0
  21. package/plugins/kysely-postgres/skills/kysely-postgres/references/query-patterns.md +65 -0
  22. package/plugins/kysely-postgres/skills/kysely-postgres/references/set-lateral-locking.md +2 -0
  23. package/plugins/nitro-testing/skills/nitro-testing/SKILL.md +10 -0
  24. package/plugins/nitro-testing/skills/nitro-testing/proving-the-claim.md +240 -0
  25. package/plugins/nitro-testing/skills/nitro-testing/transaction-rollback.md +1 -0
  26. package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/SKILL.md +23 -12
  27. package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/auth-patterns.md +50 -0
  28. package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/error-handling.md +34 -3
  29. package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/examples/validation-endpoint.ts +2 -2
  30. package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/fetch-patterns.md +57 -0
  31. package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/nitro-tasks.md +2 -0
  32. package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/server-services.md +100 -1
  33. package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/sse.md +1 -1
  34. package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/validation.md +120 -14
  35. package/plugins/pr-review/.claude-plugin/plugin.json +8 -0
  36. package/plugins/pr-review/skills/pr-review/SKILL.md +68 -0
  37. package/plugins/pr-review/skills/pr-review/brief-prompt.md +33 -0
  38. package/plugins/pr-review/skills/pr-review/focus-areas.md +63 -0
  39. package/plugins/pr-review/skills/pr-review/judge.md +29 -0
  40. package/plugins/vue-nuxt/skills/vue-nuxt/SKILL.md +29 -0
  41. package/plugins/vue-nuxt/skills/vue-nuxt/async-state.md +229 -0
  42. package/plugins/vue-nuxt/skills/vue-nuxt/component-authoring.md +45 -0
  43. package/plugins/vue-nuxt/skills/vue-nuxt/editing-forms.md +137 -0
  44. package/plugins/vue-nuxt/skills/vue-nuxt/formatters.md +8 -0
  45. package/plugins/vue-nuxt/skills/vue-nuxt/slots.md +16 -0
  46. package/plugins/vue-nuxt/skills/vue-nuxt/template-idioms.md +52 -0
  47. package/plugins/vue-nuxt/skills/vue-nuxt/v-model.md +2 -1
  48. package/plugins/vue-nuxt/skills/vue-nuxt/watch.md +5 -1
@@ -41,8 +41,13 @@ export function useStripe() {
41
41
 
42
42
  ```typescript
43
43
  // server/api/checkout/create.post.ts
44
+ import { z } from "zod";
45
+
44
46
  export default defineEventHandler(async (event) => {
45
- const { amount, currency } = await readBody(event);
47
+ const { amount, currency } = await readValidatedBody(event, z.object({
48
+ amount: z.number().int().positive(),
49
+ currency: z.enum(["usd", "eur"]),
50
+ }).parse); // never raw readBody + destructure: see validation.md
46
51
 
47
52
  const { createPaymentIntent } = useStripe();
48
53
 
@@ -169,6 +174,98 @@ async function callExternalApi() {
169
174
  }
170
175
  ```
171
176
 
177
+ ## Failures from third-party calls
178
+
179
+ The shape reviewers flag most in service code: a catch or a status check that turns
180
+ a **failure** into a normal-looking result ("not found", "empty", "disconnected",
181
+ "done"), which the caller then acts on.
182
+
183
+ ```typescript
184
+ // ❌ every error becomes "no such folder", so the caller creates a duplicate
185
+ async function findFolder(name: string) {
186
+ try { return await drive.find(name); } catch { return null; }
187
+ }
188
+
189
+ // ✅ only a real not-found means absent; everything else propagates
190
+ async function findFolder(name: string) {
191
+ try {
192
+ return await drive.find(name);
193
+ } catch (error: any) {
194
+ if (error?.status === 404) return null;
195
+ throw error;
196
+ }
197
+ }
198
+ ```
199
+
200
+ - **Only not-found is absence.** Timeouts, 5xx, 429 and auth errors on a lookup are
201
+ failures. Never create, delete, or report "no access" on the strength of a
202
+ lookup that failed.
203
+ - **A 2xx without the expected object is a failure**, not a completed read (an
204
+ empty body, a missing `items` key, a wrapper with `error` inside).
205
+ - **A 401/403 for one resource is local.** One mailbox, calendar or user the
206
+ integration can't reach doesn't mean the whole connection is down: mark that item,
207
+ keep going, and only flip "disconnected" on an auth failure of the connection itself.
208
+ - **Batches: isolate items.** One bad item (or one chunk's unreadable response body)
209
+ must not fail the whole batch. Collect per-item results, retry the failing chunk
210
+ item by item if the API is all-or-nothing, and report partial success as partial.
211
+ - **Map known upstream rejections to the right status** (a provider's "too large" to
212
+ 413, "not found" to 404) instead of a generic 502/500, so the client can say why.
213
+ - **Third-party contracts:** handle every status representation the provider
214
+ documents (string *and* numeric codes, new enum values), detect state changes by
215
+ the documented field rather than an inferred one (a zero total is not "voided"),
216
+ and re-validate a stored remote id before reusing it, since the remote side can
217
+ delete or move it.
218
+ - **Log allowlisted fields, never the whole error.** SDK errors carry request
219
+ headers, tokens and payloads; logs are not the place for emails or other personal
220
+ identifiers. Log `{ service, status, code, requestId }`.
221
+
222
+ ### Timeouts and best-effort work
223
+
224
+ An outbound call without a timeout can hang the request (or a job's claim) for
225
+ minutes. `Promise.race` against a timer **does not cancel** the call; it keeps
226
+ running and holding whatever it holds. Put the timeout on the call itself:
227
+
228
+ ```typescript
229
+ await $fetch(url, { timeout: 5_000 }); // ofetch; ignored if you also pass `signal`, and it stops
230
+ // at the response headers: a stalled body is not covered
231
+ await $fetch(url, { signal: AbortSignal.timeout(5_000) }); // covers the body read too
232
+ await fetch(url, { signal: AbortSignal.timeout(5_000) }); // native fetch
233
+ // SDKs: use the client's own timeout option
234
+ ```
235
+
236
+ Don't block a response on best-effort work (a chat notification, an analytics ping,
237
+ a "last seen" refresh). Hand it to Nitro and return:
238
+
239
+ ```typescript
240
+ event.waitUntil(notifyChannel(payment).catch((e) => console.error("notify failed", e.message)));
241
+ return { ok: true };
242
+ ```
243
+
244
+ (`event.waitUntil` is Nitro v2's; on serverless runtimes it extends the invocation,
245
+ on Node it just tracks the promise. Always `.catch`: nobody awaits it.)
246
+
247
+ ## Multi-step operations with side effects
248
+
249
+ When one handler or job does several writes, some of them external (create a folder,
250
+ send an email, post to an API), order matters because external writes can't be
251
+ rolled back with the DB transaction:
252
+
253
+ 1. **Validate everything first.** Every input, every referenced record, every
254
+ refusal check, before the first mutation. Cleanup or "prep" steps go after the
255
+ checks, so a refused request changes nothing.
256
+ 2. **DB work in one transaction** (see Transaction Pattern below), external calls
257
+ outside it, so a slow API doesn't hold row locks.
258
+ 3. **Record intent before delivery** (an outbox/guard row inserted first, delivery
259
+ marked done after). The guard that stops re-runs must not also stop a **retry** of a
260
+ delivery that failed: track delivery state separately from "already processed".
261
+ A retry after "sent but not yet marked done" sends twice, so pass the provider a
262
+ stable idempotency key (the outbox row's id) where it accepts one.
263
+ 4. **Idempotency keys cover the whole payload.** When a replay is detected by key,
264
+ compare every field that affects the result and reject a replay whose payload
265
+ differs, instead of returning the first result for a different request.
266
+ 5. **Conditional external writes.** If you validated against a remote version/etag,
267
+ send it on the write (`If-Match`) so a concurrent edit isn't overwritten.
268
+
172
269
  ## Transaction Pattern
173
270
 
174
271
  ```typescript
@@ -236,3 +333,5 @@ export function useService() {
236
333
  3. **Composition order** - Call use*() inside functions, not module level
237
334
  4. **Error transformation** - Convert SDK errors to HTTP errors
238
335
  5. **Transaction scope** - Pass `trx` when in transaction
336
+ 6. **Failure is not absence** - Only a not-found means "none"; see Failures from third-party calls
337
+ 7. **Every outbound call gets a timeout** - On the call itself, not a `Promise.race`
@@ -191,7 +191,7 @@ const reconnect = () => {
191
191
 
192
192
  ```typescript
193
193
  // Server reads position
194
- const { position } = await getValidatedQuery(event, schema);
194
+ const { position } = await getValidatedQuery(event, schema.parse);
195
195
  const chunks = await getChunksFromPosition(id, position);
196
196
  ```
197
197
 
@@ -12,26 +12,30 @@
12
12
 
13
13
  Note: It's `getRouterParams` (plural), not `getRouterParam`.
14
14
 
15
- ## Pattern 1: Direct Schema (h3 v2+ with Standard Schema)
15
+ ## Pattern 1: Pass `schema.parse` (the default)
16
16
 
17
- h3 v2+ supports Standard Schema, meaning you can pass Zod schemas directly:
17
+ Nuxt 4 runs **h3 v1** (1.15.x), whose validated readers take a **function**
18
+ `(data) => result`, not a schema object. Pass the schema's `parse`:
18
19
 
19
20
  ```typescript
20
21
  const querySchema = z.object({
21
- search: z.string().min(1),
22
- page: z.coerce.number().default(1),
22
+ search: z.string().min(1).optional(),
23
+ page: z.coerce.number().int().positive().default(1),
23
24
  });
24
25
 
25
- // Pass schema directly (recommended)
26
- const query = await getValidatedQuery(event, querySchema);
27
-
28
- // Also works for body and params
29
- const body = await readValidatedBody(event, bodySchema);
30
- const params = await getValidatedRouterParams(event, paramsSchema);
26
+ const query = await getValidatedQuery(event, querySchema.parse);
27
+ const body = await readValidatedBody(event, bodySchema.parse);
28
+ const params = await getValidatedRouterParams(event, paramsSchema.parse);
31
29
  ```
32
30
 
33
- **Pros:** Simplest syntax, cleaner code
34
- **Cons:** ZodError thrown directly - not user-friendly
31
+ When `parse` throws, h3 turns it into a **400** (`statusMessage: "Validation Error"`,
32
+ the `ZodError` in `data`). The result is typed from the schema.
33
+
34
+ - **Not the schema object:** `getValidatedQuery(event, querySchema)` is a type error
35
+ on h3 v1 (passing schemas directly is an h3 **v2** feature; Nuxt 4 isn't on it).
36
+ - **Not `schema.safeParse`:** h3 returns whatever the validator returns, so you get
37
+ the `{ success, data | error }` wrapper back as your "body", and a failed parse is
38
+ not rejected.
35
39
 
36
40
  ## Pattern 2: Manual Validator Function
37
41
 
@@ -104,13 +108,108 @@ const createUserSchema = z.object({
104
108
 
105
109
  ```typescript
106
110
  const paramsSchema = z.object({
107
- id: z.coerce.number().positive(),
111
+ id: z.coerce.number().int().positive(), // rejects "", "0", "abc", "1.5"
108
112
  });
109
113
 
110
114
  // In /api/users/[id].get.ts
111
- const { id } = await getValidatedRouterParams(event, paramsSchema);
115
+ const { id } = await getValidatedRouterParams(event, paramsSchema.parse);
116
+ ```
117
+
118
+ ## Validation traps that keep shipping
119
+
120
+ Every one of these passed review once and was later fixed. Check them on every
121
+ handler you write or touch.
122
+
123
+ ### 1. Never `readBody` / `getQuery` / `getRouterParams` and destructure
124
+
125
+ The raw readers return `any`. `const { amount } = await readBody(event)` accepts
126
+ any shape, and the first bad value surfaces as a **500** from deep in the handler
127
+ (or a database error) instead of a 400. Every field a handler reads, from body,
128
+ query **and** route params, goes through a schema, ids included.
129
+
130
+ ```typescript
131
+ // ❌ unvalidated: wrong type, missing field and junk keys all reach the DB
132
+ const { amount, invoiceId } = await readBody(event);
133
+
134
+ // ✅ 400 on bad input, typed result
135
+ const { amount, invoiceId } = await readValidatedBody(event, z.object({
136
+ amount: z.number().int().positive(),
137
+ invoiceId: z.number().int().positive(),
138
+ }).parse);
112
139
  ```
113
140
 
141
+ ### 2. Query and route values are strings, and `""` is not "absent"
142
+
143
+ `?page=` sends `""`. `z.coerce.number()` turns `""` into **`0`**, and `.default()`
144
+ only fires for `undefined`, so a blank param slips past the default. Rules:
145
+
146
+ - Ids and page numbers: `z.coerce.number().int().positive()` (rejects `""`, `0`, `NaN`).
147
+ - Optional filters a form may send blank: map `""` to `undefined` first.
148
+ - Booleans: `z.coerce.boolean()` makes `"false"` **true**. Use `z.stringbool()` or
149
+ `z.enum(["true", "false"]).transform((v) => v === "true")`.
150
+
151
+ ```typescript
152
+ const blankToUndefined = <T extends z.ZodType>(s: T) =>
153
+ z.preprocess((v) => (v === "" ? undefined : v), s);
154
+
155
+ const querySchema = z.object({
156
+ page: blankToUndefined(z.coerce.number().int().positive().optional()).default(1),
157
+ status: blankToUndefined(z.enum(["open", "closed"]).optional()),
158
+ });
159
+ ```
160
+
161
+ ### 3. Dates: validate the calendar, not the shape
162
+
163
+ A `/^\d{4}-\d{2}-\d{2}$/` regex accepts `2025-02-30`, which then fails as a 500 in
164
+ the Postgres cast, or compares wrongly as text. `z.iso.date()` checks real calendar
165
+ days (it rejects `2025-02-30` and `2025-02-29`, accepts `2024-02-29`). Check
166
+ ranges on the object, with a `path` so the error lands on the right field:
167
+
168
+ ```typescript
169
+ const rangeSchema = z.object({
170
+ from: z.iso.date(),
171
+ to: z.iso.date(),
172
+ }).refine((v) => v.from <= v.to, { error: "`to` must be on or after `from`", path: ["to"] });
173
+ ```
174
+
175
+ (Canonical `YYYY-MM-DD` strings compare correctly as text; anything else doesn't.)
176
+
177
+ ### 4. `z.object` silently strips unknown keys
178
+
179
+ A renamed or legacy field, a misspelled key, or a filter this mode doesn't support
180
+ is **dropped without an error**, so the caller believes it was applied. When a
181
+ dropped key would be a bug, use `z.strictObject({...})` (400 `Unrecognized key`),
182
+ or map the old name explicitly. Likewise, reject a parameter a branch cannot honor
183
+ (an `offset` on a mode that ignores it) instead of accepting and ignoring it.
184
+
185
+ ### 5. Bound every string and array, above all on unauthenticated routes
186
+
187
+ Sign-up, contact and webhook-style endpoints that insert rows need `.max()` on
188
+ every string and array (`z.string().trim().min(1).max(200)`,
189
+ `z.array(...).max(50)`). Unbounded input from an anonymous caller is a storage and
190
+ DoS problem, not just a validation one.
191
+
192
+ ### 6. Canonicalize once, in the schema
193
+
194
+ If identifiers are compared downstream (lookups, dedupe, guards), normalize them in
195
+ the schema with `.trim()` / `.toUpperCase()` / a `.transform()`, so every query
196
+ and every guard sees the same form. Two code paths that normalize differently
197
+ (the planner trims, the guard doesn't) disagree about the same record.
198
+
199
+ ### 7. Cross-field rules, and PATCH against the stored row
200
+
201
+ Rules that involve two fields (start ≤ end, "B is required when A is X", a pair of
202
+ columns that must both be set or both be null) belong in a `.refine`/`.superRefine`
203
+ on the object. On a PATCH that sends only one of the pair, check the rule against
204
+ **the stored row merged with the patch**, not just the fields that were sent.
205
+
206
+ ### 8. One schema per write, shared by every path that writes
207
+
208
+ Import, bulk, retry and "sync from provider" paths must call the **same** schema or
209
+ server util as the edit endpoint. A second hand-written path that skips a check is
210
+ how invalid rows get in. Put the validation in `server/utils/` (or `shared/`) and
211
+ call it from each path.
212
+
114
213
  ## Type Inference from Schemas
115
214
 
116
215
  Export schemas for client-side type reuse:
@@ -152,3 +251,10 @@ The model's prior is mostly Zod 3 — these are the idioms that changed. Get the
152
251
  const createSchema = z.object({ items: itemsSchema.default([]) });
153
252
  const patchSchema = z.object({ items: itemsSchema.optional() }); // undefined ⇢ "not sent"
154
253
  ```
254
+ - **In a PATCH, "omitted", `null` and a value are three different requests.** Omitted
255
+ (`undefined`) means "leave it", `null` means "clear it". Don't let a transform turn a
256
+ missing key into `null` (`.optional().transform((v) => v ?? null)` does exactly that,
257
+ and the update then wipes the stored value), and don't treat an explicit `null` as
258
+ "not sent" when merging defaults (`body.x ?? derived` overrides the client's clear).
259
+ Test for presence with `body.x !== undefined` (or `"x" in body`), and use `.nullable().optional()`
260
+ for clearable fields.
@@ -0,0 +1,8 @@
1
+ {
2
+ "name": "pr-review",
3
+ "description": "Review a branch or pull request for defects before a human sees it: build a context brief, run codex review with the brief, then judge each finding against the code.",
4
+ "version": "1.0.0",
5
+ "author": {
6
+ "name": "yeedle"
7
+ }
8
+ }
@@ -0,0 +1,68 @@
1
+ ---
2
+ name: pr-review
3
+ description: Review a branch or pull request for defects before a human sees it. Builds a context brief (what the change is for, its callers, sibling code and stated claims), hands the brief to codex review, then judges every finding against the code before anything is fixed. Use whenever the user asks to review a PR, branch or diff, says "codex review" or "review this before I merge", or when work is finished and about to be pushed for review. Tuned for Nuxt / Vue / TypeScript / Kysely + PostgreSQL apps.
4
+ ---
5
+
6
+ # PR review: brief, review, judge
7
+
8
+ A reviewer is only as good as what it knows about the code around the diff. Most real findings rest on evidence outside the changed lines: a caller that assumed the old behaviour, a sibling endpoint that does the same job differently, a comment or test name that promises something the code no longer does. So the review has three steps, done by three separate sets of eyes:
9
+
10
+ 1. **Brief**: a cheap model maps the code around the change. It does not review.
11
+ 2. **Review**: `codex review` gets the brief and looks for defects.
12
+ 3. **Judge**: every finding is checked against the code before it is fixed or shown.
13
+
14
+ On eight held-out pull requests, handing codex the brief raised the confirmed defects it found from 13 to about 21, and the confirmed medium- and high-impact ones from 6 to between 9 and 12, compared with a bare `codex review`. About one finding in five still did not survive checking, which is what the judge step is for.
15
+
16
+ ## Before you start
17
+
18
+ - Work from the repository root with the change committed. Print `git branch --show-current` and `git rev-parse --short HEAD` so it is unambiguous which state was reviewed.
19
+ - Pick the base ref: the PR's base branch, or for a stacked PR the branch it is stacked on. `git diff <base>...HEAD --stat` should show only this change's files. If it shows far more, the base is wrong.
20
+ - You are the orchestrator. Do not review the diff yourself first: your own opinion of the change leaks into the brief and the judging.
21
+
22
+ ## 1. Build the brief
23
+
24
+ Start a subagent on a fast, cheap model with read-only tools and give it the prompt in [brief-prompt.md](brief-prompt.md), with the base ref filled in and the PR title and description appended. If the PR or branch names a ticket, append the ticket's text too: it states the intent better than the PR body usually does. Remove any earlier reviewer's summary from the text you append.
25
+
26
+ The brief is at most 1,500 words: goal, changed units, callers and dependents, sibling code, stated claims, and existing tests. Save it to a file outside the repository. Read it once for sanity (does the goal match what the user asked for?), but do not add your own suspicions to it.
27
+
28
+ ## 2. Review with codex
29
+
30
+ ```bash
31
+ codex review "$(cat <<EOF
32
+ Review the changes on this branch against <base> (git diff <base>...HEAD). Report defects only, each with a concrete failing scenario.
33
+
34
+ A context brief was prepared before the review. It lists the code that calls, mirrors or makes claims about the changed code. Use it as a map of where to look; verify everything against the files.
35
+
36
+ $(cat /path/to/brief.md)
37
+ EOF
38
+ )" < /dev/null > /path/to/review.txt 2>&1
39
+ ```
40
+
41
+ - **Close stdin** (`< /dev/null`) whenever codex runs from an agent or in the background. Otherwise it waits for input that never comes and hangs without an error.
42
+ - `--base` cannot be combined with a prompt, which is why the base is named inside the prompt.
43
+ - The exit code is 0 even with findings. Read the text.
44
+ - The output file holds the whole session log (thousands of lines of commands and file contents). The findings are the last block, after the final `codex` line, under "Full review comments:", and are printed twice. Pass only that block to the judge.
45
+ - Reviews take from under a minute to several minutes. Run it in the background and read the file when it exits.
46
+ - Do not paste a checklist of past mistakes into this prompt. In testing, a long checklist did not add confirmed findings to a single reviewer and lowered the share that were real. Checklists work when each reviewer gets one narrow concern: see deep mode below.
47
+
48
+ ## 3. Judge every finding
49
+
50
+ Follow [judge.md](judge.md). Use a subagent that has not seen the brief being built, give it only the findings and the base ref, and have it return a verdict per finding (real with impact, pre-existing, wrong, not a defect, unverifiable) with `file:line` evidence. A different model family from the reviewer is better: it does not share the reviewer's blind spots.
51
+
52
+ ## 4. Act and report
53
+
54
+ - Fix real findings (all high and medium; low when small and local), commit, and review again if the fixes were more than trivial. Later rounds: tell codex which findings were already fixed so it does not re-flag them.
55
+ - Tell the user, in this order: the real findings and what you did about each; the findings you rejected and why, in one compact list they can overrule; pre-existing problems as possible follow-ups.
56
+ - Record the outcome in the PR description: what reviewed it, how many findings, how many fixed.
57
+
58
+ For the mechanics of the fix-and-re-review loop, see the `git-github` skill's external-review reference.
59
+
60
+ ## Deep mode
61
+
62
+ For changes that touch money, permissions, migrations or concurrency, or when the user asks for a thorough review, run one focused reviewer per concern in parallel, as described in [focus-areas.md](focus-areas.md). It costs several reviews per PR and produces many more claims, so the judge step is not optional there.
63
+
64
+ ## Files
65
+
66
+ - [brief-prompt.md](brief-prompt.md): the brief builder's prompt.
67
+ - [judge.md](judge.md): the five keep-rules and verdicts.
68
+ - [focus-areas.md](focus-areas.md): deep mode's concerns and prompt.
@@ -0,0 +1,33 @@
1
+ # Context brief prompt
2
+
3
+ Give this prompt to a cheap, fast model with read-only tools, run from the repository root. Replace `BASE` with the base ref and append the PR title and description (and the linked ticket's text, if there is one) at the end. Strip any earlier reviewer's summary or comments from that text first.
4
+
5
+ The brief builder must not review. A brief that contains opinions anchors the reviewer on them.
6
+
7
+ ```text
8
+ You are preparing a context brief for a code reviewer. You are NOT reviewing: do not look for bugs, do not judge the change, do not suggest fixes. Report facts and pointers only.
9
+
10
+ The change is `git diff BASE...HEAD` in this repository. Read the diff, then explore the repository (read-only) and write a brief of at most 1,500 words with these sections:
11
+
12
+ ## Goal
13
+ Two or three sentences on what the change is meant to do, from the PR text below and the commit messages.
14
+
15
+ ## Changed units
16
+ One line per changed function, endpoint, query, component, migration or test: `path:line` and what it does now.
17
+
18
+ ## Callers and dependents
19
+ For each changed unit that other code uses: who calls it or reads what it writes (`path:line`), and what they assume about it. Include callers of anything the diff deletes or renames.
20
+
21
+ ## Sibling code
22
+ Other code that does the same job or must agree with a changed unit: the other endpoints for the same resource (create vs update vs delete), a list query and its count query, a preview and the save it previews, a client-side check and the server validation, an import path and the edit path, a guard and the join it protects. Give `path:line` for each and one line on how it handles the same thing.
23
+
24
+ ## Stated claims
25
+ Sentences elsewhere that say how the changed code should behave, each with `path:line`: code comments and docstrings, test names, documentation and markdown, on-screen labels and messages, validation schemas, database constraints, column comments and migrations for the tables touched.
26
+
27
+ ## Lint, types and tests
28
+ Only if you can see them without running anything: existing tests that cover the changed units (`path`), and anything the repository's own instructions (CLAUDE.md, AGENTS.md) require for this kind of change.
29
+
30
+ Output the brief as markdown and nothing else.
31
+
32
+ PR text, then the linked ticket's text if there is one:
33
+ ```
@@ -0,0 +1,63 @@
1
+ # Deep mode: one focused reviewer per concern
2
+
3
+ One reviewer looking for everything finds the loud problems. Splitting the review into narrow concerns, each with its own reviewer and the same context brief, finds about three times as many confirmed defects, most of them low impact, and roughly five times as many claims to judge. Use it for changes that touch money, permissions, migrations or concurrency, or when the user asks for a thorough review. Always follow it with the judge step: about four in ten of its claims do not survive.
4
+
5
+ ## Plan
6
+
7
+ List the changed files (`git diff --name-only <base>...HEAD`) and give each file to the concerns its type calls for. Run only the concerns that have files.
8
+
9
+ | Changed file | Concerns |
10
+ |---|---|
11
+ | Test files (`.test.`, `.spec.`, `tests/`) | tests |
12
+ | Migrations | migration |
13
+ | Markdown | docs |
14
+ | `.vue`, `composables/`, `stores/` | ui |
15
+ | Other code (`server/`, `shared/`, `.ts`, `.js`, `.sql`, scripts) | concurrency, agreement, inputs, access |
16
+ | The whole change (every non-test code file) | intent, design |
17
+
18
+ These two look at the change as a whole, so give them the full diff, not a file list, and give `intent` the pull request description and the linked ticket in full. On eight past pull requests they raised 39 findings and two independent checkers confirmed 31, most of them things no bug-hunting reviewer reported: a requirement in the ticket that the code did not deliver, or one rule written in two or three places. Several of the duplicated rules were where a separate reviewer had found a bug. Report their findings under their own headings ("Against the ticket", "Design"), apart from the defects.
19
+
20
+ ## Prompt for each reviewer
21
+
22
+ Run the reviewers in parallel, each as its own `codex exec -s read-only` (or a read-only subagent), from the repository root:
23
+
24
+ ```text
25
+ You are one of several reviewers of the change `git diff BASE...HEAD` in this repository. Your assignment is ONE concern only: <title>.
26
+
27
+ Files in scope for you:
28
+ <the files planned for this concern>
29
+
30
+ <the concern's questions>
31
+
32
+ Follow the code beyond the diff wherever these questions lead: read callers, sibling handlers, schemas and tests. Do not modify any file and do not use the network. Ignore every other kind of problem; other reviewers have them.
33
+
34
+ Finish with a numbered list of findings. For each: the file path and line, a one-sentence title, and a short explanation with a concrete scenario (specific values or a sequence of events) that produces the wrong result. If you cannot give such a scenario, leave the finding out. If you find nothing, say so in one line.
35
+
36
+ A context brief was prepared before the review. Use it as a map of where to look; verify everything against the files.
37
+
38
+ <the context brief>
39
+ ```
40
+
41
+ Then merge the lists, drop duplicates (the same cause on the same code, even if worded differently), and judge every remaining finding ([judge.md](judge.md)).
42
+
43
+ ## The concerns
44
+
45
+ **tests: Tests that do not test their claim.** For each changed test: does the body exercise what its name says? Could it pass if the feature were broken (fixture that cannot fail, assertion that accepts any error, `.catch` that swallows, wrong mock route, clock not pinned near a day boundary, timing-based proof)?
46
+
47
+ **docs: Docs that contradict the code.** For each changed doc sentence, label or comment: find the code it describes and check that the code does exactly that, including exceptions, defaults, limits and names. Also check that sections of the same doc agree with each other.
48
+
49
+ **migration: Migration safety.** For each migration: does `down()` undo `up()` and can `up()` run again after it? Is the backfill reading the right source for every existing row? Can a write path now violate a new CHECK, unique or foreign-key constraint, or a changed state column leave its coupled column inconsistent? Long locks on large tables? Are generated types in sync?
50
+
51
+ **ui: Frontend state and async ordering.** For each changed component, page or composable: (1) what state survives when a dialog reopens, the selected record changes, or a prop changes, and should it? (2) can an older request, poll or save resolve after a newer one and overwrite it? (3) what does the user see when each fetch fails: is it distinguishable from empty, and does code that awaits `refresh()` check the error? (4) can the submit handler run twice (Enter, IME Enter, double click)? (5) after a mutation, is every fetch that shows that data refreshed? (6) do the displayed values and the submitted payload come from the same computation?
52
+
53
+ **concurrency: Races and atomicity.** For each changed write path: is every check that the write depends on made inside the same transaction, on a locked row or backed by a constraint whose violation is mapped to the right error? What if two requests overlap, or a delete or deactivate lands between the read and the write? Are multi-step writes (including calls to external services) atomic or recoverable when a later step fails? Is a guard row written before the step it guards can fail?
54
+
55
+ **agreement: Paths that must agree.** For each changed function, query or endpoint: find the other code that does the same job or depends on it (create vs update vs delete, list vs count, preview vs save, client check vs server validation, import vs edit, export vs display, a guard and the join it protects). Do they normalise and compare identifiers the same way (trim, case, padding)? Do they apply the same filters, limits and exclusions (deleted, cancelled, inactive, superseded)? Is a LIMIT or "first match" applied before the exact-match, access or dedupe filter? Does the code read the current row or a stale snapshot, and does an upsert or update overwrite fields it should preserve?
56
+
57
+ **inputs: Inputs, boundaries and failures.** For each changed input and computation: can the schema accept a value the code cannot handle (impossible calendar date, non-canonical format, NaN from `Number()`, over-long string, mutually exclusive params)? Does a truthiness check drop a legitimate `false`, `0` or empty value? Day boundaries and time zones (UTC vs local day, inclusive ranges, multi-day spans), rounding, text-sorted numbers, zero rows or a missing relation? Does a catch or default turn a real failure into a misleading success, or one bad item fail a whole batch?
58
+
59
+ **access: Permissions and exposure.** For each changed endpoint or tool operation: who may call it, and is that enforced on this path and every sibling path (deactivate/reactivate, bulk, export)? Can a caller reach another tenant's or user's rows by passing an id? Is sensitive data written to logs, responses, caches or error messages? Any redirect, URL fetch or generated file (CSV) built from user input?
60
+
61
+ **intent: Does the change do what was asked?** Needs the stated goal: the pull request description and the linked ticket, quoted in full in the brief. Skip this concern when there is neither. List each thing the ticket asks for and each acceptance criterion, then find the code that delivers it. What was asked for and is missing, half done, or done only on one path (create but not edit, the page but not the export)? Does the change do something the ticket did not ask for? Does the approach solve the stated problem, or a narrower or different one (a symptom patched where the cause is elsewhere)? Does a business rule in the code (who qualifies, what is counted, which status allows which action, how an amount is derived) match the rule as the ticket states it, including the cases the ticket names? In place of a failing scenario, each finding quotes the sentence of the ticket and names the code that departs from it.
62
+
63
+ **design: Does the change leave the code easier to change?** Judge the structure the change adds, not style. (1) Deep modules, narrow surface: does each new function, composable, component or endpoint hide a real decision behind a small interface, or is it a thin pass-through whose callers must still know how it works (order of calls, flags that select behaviours, internal shapes leaking through parameters and return values)? Could an export, option or prop be removed because nothing outside needs it? (2) One rule, one owner: is a business rule (who qualifies, what counts, which status allows what) written in several places that must now change together, including once in a component and once on the server, when one module could own it? (3) Does the change add a second way to do something the codebase already has one way to do? (4) Is anything built for a case no caller has (unused options, a generic layer with one user)? (5) Is a concept in the wrong layer (business rule in a component, HTTP details in a domain function)? In place of a failing scenario, each finding names the callers or files affected and the concrete change that would fix it (what to merge, hide, move or delete). Leave out anything that is only a preference. The judge keeps a design finding when the code is as described and the cost named is real for a caller that exists today; these are advice for the author, never a reason to block on their own.
@@ -0,0 +1,29 @@
1
+ # Judging findings
2
+
3
+ A reviewer's findings are claims, not facts. Before any finding is fixed or shown to the user, check it against the code. Do this with fresh eyes: a subagent that has not seen the review being produced, or at least a separate pass in which you look for nothing new.
4
+
5
+ ## Keep a finding only if all five hold
6
+
7
+ 1. **The code is as described.** The cited file and line exist and do what the finding says.
8
+ 2. **A concrete scenario reaches wrong behaviour.** Trace specific values or a sequence of events through the actual code. Look for the guard, lock, constraint, caller or test setup that already prevents it before you keep it.
9
+ 3. **The diff owns it.** The defect is in code the change adds or modifies, or the change newly exposes it (for example it deletes a route that an untouched button still calls). Behaviour that was already there and is untouched goes in a separate "pre-existing" list, not in the review. One exception: when the change adds a claim (a doc sentence, comment, label or test name) that the already-existing behaviour contradicts, the claim is the diff's and the finding is real.
10
+ 4. **It is a defect.** Not style, naming, wording or a preference.
11
+ 5. **It needs no unsupported assumption about deployment.** Several app instances, separate database roles, re-running a migration that is already applied, or code that a later PR in the stack removes: keep the finding only if the repository shows the assumption holds.
12
+
13
+ ## Output
14
+
15
+ For each finding give a verdict and one line of evidence with `file:line`:
16
+
17
+ - **real**: passes all five. Add impact: high (data loss or corruption, a security or permission hole, wrong money or dates, a crash on a normal path), medium (wrong behaviour a user would plausibly hit), low (rare edge, cosmetic consequence, test or doc quality).
18
+ - **pre-existing**: real, but fails rule 3.
19
+ - **wrong**: fails rule 1 or 2. Say what prevents it.
20
+ - **not a defect**: fails rule 4.
21
+ - **unverifiable**: could not be settled from the repository. Say what would settle it.
22
+
23
+ Never drop a finding silently. Every finding gets a verdict the user can read.
24
+
25
+ ## What to do with the verdicts
26
+
27
+ - Fix every real high and medium finding. Fix real low findings when the fix is small and local; otherwise list them.
28
+ - Show the user the wrong, not-a-defect and unverifiable ones in one compact list so they can overrule you.
29
+ - Offer pre-existing findings as follow-up work. Do not fix them in this change.
@@ -24,6 +24,7 @@ cross-links to those rather than restating them.
24
24
  - Anything reactivity-shaped: `computed` vs `watch`, prop→state sync, DOM measurement
25
25
  - You see `watch` and want to know if it should be something else
26
26
  - About to hand-roll a `watch` + lifecycle teardown for a browser API (storage, timers, DOM, listeners, URL) — VueUse likely wraps it
27
+ - Writing a form, dialog or drawer that edits a record, or any component that loads or saves data
27
28
 
28
29
  ## Reference Files
29
30
 
@@ -36,6 +37,8 @@ cross-links to those rather than restating them.
36
37
  - [watch.md](./watch.md) — **`watch` is the escape hatch, not the default**: when it's right, and the four smell shapes (with refactors) found auditing 159 real watchers
37
38
  - [vueuse.md](./vueuse.md) — reach for a VueUse composable before hand-rolling a `watch` + lifecycle teardown for an external-world effect (DOM, timers, storage, URL, listeners); the `@vueuse/nuxt` setup, the watch-sugar functions, and what to keep on Nuxt's own APIs
38
39
  - [template-idioms.md](./template-idioms.md) — duplicate-`@keyup` TS error, `:deep()`/`:slotted()`/`:global()`, click-outside marker class, `NuxtLink`/thin `app.vue`, `useHead`, `v-bind` shorthand, `useId`, `<Teleport>`/`<KeepAlive>`, `v-memo`/`v-once`, file-input reset
40
+ - [async-state.md](./async-state.md) — loading/error/empty as separate states, `refresh()` doesn't throw, success only on success, refreshing every view after a mutation, discarding stale responses (request tokens), one `router.replace`, double-submit and IME guards
41
+ - [editing-forms.md](./editing-forms.md) — forms/dialogs/drawers editing a record: seed on open and id change (or remount with `:key`), reset every transient, don't re-seed on refetch, seed every field and send what changed, selections whose options disappear, URL-mirrored state, reactive clocks
39
42
  - [page-structure.md](./page-structure.md) — keep pages thin: route-param parsing + layout in the page, data/logic/forms in components
40
43
  - [formatters.md](./formatters.md) — never inline a currency/date/number formatter; centralize in `useFormatters`, prefer Intl/date-fns
41
44
 
@@ -53,6 +56,32 @@ instead of testing those pieces as plain Vue functions.
53
56
  5. **Call composables at the top of `<script setup>`** — never inside a callback or a template expression (both lose Nuxt's request scope). Derive display state with `computed`, guarding for possibly-null data.
54
57
  6. **Defer to the right skill.** Fetch/SSR/auth/middleware → `nuxt-nitro-api`. UI components, `pt` styling, color tokens, dark mode → `gallop-ui`. Don't duplicate them here.
55
58
 
59
+ ## The traps reviewers flag most
60
+
61
+ These recur in review findings on components written with this skill loaded. Each
62
+ links to the rule and an example.
63
+
64
+ 1. **Stale local state.** A draft, selection, preview or flag copied from a prop or
65
+ fetched data keeps the previous record's value when the dialog reopens or the id
66
+ changes. Seed on open and on id change (or mount the form only while open, with `:key="record.id"`), and
67
+ reset every transient with it. → [editing-forms.md](./editing-forms.md)
68
+ 2. **Stale async responses.** A request that resolves after the user switched
69
+ record, reopened the dialog, typed again or left overwrites current state. Use
70
+ `useFetch` with a reactive key, or a request token checked after every `await`.
71
+ → [async-state.md](./async-state.md#stale-responses-an-older-request-must-not-overwrite-newer-state)
72
+ 3. **Failures shown as empty or as success.** Render `error` before the empty state
73
+ with a Retry; `refresh()` resolves on failure, so check `error.value` after it;
74
+ emit `saved` and close only on success; reset loading flags in `finally`.
75
+ → [async-state.md](./async-state.md)
76
+ 4. **Other views not refreshed after a mutation.** Share one keyed fetch or refresh
77
+ every list showing the changed data. → [async-state.md](./async-state.md#refresh-every-view-of-the-data-you-changed)
78
+ 5. **The same rule computed twice.** Filters vs counts vs labels, preview vs action,
79
+ button state vs message: one helper, every consumer. → [component-authoring.md](./component-authoring.md#one-rule-one-helper)
80
+ 6. **Keyboard and copy gaps.** Clickable non-buttons, unfocusable tooltip triggers,
81
+ icon buttons with no name, "0 items" sentences. → [template-idioms.md](./template-idioms.md#keyboard-and-screen-reader-access-for-custom-controls)
82
+ 7. **Double submit.** Guard every mutating handler with an in-flight flag, not just
83
+ `:disabled`; ignore IME-confirm Enter. → [async-state.md](./async-state.md#double-submit)
84
+
56
85
  ## Contributing Back
57
86
 
58
87
  If you hit a Vue-in-Nuxt authoring gotcha this skill doesn't cover (or one it gets