agentscamp 0.1.0

package/content/commands/benchmark-rerankers.md

@@ -0,0 +1,44 @@
+---
+description: "Measure whether adding a reranker actually improves retrieval, by scoring reranked vs. un-reranked results on a labeled query set."
+argument-hint: "<path to eval set / retrieval results, or a description of the pipeline>"
+allowed-tools: "Read, Grep, Glob, Bash"
+model: sonnet
+---
+
+## Scope
+
+Treat `$ARGUMENTS` as the retrieval setup to benchmark — a path to an eval set and retrieval results, or a description of the pipeline (retriever, candidate count, reranker). Restate what you're comparing in one sentence before running.
+
+Goal: quantify the lift a **reranker** adds over first-stage retrieval, so the decision to ship it (and pay its latency/cost) is measured, not assumed.
+
+> [!NOTE]
+> A reranker reorders candidates the retriever already found — it cannot recover an answer that first-stage retrieval missed. So always over-retrieve (top-25–50) before reranking, and measure recall at the **first stage** too.
+
+## Step 1 — Establish the eval set
+
+Use a labeled set of queries with known-relevant passages (gold spans). If none exists, say so and help build a small one (20–50 queries) before benchmarking — a benchmark without ground truth is theater.
+
+## Step 2 — Produce two result sets
+
+For each query, capture the **top-k before reranking** (raw retriever order) and the **top-k after reranking** (e.g. via [Cohere Rerank](/tools/cohere-rerank) or another cross-encoder), over the same candidate pool.
+
+## Step 3 — Score both
+
+Compute, for k ∈ {3, 5, 10}:
+
+- **recall@k** — fraction of queries with a gold passage in the top-k.
+- **nDCG@k** — rank-aware quality (rewards putting the right passage higher).
+- **MRR** — mean reciprocal rank of the first gold passage.
+
+Report a side-by-side table: metric | retriever-only | + reranker | delta.
+
+## Step 4 — Weigh the cost
+
+State the added **per-query latency** and **cost** of the rerank call. Reranking only the top candidates keeps both modest, but make the trade-off explicit.
+
+## Step 5 — Recommend
+
+Give a clear verdict: ship the reranker, skip it, or change candidate depth / rerank model. Justify it from the numbers — e.g. "+0.14 nDCG@5 for +90ms is worth it" or "negligible lift, not worth the latency here."
+
+> [!WARNING]
+> Don't tune the reranker against the same handful of queries you eyeball. Use the frozen eval set, and report all metrics, not just the one that improved.

package/content/commands/breakdown-task.md

@@ -0,0 +1,86 @@
+---
+description: "Decompose a task into an ordered checklist of small, verifiable steps."
+argument-hint: "<task>"
+allowed-tools: "Read, Grep, Glob"
+---
+
+Break the task in `$ARGUMENTS` into the smallest sensible, dependency-ordered steps and return them as a Markdown checklist. This is a planning pass only — read the code to ground the plan, but do not edit, run, or create any files.
+
+## Scope
+
+Treat `$ARGUMENTS` as the task to decompose — a feature request, a bug, a refactor, or a migration ("add rate limiting to the login route", "split the `Invoice` model into separate billing tables"). If it names files, paths, or symbols, those are your starting points for investigation.
+
+If `$ARGUMENTS` is empty, do not guess. Ask the user what task they want broken down, and stop until they answer.
+
+## Step 1 — Ground the task in the code
+
+Read enough of the repo to plan against reality, not assumptions. Find the files the task touches and the seams it crosses before you split anything.
+
+```bash
+# Locate the symbols, routes, or modules named in the task
+grep -rn "loginHandler" src/
+
+# Map the surrounding structure
+find src -path '*auth*' -name '*.ts'
+```
+
+Open the entry points and trace one level of callers and callees. Note existing tests, types, and config that the change will ripple into.
+
+> [!NOTE]
+> If the task as written is ambiguous or hides a decision (which library? sync or async? backward-compatible?), surface that as an open question in the output instead of silently picking one. A plan built on a wrong assumption wastes the whole execution pass.
+
+## Step 2 — Split into the smallest sensible steps
+
+Cut the work into steps that are each independently verifiable and small enough to land as one focused commit. A good step changes one thing and can be checked on its own.
+
+Aim for steps that are:
+
+- **Atomic** — one concern each (add the schema; *then* wire the endpoint; *then* the test).
+- **Verifiable** — you can state a concrete check that proves it is done.
+- **Reversible** — a step that turns out wrong can be redone without unwinding the others.
+
+Avoid two failure modes: steps so coarse they hide three decisions, and steps so fine they fragment a single edit across five lines.
+
+> [!TIP]
+> Lead with the steps that de-risk the work — the unknown, the spike, the schema or interface everything else depends on. Settled, mechanical steps come last.
+
+## Step 3 — Order by dependency and mark parallelism
+
+Sort the steps so each one only depends on steps above it. For every step, record what it needs and whether anything blocks it.
+
+Then mark which steps are independent and can run in parallel — steps that share no inputs and touch no common files. Group them so the executor (or multiple agents) can fan them out.
+
+```text
+1. Define rate-limit config + types        (no deps)
+2. Add Redis-backed counter store          (depends on 1)
+3. Wire middleware into login route         (depends on 2)
+4. Update API docs                          (depends on 1)   [parallel with 2–3]
+5. Add tests for limit + reset window       (depends on 3)
+```
+
+> [!WARNING]
+> Two steps are only safe to parallelize if they do not edit the same files and neither reads the other's output. When in doubt, serialize — a false "parallel" tag causes merge conflicts and rework that costs more than the time saved.
+
+## Step 4 — Define done for each step and overall
+
+Give every step a one-line **definition of done** — a concrete, checkable condition, not a restatement of the step ("tests pass for the reset window", not "tests are done"). Then write one overall definition of done for the whole task: the observable end state that means the work is complete.
+
+## Output format
+
+Return a single Markdown checklist. Number the steps in execution order, tag parallel-eligible ones, and end each with its definition of done.
+
+```markdown
+## Plan — <task>
+
+- [ ] **1. Define rate-limit config + types** — _done when_ `RateLimitConfig` exists and is imported by the middleware.
+- [ ] **2. Add Redis-backed counter store** — _done when_ `increment`/`reset` are covered by unit tests.
+- [ ] **3. Wire middleware into login route** — _done when_ a 6th request in the window returns `429`.
+- [ ] **4. Update API docs** _(parallel with 2–3)_ — _done when_ the docs describe the limit, window, and reset header.
+- [ ] **5. Add tests for limit + reset window** — _done when_ `npm test` passes for the new cases.
+
+**Definition of done (overall):** Login enforces N requests/window per IP, returns `429` with a reset header past the limit, and is documented and tested.
+
+**Open questions:** <anything that needs a decision before step 1 — or "none">
+```
+
+Keep the plan tight: enough steps to be unambiguous, never so many that the checklist becomes noise. Do not begin executing — hand the checklist back to the user.

package/content/commands/commit.md

@@ -0,0 +1,117 @@
+---
+description: "Stage changes and write a Conventional Commits message describing them."
+---
+
+Create a well-formed git commit for the current changes. Follow the steps below exactly, and only commit what the user intends.
+
+## Scope
+
+If `$ARGUMENTS` is provided, treat it as guidance for what to commit — for example specific paths to stage (`src/lib/auth.ts`), a hint about the change type (`fix`, `feat`), or a short description of intent. If `$ARGUMENTS` is empty, infer everything from the working tree.
+
+## Step 1 — Inspect the working tree
+
+Run these in parallel and read the output before doing anything else.
+
+```bash
+git status
+git diff
+git diff --staged
+git log --oneline -10
+```
+
+- `git status` shows what is staged, unstaged, and untracked.
+- `git diff` / `git diff --staged` reveal the actual content of the changes — read these to understand what happened, not just file names.
+- `git log --oneline -10` shows the repository's existing message style. Match its tone and format where it does not conflict with the rules below.
+
+## Step 2 — Stage the right files
+
+Stage only files that belong in this commit.
+
+```bash
+# Stage specific paths derived from $ARGUMENTS or your analysis
+git add src/lib/auth.ts src/lib/session.ts
+
+# Or stage everything when all changes are part of one logical unit
+git add -A
+```
+
+> [!WARNING]
+> Do not blindly `git add -A` if the diff mixes unrelated work. Split unrelated changes into separate commits so history stays reviewable.
+
+> [!NOTE]
+> Never stage secrets, credentials, `.env` files, large build artifacts, or local-only config. If you see any in `git status`, stop and flag them to the user instead of committing.
+
+## Step 3 — Write the message
+
+Write a [Conventional Commits](https://www.conventionalcommits.org/) message:
+
+```
+<type>(<optional scope>): <short summary>
+
+<optional body explaining what and why>
+
+<optional footer: BREAKING CHANGE / issue refs>
+```
+
+### Rules for the subject line
+
+- Use one of these `type` values:
+
+| type | use for |
+| --- | --- |
+| `feat` | a new feature |
+| `fix` | a bug fix |
+| `docs` | documentation only |
+| `style` | formatting, no logic change |
+| `refactor` | code change that is neither a fix nor a feature |
+| `perf` | performance improvement |
+| `test` | adding or fixing tests |
+| `build` | build system or dependencies |
+| `ci` | CI configuration |
+| `chore` | maintenance, tooling, misc |
+
+- Keep the summary in the imperative mood ("add", not "added" or "adds").
+- Lower-case the summary and omit the trailing period.
+- Keep the subject line at or under 72 characters.
+
+### Rules for the body
+
+- Add a body only when the change needs explanation. Wrap lines at ~72 characters.
+- Explain the *why* and the user-facing or behavioral impact — the diff already shows the *how*.
+- For a breaking change, add a `BREAKING CHANGE:` footer describing the migration.
+
+### Example
+
+```
+feat(auth): add refresh-token rotation
+
+Issue short-lived refresh tokens and rotate them on every use to
+limit the blast radius of a leaked token. Old tokens are revoked
+on rotation.
+
+Closes #142
+```
+
+## Step 4 — Commit and verify
+
+Use a HEREDOC so multi-line messages render correctly.
+
+```bash
+git commit -m "$(cat <<'EOF'
+feat(auth): add refresh-token rotation
+
+Issue short-lived refresh tokens and rotate them on every use.
+
+Closes #142
+EOF
+)"
+```
+
+Then confirm the result:
+
+```bash
+git status
+git log -1 --stat
+```
+
+Report the final commit hash and subject line. Do not push unless the user explicitly asks.

package/content/commands/create-pr.md

@@ -0,0 +1,109 @@
+---
+description: "Push the current branch and open a GitHub pull request with a generated title and body."
+argument-hint: "[base branch or notes]"
+allowed-tools: "Bash"
+---
+
+Open a GitHub pull request for the current branch. Follow the steps below exactly. Push the branch if needed, but do not merge, and confirm the base branch before you create anything.
+
+## Scope
+
+If `$ARGUMENTS` is provided, treat it as the base branch to target (`develop`, `release/2.0`) and/or freeform notes to weave into the body — for example a hint about scope (`backend only`), an issue to close (`Closes #214`), or a reviewer to request. If `$ARGUMENTS` is empty, default the base to the repository's main branch and derive the entire title and body from the commits and diff.
+
+## Step 1 — Inspect the branch and confirm the base
+
+Run these in parallel and read the output before doing anything else.
+
+```bash
+# Current branch name and where HEAD sits relative to its upstream
+git status -sb
+
+# The repository's default branch (use as the base when none is given)
+gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name'
+
+# Commits unique to this branch, oldest first
+git log <base>..HEAD --oneline
+
+# The full diff against the base
+git diff <base>...HEAD --stat
+git diff <base>...HEAD
+```
+
+Substitute the real base (`$ARGUMENTS` or the default branch) for `<base>`. The `...` (three-dot) range shows what this branch adds since it diverged, which is exactly what the PR will contain.
+
+> [!NOTE]
+> Confirm the base branch with the user before creating the PR. Targeting the wrong base (e.g. `main` instead of `develop`) is the most common and most disruptive mistake. If you defaulted to the repo's main branch, say so explicitly.
+
+> [!WARNING]
+> If `git log <base>..HEAD` is empty, the branch has no new commits and there is nothing to open a PR for. Stop and tell the user instead of creating an empty PR.
+
+## Step 2 — Ensure the branch is pushed
+
+The remote must have your commits before a PR can reference them.
+
+```bash
+# Push and set the upstream on first push; the branch name is inferred from HEAD
+git push -u origin HEAD
+```
+
+> [!WARNING]
+> Only push the current feature branch. Never force-push (`--force`) a shared branch or push to `main`/`develop` directly. If `git status -sb` shows the branch is already up to date with its upstream, skip this step.
+
+## Step 3 — Derive the title and body
+
+Read the commits and diff from Step 1, then synthesize the PR content. Do not just paste commit messages — describe the change as a whole.
+
+**Title** — one concise, imperative line (matching the commit style), at or under ~72 characters. For a single-commit branch, the commit subject is usually a good title.
+
+**Body** — fill in this structure, using your reading of the diff:
+
+```markdown
+## Summary
+<1-3 sentences on what this PR does and why.>
+
+## Changes
+- <key change, grouped by area or concern>
+- <another notable change>
+
+## Testing
+- <how it was verified: tests added/run, manual steps, or "not yet tested">
+
+## Risk
+- <blast radius, migrations, rollback notes, or "low — isolated change">
+```
+
+> [!WARNING]
+> Do not include secrets, tokens, internal URLs, or customer data in the title or body — a PR description is public to everyone with repo access. Summarize sensitive context instead of pasting it.
+
+## Step 4 — Create the pull request
+
+Pass the body via a HEREDOC so multi-line Markdown renders correctly.
+
+```bash
+gh pr create \
+  --base "<base>" \
+  --head "$(git branch --show-current)" \
+  --title "<generated title>" \
+  --body "$(cat <<'EOF'
+## Summary
+<1-3 sentences on what this PR does and why.>
+
+## Changes
+- <key change, grouped by area or concern>
+- <another notable change>
+
+## Testing
+- <how it was verified: tests added/run, manual steps, or "not yet tested">
+
+## Risk
+- <blast radius, migrations, rollback notes, or "low — isolated change">
+EOF
+)"
+```
+
+> [!NOTE]
+> Add `--draft` if the work is not ready for review, and `--reviewer <user>` or `--label <label>` when the user asks. Do not merge the PR — opening it is the end of this command.
+
+## Report
+
+Print the URL that `gh pr create` returns, plus the resolved base branch and the number of commits included so the user can confirm the PR landed where they expected. If anything blocked creation (no commits, dirty tree, unconfirmed base), report that instead of forcing the PR open.

package/content/commands/db-migrate.md

@@ -0,0 +1,47 @@
+---
+description: "Generate and apply a database migration the safe way — using the project's migration tool, with expand-contract discipline for breaking changes, lock-free DDL, and a reversible up/down."
+argument-hint: "<the schema change to make, or a path to a pending migration to review>"
+allowed-tools: "Read, Grep, Glob, Bash, Edit"
+model: sonnet
+---
+
+## Scope
+
+Treat `$ARGUMENTS` as the schema change to make (e.g. "add a `status` column to `orders`", "rename `user.name` to `full_name`") or a path to a pending migration to review. Restate the change and whether it's **additive** (safe) or **breaking** (needs expand-contract) in one sentence before writing anything.
+
+Goal: produce a migration that's **safe on a live database** — uses the project's migration tool, avoids long locks, and is reversible — not a hand-run `ALTER` that locks a hot table mid-deploy.
+
+> [!NOTE]
+> This command writes and applies a migration with safe-migration discipline. For a brand-new pgvector schema specifically, use [Scaffold a pgvector Schema](/commands/db/scaffold-pgvector-schema); for planning a large, multi-step breaking change end to end, hand off to the [postgres-migration-engineer](/agents/data-ai/postgres-migration-engineer).
+
+## Step 1 — Detect the migration tool
+
+Find the project's migration framework (Prisma, Drizzle, Alembic, Flyway, golang-migrate, Rails, Knex, …) and match its file naming, format, and up/down conventions. Never hand-run DDL outside the tool that owns the schema. If [pgroll](/tools/pgroll) is in use, generate its JSON migration instead.
+
+## Step 2 — Classify the change
+
+Decide if the change is **additive** (new nullable column, new table, new index — safe to apply directly) or **breaking** (rename, retype, `NOT NULL`, drop, new constraint on existing data). Breaking changes on a table with real data/traffic must be decomposed.
+
+## Step 3 — Decompose breaking changes (expand-contract)
+
+For a breaking change, split it into separate, reversible migrations: **expand** (additive) → **backfill** (batched) → **dual-write** (app) → **migrate reads** (app) → **contract** (drop old, a later release). Don't collapse add and remove into one migration. See [Zero-Downtime Postgres Migrations](/guides/database/zero-downtime-postgres-migrations).
+
+## Step 4 — Use lock-free DDL
+
+Substitute online operations for the ones that lock:
+
+- `CREATE INDEX CONCURRENTLY` (not plain `CREATE INDEX`).
+- `ADD CONSTRAINT … NOT VALID` then `VALIDATE CONSTRAINT` (not a constraint that scans under lock).
+- Add columns nullable with a **constant** default (a volatile default rewrites the table).
+- Batched, resumable backfills (never one giant `UPDATE`).
+
+## Step 5 — Make it reversible
+
+Write the `down`/rollback for the migration (or confirm the tool generates a correct one). For expand-contract, ensure the old path survives until the contract step, so any phase can be rolled back without data loss.
+
+## Step 6 — Plan, apply, verify
+
+Show the SQL the tool will run (a dry-run/plan where supported) and call out any statement that would take an `ACCESS EXCLUSIVE` lock. Apply it, then verify: the migration recorded, a `CONCURRENTLY`-built index is `VALID`, and the schema matches intent.
+
+> [!WARNING]
+> The migrations that cause outages take a long lock or rewrite a large table: a plain `CREATE INDEX`, `SET NOT NULL` directly, an `ALTER TYPE` rewrite, a volatile-default column add, or a single huge `UPDATE`. If the change implies any of these on a table with data, stop and decompose it before applying.

package/content/commands/explain-code.md

@@ -0,0 +1,71 @@
+---
+description: "Explain what the given code does, in clear prose with a short summary."
+argument-hint: "[file or symbol]"
+---
+
+Explain the code identified by `$ARGUMENTS`. The argument may be a file path, a function or class name, a module, or a line range. Produce an explanation that a teammate could read once and understand without opening the source themselves.
+
+## Locate the target
+
+Resolve `$ARGUMENTS` before explaining anything.
+
+- If it is a path (e.g. `src/auth/session.ts`), read that file.
+- If it is a symbol (e.g. `validateToken` or `class UserStore`), search the codebase to find its definition, then read the surrounding context.
+- If it is a path with a range (e.g. `parser.go:40-120`), read those lines plus enough above and below to understand the scope.
+- If it is ambiguous or matches multiple results, list the candidates and ask which one is meant. Do not guess.
+
+> [!NOTE]
+> Read the actual source before writing a single word of explanation. Never describe code from the name alone.
+
+## Understand before you write
+
+Trace the behavior, not just the syntax. Before drafting, work out:
+
+- The **purpose**: what problem this code solves and who calls it.
+- The **inputs**: parameters, arguments, environment, or global state it reads.
+- The **outputs**: return values, mutations, writes, network calls, or thrown errors.
+- The **control flow**: branches, loops, early returns, and the happy path versus edge cases.
+- The **dependencies**: other functions, modules, or services it relies on.
+- Any **non-obvious details**: concurrency, caching, side effects, or subtle correctness concerns.
+
+## Output format
+
+Structure the response with these sections.
+
+### Summary
+
+Two or three sentences in plain language stating what the code does and why it exists. A reader should be able to stop here and have the gist.
+
+### How it works
+
+Walk through the logic in execution order. Use prose for the narrative and a short list for distinct steps. Quote only the small, load-bearing fragments that matter — do not paste the whole file back.
+
+```text
+1. Receives <input> and validates <condition>.
+2. Transforms it via <step>.
+3. Returns <output> or raises <error> when <edge case>.
+```
+
+### Inputs and outputs
+
+Be precise about types and contracts.
+
+| Aspect | Detail |
+| --- | --- |
+| Inputs | parameters, types, expected shape |
+| Returns | return type and meaning |
+| Side effects | I/O, mutations, network, logging |
+| Errors | what is thrown or returned on failure |
+
+### Edge cases and gotchas
+
+Call out anything surprising: silent failure modes, off-by-one risks, assumptions about input, thread safety, or behavior that contradicts the function name.
+
+## Guidelines
+
+- Match the explanation's depth to the code's complexity. A three-line helper needs a sentence; a state machine needs the full breakdown.
+- Use the project's own terminology — variable and domain names as they appear in the source.
+- Prefer correctness over completeness. If you are unsure how something behaves, say so explicitly rather than inventing an explanation.
+
+> [!WARNING]
+> Do not modify the code. This command only explains. If you spot a bug while reading, mention it in the gotchas section but make no edits.

package/content/commands/explain-error.md

@@ -0,0 +1,98 @@
+---
+description: "Diagnose an error message or stack trace and propose a fix."
+argument-hint: "<error message or stack trace>"
+allowed-tools: "Read, Grep, Glob, Bash"
+---
+
+Diagnose the error in `$ARGUMENTS` against this codebase and propose a specific fix. Your job is to explain *why* it happens and *how* to fix it — not to restate the message back. Do not change any files; report your findings and the recommended fix.
+
+## Scope
+
+`$ARGUMENTS` is the raw error to diagnose — an exception message, a stack trace, a compiler/type error, or a chunk of failing log output. Parse it for the signal that matters:
+
+- The **error type/class** and message (`TypeError`, `NullPointerException`, `ECONNREFUSED`, `error[E0382]`, ...).
+- The **top in-repo frame** — the first stack frame pointing at a file *in this project*, not in `node_modules`, the standard library, or a vendored dependency. That frame is usually where the fix lives.
+- Any **identifiers** in the message: variable names, function names, file paths, line numbers, error codes.
+
+If `$ARGUMENTS` is empty, do not guess. Ask the user to paste the full error or stack trace, or point you at the failing command (e.g. `npm test`, `cargo build`) so you can reproduce it and capture the output yourself.
+
+## Step 1 — Locate the originating code
+
+Find the exact line the error blames, then read enough around it to understand the context.
+
+```bash
+# Jump to the file:line from the top in-repo stack frame
+# e.g. "at src/lib/auth.ts:42" -> open that file around line 42
+```
+
+When the trace is minified, transpiled, or points at a build artifact, search for the symbols in the message instead:
+
+```bash
+# Find where the named function / variable / message string is defined
+rg -n "functionFromTheTrace|the exact error string" src
+```
+
+> [!NOTE]
+> Trust the *first in-repo frame*, not the last frame. The deepest frame is often inside a library doing exactly what it was told — the bug is usually at the boundary where your code called it with bad input.
+
+## Step 2 — Identify the likely root cause
+
+Explain in plain terms what actually went wrong, one level beneath the message. Map the error to its underlying condition rather than echoing the text:
+
+| The message says | The real cause is usually |
+| --- | --- |
+| `Cannot read properties of undefined` | a value was never assigned, an async result wasn't awaited, or a lookup missed |
+| `NullPointerException` / `nil` deref | an unchecked optional or a failed-but-ignored return |
+| `ECONNREFUSED` / `connection refused` | wrong host/port, service not running, or env var unset |
+| `Module not found` | missing dependency, bad import path, or stale build cache |
+| type / borrow / lint error | a contract the compiler is enforcing — read it literally |
+
+State the cause as a single clear sentence: *"`session` is `undefined` here because `getSession()` returns a Promise that the caller never awaits, so the `.user` access runs before it resolves."*
+
+## Step 3 — Confirm before you commit to an answer
+
+When practical, verify the hypothesis instead of asserting it. Use read-only checks only.
+
+```bash
+# Re-run the failing command to confirm the error and see the full trace
+npm test 2>&1 | tail -40
+
+# Inspect runtime conditions the trace implies (env, service, versions)
+# prints key names only — omit `cut -d= -f1` if you need the values
+printenv | cut -d= -f1 | rg -i 'DATABASE|API|PORT'
+```
+
+> [!NOTE]
+> Reproduce or confirm the cause with a read-only command whenever it's cheap to do so — a confirmed diagnosis beats a plausible one.
+
+> [!WARNING]
+> Stay read-only. Do not run migrations, installs, formatters, or anything that mutates the repo, the database, or remote state to "test" a theory. Confirm by reading and by re-running the same failing command, nothing more.
+
+## Step 4 — Report the diagnosis and fix
+
+When the cause is clear, report it directly:
+
+```markdown
+## Error: <error type — one-line summary>
+
+**Origin:** `path/to/file.ts:42` — <what this line was doing>
+
+**Root cause:** <the plain-terms why, one level below the message>
+
+**Fix:** <the specific change — code, not vibes>
+
+    - const user = getSession().user;
+    + const user = (await getSession()).user;
+
+**Confidence:** High — reproduced via `npm test`; the trace points squarely here.
+```
+
+When the cause is **ambiguous**, list the top candidates ranked by likelihood, each with the evidence for it and the one-line check that would confirm or rule it out:
+
+```markdown
+**Most likely (≈70%):** <cause> — confirm with `<read-only check>`
+**Possible (≈20%):** <cause> — confirm with `<read-only check>`
+**Long shot (≈10%):** <cause> — confirm with `<read-only check>`
+```
+
+End with the single highest-value next step: the fix to apply, or the one check that collapses the remaining ambiguity.