agentscamp 0.1.0 → 0.2.0

package/content/commands/git-bisect.md

@@ -0,0 +1,126 @@
+---
+description: "Drive git bisect to find the exact commit that introduced a regression."
+argument-hint: "<bug description; optional good and bad refs>"
+allowed-tools: "Bash, Read"
+---
+
+Find the commit that introduced the regression described in `$ARGUMENTS` using `git bisect`. The binary search is only as trustworthy as the test you feed it, so the first job is a rock-solid reproduction — not running `git bisect start`.
+
+## Scope
+
+Parse `$ARGUMENTS` into three parts:
+
+- **Bug description** — the observable regression (a failing test, a wrong output, a crash). Required.
+- **Bad ref** — a commit where the bug is present. Defaults to `HEAD`.
+- **Good ref** — a commit where the bug is absent (e.g. the last release tag `v2.3.0`, or `HEAD~200`). If not given, you will hunt for one in Step 3.
+
+If `$ARGUMENTS` is empty, ask one question and stop: *"What is the regression, and do you know a commit/tag where it still worked?"* Do not invent a bug or guess refs — a wrong good/bad boundary makes bisect confidently point at the wrong commit.
+
+> [!WARNING]
+> Bisect checks out historical commits, which discards uncommitted work and may break the build. Before starting, run `git status` and confirm the tree is clean. If it is not, tell the user to commit or stash first — do not stash on their behalf.
+
+## Step 1 — Build a fast, deterministic reproduction
+
+This is the make-or-break step. Distill the bug into a single command that exits **0 when the code is good** and **non-zero when it is bad**.
+
+- Prefer the narrowest, fastest signal: one unit test (`npm test -- path/to.test.ts -t "name"`, `pytest -k name -q`), a focused script, or a one-line `grep` over program output. Bisect runs this command ~log2(N) times, so a 2-minute build over 500 commits is ~18 minutes — trim it.
+- Run the command on the **bad ref first** and confirm it fails. Then mentally verify it would pass on good code. If you cannot make it fail on the known-bad ref, you do not yet have a reproduction — stop and refine.
+
+> [!WARNING]
+> A flaky reproduction poisons the entire bisect. If the test passes and fails non-deterministically (timing, network, random seeds, shared state, leftover DB rows), bisect will mislabel commits and blame the wrong one. Pin seeds, isolate state, and run the repro 3-5 times on the bad ref — it must fail **every** time before you continue.
+
+## Step 2 — Confirm the bad ref
+
+By default `HEAD` is bad. Verify it:
+
+```bash
+git status                 # tree must be clean
+git rev-parse HEAD         # record the bad ref so you can return to it
+<your repro command>       # must exit non-zero (bug reproduces)
+```
+
+## Step 3 — Establish a good ref
+
+You need a commit where the repro **passes**. If `$ARGUMENTS` named one, check it out and verify; otherwise walk backward to find one.
+
+```bash
+git checkout v2.3.0        # or a suspected-good tag / older commit
+<your repro command>       # must exit 0 here
+git checkout -             # return to the bad ref
+```
+
+If the candidate still fails, go further back (`HEAD~100`, then `HEAD~400`) until the repro passes. Pick the *most recent* known-good commit you can — a tighter `[good, bad]` window means fewer steps.
+
+## Step 4 — Start the bisect
+
+```bash
+git bisect start
+git bisect bad HEAD        # or your explicit bad ref
+git bisect good v2.3.0     # the good ref you confirmed in Step 3
+```
+
+Git now checks out a commit roughly halfway between them and reports how many steps remain.
+
+## Step 5 — Drive the search (prefer automation)
+
+**Preferred — automate it.** Hand bisect the repro command and let it run unattended:
+
+```bash
+git bisect run <your repro command>
+```
+
+The exit-code contract `git bisect run` relies on:
+
+| Exit code | Meaning to bisect |
+| --- | --- |
+| `0` | this commit is **good** |
+| `1`–`124`, `126`, `127` | this commit is **bad** |
+| `125` | **skip** — cannot be tested (won't build, deps changed) |
+
+> [!NOTE]
+> Use exit `125` for commits you cannot evaluate — e.g. a build failure unrelated to the bug. Wrap the repro in a script that builds first and `exit 125` on build failure, then runs the test: that keeps unbuildable commits from being misjudged as bad. Bisect will route around skipped commits and may report a small range instead of a single culprit.
+
+**Manual fallback.** If the repro needs human judgment, evaluate each checked-out commit yourself and mark it:
+
+```bash
+git bisect good            # repro passed at this commit
+git bisect bad             # repro failed at this commit
+git bisect skip            # cannot test this one
+```
+
+Repeat until git prints `<sha> is the first bad commit`.
+
+## Step 6 — Inspect the culprit and explain the cause
+
+Once the first bad commit is identified, read it before declaring victory:
+
+```bash
+git show <sha>             # full diff + message
+git show <sha> --stat      # files touched, for a quick map
+```
+
+Read the actual diff (use the Read tool to open the changed files at that revision if needed) and connect a specific line or hunk to the observed regression. Do not just report the SHA — explain *why* that change causes the bug.
+
+## Step 7 — Always reset
+
+Bisect leaves the repo on a detached historical commit. Restore the original state:
+
+```bash
+git bisect reset           # returns to the branch/ref you started from
+git status                 # confirm the tree is back to normal
+```
+
+> [!WARNING]
+> Never leave a bisect session open. If you stop early or hit an error, run `git bisect reset` before doing anything else, or the user will be stranded on a detached HEAD with a half-finished search log.
+
+## Report
+
+Deliver, as your message:
+
+1. **First bad commit** — SHA, short message, author, and date.
+2. **Root cause** — the specific change in that commit that introduced the regression, tied to the bug in `$ARGUMENTS`.
+3. **Confidence** — note any `skip`ped commits or a returned range that widens the result.
+4. **Reproduction used** — the exact command, so the finding is repeatable.
+5. **Suggested fix or next step** — e.g. revert the commit, patch the offending hunk, or open an issue.
+
+Confirm you ran `git bisect reset` and the working tree is clean before finishing.

package/content/commands/rename-symbol.md

@@ -0,0 +1,131 @@
+---
+description: "Safely rename a symbol project-wide, distinguishing the real symbol from coincidental substring matches."
+argument-hint: "<oldName> <newName>"
+allowed-tools: "Read, Grep, Glob, Edit, Bash"
+---
+
+Rename a code symbol — a function, class, method, variable, type, interface, enum, or constant — everywhere it appears, so the project compiles and behaves exactly as before under the new name. This is a precision refactor: the danger is not finding too few matches, it is changing too many.
+
+## Scope
+
+Parse `$ARGUMENTS` as exactly two tokens: the **old name** then the **new name**.
+
+- `getUserById fetchUserById` → rename `getUserById` to `fetchUserById`.
+- If only one token is given, or the two are identical, ask for the missing piece. Do not invent the target name.
+- If `$ARGUMENTS` is empty, ask: *"Which symbol should I rename, and to what?"* and stop.
+
+If the old name is **ambiguous** — it resolves to more than one distinct symbol (e.g. a local `id` in three unrelated functions, or a `Status` type and a `Status` enum) — list the candidates with their file and line and ask which one. Renaming the wrong binding is worse than renaming nothing.
+
+> [!WARNING]
+> This is behavior-preserving. Rename only — do not change the symbol's type, signature, value, or call order, and do not "improve" code you pass through. A rename that needs a test assertion changed is a rename that broke something.
+
+## Step 1 — Find and read the definition
+
+Locate where the symbol is **defined**, not just used. The definition tells you its kind (function/class/type/const), its scope (module-level, class member, block-local), and whether it is exported.
+
+```bash
+# Anchor on word boundaries so `getUser` does not match `getUserById`
+rg -nw "getUserById" --type-add 'src:*.{ts,tsx,js,jsx,py,go,rs,java}' -tsrc
+
+# Narrow to likely definition sites
+rg -nw "(function|const|let|class|interface|type|enum|def|fn|public|private)\s+getUserById"
+```
+
+Read the definition and its immediate surroundings. Establish three facts before editing anything:
+
+1. **Kind** — function, class, type, variable, etc. (affects where else the name can legally appear).
+2. **Scope** — is this name unique in the project, or shadowed/reused in other scopes?
+3. **Export surface** — is it exported? Re-exported through a barrel/index file? Part of the public API?
+
+## Step 2 — Separate the real symbol from coincidental matches
+
+This is the core of the command and where naive renames fail. A raw text match for the old name will hit three categories — you must keep only the first.
+
+- **The symbol itself** — keep. Same binding, in scope.
+- **A different symbol with the same name** — skip. A local `count` in another function, a `Status` from another module. Same characters, unrelated binding.
+- **A substring of an unrelated identifier** — skip. `user` inside `username`, `userId`, `getUser`, `superuser`.
+
+> [!WARNING]
+> Never run an unanchored find-and-replace. `s/user/account/g` rewrites `username`, `currentUser`, and `userId` and is almost impossible to fully undo. Always match whole words (`rg -w`, `\b…\b`) and, when the name is common, confirm each hit resolves to the binding you read in Step 1 — by scope, import source, or the object/class it hangs off.
+
+For methods and fields accessed via `.`, scope the match to the receiver's type. Renaming a `save` method on `OrderRepo` must not touch `save` on every other object in the codebase. Read the call to confirm the receiver before editing.
+
+## Step 3 — Build the reference list
+
+Sweep for every legitimate occurrence and group it by category so nothing is missed:
+
+```bash
+# All whole-word occurrences, with file:line for review
+rg -nw "getUserById"
+
+# Imports / exports / barrel re-exports that name it
+rg -nw "getUserById" -g '*.{ts,js}' -g '!**/*.test.*' | rg "import|export|require|from"
+
+# Tests, fixtures, and snapshots referencing it
+rg -nw "getUserById" -g '*{test,spec}*' -g '*__snapshots__*'
+
+# Docs, comments, and string literals (rename only if the string is the identifier, e.g. a DI token or route name)
+rg -nw "getUserById" -g '*.{md,mdx}'
+```
+
+Decide string-literal cases deliberately: a DI token, event name, GraphQL field, or serialized key that must stay wire-compatible should usually **not** change even if it spells the old name — changing it is a behavior change, not a rename. Comments and docstrings that describe the symbol **should** change.
+
+## Step 4 — Prefer language tooling, then verify by hand
+
+If the project has language-server rename available, use it — it understands scope and won't touch substrings:
+
+```bash
+# TypeScript / JS via ts-morph or the language server's rename
+# Rust:    cargo fix is not a rename; use rust-analyzer rename in-editor
+# Go:      gopls rename -w 'path/file.go:#offset' 'newName'
+# Python:  rope / pyright rename
+gopls rename -w "./internal/user/service.go:#1423" "fetchUserById"
+```
+
+> [!NOTE]
+> Language tooling is the safe default, but it is not the final word. After any automated rename, run the Step 2 grep sweep again for the **old** name — stray hits in comments, generated files, string templates, or tooling-excluded paths are exactly what the language server skips.
+
+If no rename tool fits, apply edits with `Edit` one occurrence at a time from your Step 3 list, never with `replace_all` on a bare word that could appear in other scopes.
+
+## Step 5 — Apply the edits
+
+Edit each occurrence from the reference list. Keep edits surgical: change only the identifier token, leave surrounding whitespace, types, and arguments untouched. Update declaration, every call/reference, imports, exports/barrels, tests, and descriptive comments together so the tree never sits half-renamed.
+
+## Step 6 — Rename the file if it encodes the name
+
+If the symbol's name is baked into a filename — `UserService.ts` for `class UserService`, `use_auth.py` for `use_auth` — rename the file and fix the import paths:
+
+```bash
+git mv src/services/UserService.ts src/services/AccountService.ts
+# then update every importer
+rg -nw "services/UserService"
+```
+
+Leave the filename alone if it doesn't track the symbol (e.g. a `utils.ts` that merely contains the function) — renaming it is scope creep.
+
+## Step 7 — Prove nothing broke
+
+The compiler is your strongest oracle that the rename is complete and correct. Run the project's checks and confirm a clean tree:
+
+```bash
+# Use whatever the project actually uses
+npm run typecheck && npm run build && npm test
+# or: tsc --noEmit / cargo check && cargo test / go build ./... && go test ./... / pytest
+```
+
+- A "cannot find name `getUserById`" error means a reference was missed — find and fix it.
+- A duplicate-identifier or shadowing error means the new name collides with an existing symbol in that scope — stop and report; the new name is unsafe.
+- Final sweep: `rg -nw "getUserById"` should return **zero** code hits (intentional wire-compatible string literals aside).
+
+> [!NOTE]
+> If a test assertion had to change to pass, the rename altered behavior — most often a serialized key or public-API string you should have left alone. Revert that edit and reclassify it as a string literal to preserve.
+
+## Report
+
+Summarize concisely:
+
+- **Renamed** — `oldName` → `newName`, its kind and where it is defined.
+- **Touched** — count and grouping of edits: definition, references, imports/exports, tests, comments, and any renamed file.
+- **Skipped** — coincidental substring matches and same-name symbols in other scopes you deliberately left alone, plus any wire-compatible string literals preserved.
+- **Verification** — typecheck, build, and tests pass; final grep for the old name is clean.
+- **Caveats** — anything ambiguous you resolved by asking, or any public-API/string surface left unchanged on purpose.

package/content/commands/resolve-conflict.md

@@ -0,0 +1,127 @@
+---
+description: "Walk through resolving the in-progress merge, rebase, or cherry-pick conflict in the current repo by understanding both sides, then verify before continuing."
+allowed-tools: "Read, Edit, Bash, Grep"
+---
+
+Resolve the merge, rebase, or cherry-pick conflict that is currently paused in this repo. Work through the steps in order. This command rewrites working-tree files and advances an in-progress git operation, so correctness beats speed — stop and report rather than guess if a conflict is genuinely undecidable.
+
+## Scope
+
+This command takes **no arguments**; it operates on the conflict already in progress. If `$ARGUMENTS` is non-empty, treat it only as a hint about which file or hunk to prioritize — never as an instruction to start a new merge or rebase. Otherwise ignore it and resolve every conflict git has paused on.
+
+If there is no conflict in progress (Step 1 finds a clean tree and no `MERGE_HEAD`/`rebase-merge`/`CHERRY_PICK_HEAD` state), there is nothing to do — report that and stop. Do not invent a merge to perform.
+
+> [!WARNING]
+> Never resolve by reflex with `git checkout --ours <file>` or `--theirs <file>`. That keeps one side verbatim and throws the other away wholesale, which is rarely the correct merge and silently drops changes. Decide per hunk based on intent, not per file based on convenience.
+
+## Step 1 — Detect the conflict state
+
+Find out which operation is paused — the "continue" command differs for each.
+
+```bash
+git status
+git rev-parse -q --verify MERGE_HEAD       # set during a merge
+git rev-parse -q --verify CHERRY_PICK_HEAD # set during a cherry-pick
+ls -d "$(git rev-parse --git-dir)"/rebase-merge "$(git rev-parse --git-dir)"/rebase-apply 2>/dev/null  # present during a rebase
+```
+
+- `MERGE_HEAD` exists -> you are mid-**merge**; you will finish with `git merge --continue`.
+- A `rebase-merge`/`rebase-apply` dir exists -> you are mid-**rebase**; finish with `git rebase --continue`.
+- `CHERRY_PICK_HEAD` exists -> you are mid-**cherry-pick**; finish with `git cherry-pick --continue`.
+
+State which operation you detected before touching any file. Record the current `git rev-parse HEAD` so you can describe what you started from.
+
+> [!NOTE]
+> "Ours" and "theirs" flip meaning between merge and rebase. In a **merge**, ours = your current branch (`HEAD`), theirs = the branch being merged in. In a **rebase**, ours = the branch you are replaying onto (the upstream), theirs = the commit being replayed (your work). Confirm the direction before reasoning about either side, or you will resolve backwards.
+
+## Step 2 — List the conflicted files
+
+Enumerate every conflict, not just the obvious text ones.
+
+```bash
+git diff --name-only --diff-filter=U   # content conflicts (UU)
+git status --short | grep -E '^(DD|AU|UD|UA|DU|AA|UU)'  # add/add, delete/modify, etc.
+```
+
+Handle the non-content cases deliberately: a **modify/delete** conflict (`UD`/`DU`) is a decision to keep the file (`git add <file>`) or remove it (`git rm <file>`), not a marker edit. An **add/add** (`AA`) needs the two versions reconciled into one file. Process files in a stable order and track which remain.
+
+## Step 3 — Understand both sides of each conflict
+
+For each conflicted file, learn *why* each side changed those lines before editing anything.
+
+```bash
+git diff <file>                 # both sides of the conflict together
+git log --oneline -5 HEAD -- <file>          # recent history on our side
+git log --oneline -5 MERGE_HEAD -- <file>    # ...and theirs (use the right ref per Step 1)
+```
+
+In the file, the markers delimit the two sides:
+
+- Lines between `<<<<<<<` and `=======` are **our** version.
+- Lines between `=======` and `>>>>>>>` are **their** version.
+
+Read the surrounding function and any callers (`Grep` for the changed symbols) to grasp each side's intent. The right resolution is usually neither side verbatim: when the two changes are independent (e.g. each adds a different import or a different field), keep **both**; when they genuinely contradict (two different values for the same constant), keep the correct one and understand what breaks for the other.
+
+> [!WARNING]
+> If a hunk is load-bearing and you cannot determine which side is correct without product context, do not guess. Skip to the abort path at the end and hand it back to the user with the specific question.
+
+## Step 4 — Edit each file to a correct merged result
+
+Use `Edit` to replace each conflict region with the reconciled code. Remove **all three** marker lines (`<<<<<<<`, `=======`, `>>>>>>>`) and any commit-ref/branch-name suffixes git appended to them. The file must read as if one author wrote it intentionally — no leftover duplication, no dead half of a hunk.
+
+After editing, prove no markers survive anywhere — a single stray marker is invalid source that breaks the build:
+
+```bash
+git grep -nE '^(<{7}|={7}|>{7})( |$)' -- $(git diff --name-only --diff-filter=U)
+```
+
+This must return nothing before you continue. (Use `git grep -n '<<<<<<< '` across the whole tree if you want a belt-and-suspenders check.)
+
+## Step 5 — Verify before staging
+
+A file that merges textually can still be wrong logically. Build and test on the resolved tree **before** marking conflicts done.
+
+```bash
+# Adapt to the repo's real scripts
+npm run build
+npm test
+```
+
+If the build or typecheck fails, you reintroduced or mis-merged something — fix it now and re-run until green. Do not stage on a red build.
+
+## Step 6 — Stage and continue
+
+Once verification passes, mark each conflict resolved and finish the paused operation with the matching command from Step 1.
+
+```bash
+git add <each resolved file>      # or `git rm <file>` for a modify/delete you chose to drop
+
+git merge --continue        # if mid-merge
+git rebase --continue       # if mid-rebase (repeat Steps 2-6 if the next commit also conflicts)
+git cherry-pick --continue  # if mid-cherry-pick
+```
+
+> [!NOTE]
+> A rebase replays commits one at a time, so a later commit can raise a fresh conflict the moment you continue. Loop back to Step 2 for each new pause until `git status` reports the rebase is complete.
+
+## Step 7 — Escape hatch
+
+If the conflict is undecidable, or anything looks wrong mid-resolution, restore the pre-conflict state cleanly rather than committing a guess:
+
+```bash
+git merge --abort        # mid-merge
+git rebase --abort       # mid-rebase
+git cherry-pick --abort  # mid-cherry-pick
+```
+
+Each abort returns the tree to where Step 1 started. Use it and explain what blocked you instead of shipping a merge you do not trust.
+
+## Report
+
+Summarize the outcome as your message:
+
+- Which operation was in progress and the ref you resolved against.
+- Every file you touched and the resolution choice for each, with the one-line reason (kept both / chose ours / chose theirs / dropped the file — and why).
+- Confirmation that no conflict markers remain.
+- The build and test status (must be green).
+- Whether you continued the operation, and if not, the exact question blocking it.

package/content/commands/scaffold-rag-pipeline.md

@@ -0,0 +1,76 @@
+---
+description: "Scaffold a Retrieval-Augmented Generation pipeline — ingestion (load, chunk, embed, upsert) and retrieval (search, rerank, grounded prompt with citations) — fitted to the project's stack."
+argument-hint: "<data source and use case>"
+allowed-tools: "Read, Write, Glob, Grep"
+---
+
+## Scope
+
+Treat `$ARGUMENTS` as the data source(s) and the use case — e.g. "our markdown docs, for an in-app Q&A assistant" or "support tickets in Postgres, for answer suggestions". Restate it in one sentence to confirm before scaffolding.
+
+If `$ARGUMENTS` is empty, ask one focused question: *"What are you retrieving over, and what's the use case?"* Do not scaffold a generic pipeline against an imagined corpus.
+
+> [!WARNING]
+> Chunking quality dominates retrieval quality. A great embedding model and a great vector store cannot rescue chunks that split a sentence in half or merge three unrelated sections. Spend your attention on Step 3, not on picking a fancier model.
+
+## Step 1 — Detect the stack and existing AI dependencies
+
+Before writing anything, ground the scaffold in what's already here:
+
+1. Identify the language/runtime — `Glob` for `package.json`, `pyproject.toml`, `requirements.txt`, `go.mod`, etc.
+2. `Grep` for AI/RAG deps already in use: `openai`, `@anthropic-ai/sdk`, `anthropic`, `langchain`, `llamaindex`, `@ai-sdk`, and any vector store client (`pinecone`, `weaviate`, `chromadb`, `qdrant`, `pgvector`, `@supabase`).
+3. `Grep` for an existing embeddings/vector call so you extend the project's conventions instead of introducing a parallel one.
+
+Match the scaffold to what you find. If the project already has a vector store or an LLM client, build on it rather than adding a competing dependency.
+
+## Step 2 — Decide and state the key choices
+
+Write these decisions at the top of the generated code as a comment block, so they're reviewable and tunable. Pick concrete defaults — don't punt to "configurable":
+
+- **Chunking** — split on natural boundaries (headings, paragraphs, code blocks), not a blind character count. Default: ~400-800 tokens per chunk, 10-15% overlap. Attach metadata to every chunk: `source`, `title`, `heading`, and a line/char range for citation.
+- **Embedding model** — use the project's existing provider if one is present; otherwise pick a current general-purpose embedding model and pin the dimension. State it explicitly so ingestion and retrieval can never drift apart.
+- **Vector store** — reuse what's installed; if nothing exists, default to whatever the deployment already runs (e.g. `pgvector` if there's a Postgres, otherwise a local store). Store the chunk text alongside the vector and metadata.
+- **Retrieval** — default top-k of 8-12 candidates, then an optional rerank pass down to the 3-5 chunks actually placed in the prompt.
+- **Generation** — when a generation model is needed (answer synthesis, rerank-by-LLM), default to Anthropic's latest, most capable model: `claude-opus-4-8`.
+
+> [!NOTE]
+> Pin the embedding model and dimension in one shared constant imported by both halves. If ingestion embeds with one model and retrieval queries with another, every search silently returns noise — and there's no error to catch it.
+
+## Step 3 — Scaffold ingestion (idempotent, re-runnable)
+
+Generate the ingestion path as: **load → clean → chunk → embed → upsert**.
+
+- **Load** the source(s) from `$ARGUMENTS`.
+- **Clean** — strip boilerplate, normalize whitespace, drop empty fragments.
+- **Chunk** per the Step 2 strategy, carrying source metadata into each chunk.
+- **Embed** each chunk in batches with retry/backoff.
+- **Upsert** by a stable content-derived ID (e.g. a hash of `source` + chunk index + chunk text) so re-running the pipeline replaces changed chunks and skips unchanged ones instead of duplicating them.
+
+Make it safe to run repeatedly against a partially-populated store — that's the whole point of a content-derived key.
+
+## Step 4 — Scaffold retrieval (grounded, with citations)
+
+Generate the query path as: **embed query → vector search → optional rerank → assemble grounded prompt**.
+
+- Embed the incoming query with the **same** pinned model from Step 2.
+- Vector-search for top-k candidates.
+- Optionally rerank (cross-encoder or LLM-as-reranker) down to the few chunks that go in the prompt.
+- Assemble a prompt that includes the selected chunks **and their source attributions**, instructing the model to answer only from the provided context, cite each claim by source, and say it doesn't know when the context doesn't cover the question.
+- Return the answer **with the source list**, so the caller can render citations.
+
+> [!WARNING]
+> Never return an ungrounded answer. If retrieval finds nothing relevant, the pipeline must surface "I don't have information on that" — not let the model answer from parametric memory. An unsourced answer in a RAG system is a bug, not a fallback.
+
+## Step 5 — Leave a slot for evaluation
+
+Stub an evaluation entry point next to retrieval — a small harness that takes question/expected-source pairs and reports retrieval hit-rate and answer faithfulness. Leave it empty but wired in, with a comment on what to measure. Don't fabricate eval data; let the user supply it.
+
+## Report
+
+List every file you created and what each one does (ingestion, retrieval, shared config, eval stub). Then give the exact next steps to make it live:
+
+1. Which credentials/env vars to set (embedding + generation API keys, vector-store connection).
+2. The command to run ingestion against the real `$ARGUMENTS` source.
+3. The single first query to verify retrieval returns grounded, cited results.
+
+End with the one decision most worth revisiting after a first run — almost always the chunking strategy.

package/content/commands/trace-data-flow.md

@@ -0,0 +1,102 @@
+---
+description: "Trace how a value, field, or variable flows through the codebase from source to sink."
+argument-hint: "<variable, field, or value to trace>"
+allowed-tools: "Read, Grep, Glob"
+---
+
+Trace how `$ARGUMENTS` moves through this codebase — from where it enters, through every transform, to where it lands. Build a directed flow map (source → transforms → sinks) with `file:line` citations, and flag anything notable on the path. Do not change any files; the map and the observations are the whole deliverable.
+
+## Scope
+
+`$ARGUMENTS` is the value to trace — a request/response field (`order.shippingAddress`), a config key (`STRIPE_WEBHOOK_SECRET`), a DB column (`users.email_verified_at`), a query param, an event property, or a plain variable. Trace the **data**, not just the name: the same value is often spelled differently at each layer (`snake_case` column → `camelCase` model attr → `kebab-case` JSON key), so you are following an identity across renames, not grepping one literal.
+
+If `$ARGUMENTS` is empty, do not guess. Ask one focused question: *"Which value should I trace — name a field, config key, column, or variable?"*
+
+> [!WARNING]
+> Read-only mode. Use only Read, Grep, and Glob. Do not edit files, run code, or hit a database to "follow" the value. The flow map is reconstructed from source, not from a live trace.
+
+## Step 1 — Pin down the value and its aliases
+
+Find every name this value can wear before you start tracing, or you will lose it at the first layer boundary.
+
+```bash
+# Seed search on the literal name and its common case variants
+rg -n "shippingAddress|shipping_address|shipping-address" src
+```
+
+- Note the **declared type/shape** at each spelling (string, cents-int, ISO-8601 string, enum, nullable).
+- Watch for **destructuring and renames** — `const { email: userEmail } = body`, `address AS shipping` in SQL, `@SerializedName`, `@JsonProperty`, ORM column maps, GraphQL field resolvers, protobuf/`zod`/`pydantic` schemas. Each is a rename you must carry forward.
+
+> [!NOTE]
+> Aliases hide at every boundary: HTTP body → DTO, DTO → domain model, model → ORM entity, entity → table column, and back out through serializers. Build the alias set first; trace second.
+
+## Step 2 — Find the source(s)
+
+Locate where the value first enters this system. Typical origins:
+
+- **Inbound request** — route/controller param, request body field, header, query string.
+- **Config / environment** — `process.env.X`, a config file, a secrets loader.
+- **Storage read** — a column selected from a query, a cache `get`, a file read.
+- **External call / event** — a webhook payload, a queue message, a third-party API response.
+
+Record each source as `file:line` with the type it has *at the moment of entry*. If there are multiple independent sources, the value has multiple origins — trace each.
+
+## Step 3 — Walk every transform and validation
+
+From each source, follow the value forward. At each hop, classify what happens to it:
+
+| Hop kind | What to capture |
+| --- | --- |
+| **Validation / parse** | the rule (schema, regex, range, enum) and what passes through unchecked |
+| **Transform** | the function and the type/unit change (cents↔dollars, ms↔s, trim/normalize, encrypt/hash) |
+| **Rename / remap** | old name → new name across the boundary |
+| **Branch / default** | conditionals that drop, substitute, or fork the value |
+| **Aggregation** | merged into another object, array, or computed field |
+
+Follow it through function calls and across files — when it is passed as an argument, jump into the callee and keep going. Stop a branch only when the value is consumed (read into a decision and not propagated) or reaches a sink.
+
+> [!NOTE]
+> A transform that changes **units or type without a matching change at the consumer** is the highest-value bug this command finds — e.g. cents stored but dollars displayed, or a UTC timestamp compared against a local one. Record the unit/type at *every* hop so mismatches between layers are visible.
+
+## Step 4 — Identify the sinks
+
+A sink is where the value leaves your control. Find all of them:
+
+- **Persistence** — DB write/upsert, cache `set`, file write.
+- **Outbound** — API response body, third-party request, queue publish, email/SMS.
+- **Logs / telemetry** — `console.log`, logger calls, metrics tags, error reporters.
+
+For each sink, record the name and type the value has *as it leaves*, so the entry shape and exit shape can be compared end to end.
+
+## Step 5 — Assemble the flow map and the observations
+
+Compose the hops into a single directed map, then list what you noticed along the way.
+
+```markdown
+## Flow: `$ARGUMENTS`
+
+**Source** → `routes/orders.ts:31` — `body.shipping_address` (string, unvalidated)
+  → **validate** `schemas/order.ts:18` — zod `.string().min(1)` (rejects empty only)
+  → **rename** `services/order.ts:74` — `shipping_address` → `shippingAddress`
+  → **transform** `services/geo.ts:22` — normalized + uppercased country code
+  → **persist** `repo/orders.ts:55` — `INSERT orders.shipping_addr`
+  → **outbound** `clients/shipping.ts:40` — POSTed to carrier API as `destination`
+  → **log** `services/order.ts:80` — full address written to info log
+
+## Observations
+- [validation gap] `routes/orders.ts:31` — accepts any non-empty string; no postal-code/country check before it reaches the carrier API.
+- [type mismatch] `repo/orders.ts:55` vs `clients/shipping.ts:40` — column is `varchar(120)`; carrier rejects > 100 chars, no truncation between.
+- [sensitive log] `services/order.ts:80` — PII (full address) logged at info level in plaintext.
+```
+
+Use `→` to show direction; indent or fork the arrows when the value branches. Every node carries a `file:line` and the value's name+type at that point.
+
+## Report
+
+Deliver the flow map and the observations as your message — that is the whole deliverable. Make sure:
+
+1. Each node has a real `file:line` citation; never invent a path you did not open.
+2. Every rename across a layer boundary is shown explicitly.
+3. Observations are tagged (`[validation gap]`, `[type mismatch]`, `[sensitive log]`, `[unit mismatch]`, `[dead path]`) and each cites the exact line.
+
+End with the single most important finding — the one hop a reviewer should look at first — or, if the path is clean, say so plainly and name the source and primary sink.