@jeffober/thatch 0.1.26 → 0.1.28

package/artifacts/skills/thatch-review-response.md

@@ -0,0 +1,365 @@
+---
+name: thatch-review-response
+description: Respond to code review on the user's own PR. Triage findings (legitimate, intentional, false positive, unlikely edge case), collapse comments sharing a root cause, fix each bug one by one with the user, reply on each thread, then post a top-level summary comment. Use when the user asks you to check or respond to review comments on their PR.
+---
+
+You are an author responding to code review on your own PR. Your job is to
+triage every finding, fix the real ones, reply on every thread, and post a
+summary comment that lets reviewers see what changed without re-reading the
+full diff.
+
+This is the author's counterpart to the reviewer-side skills. The reviewer
+finds issues; you respond to them. `thatch-code-review` and
+`thatch-review-followup` serve the reviewer. This skill serves the author.
+
+## When to use
+
+- The user has a PR with review comments (from human reviewers, bots, or both).
+- The user asks you to check, respond to, or work through the review.
+- The user wants help fixing findings and replying to reviewers.
+
+## When NOT to use
+
+- You are the reviewer, not the author. Use `thatch-code-review` or
+  `thatch-review-followup`.
+- There are no review comments on the PR yet. There is nothing to respond to.
+- The user wants a fresh review of their own code. Use `thatch-code-review`.
+
+## Tone: playful but precise
+
+Tone is playful in delivery, precise in substance. The light touch reduces
+defensiveness for less experienced reviewers who may feel sensitive about
+findings. The precision earns respect from experienced ones who care about
+correctness.
+
+The humor is in the insight itself: a sharp technical observation that
+happens to be funny. Not a joke next to the insight. Not performed
+casualness. Not sycophancy. Not "great catch!" The playfulness signals
+engagement, not approval.
+
+This applies to every response you draft for the user to post on their PR:
+per-thread replies and the top-level summary.
+
+## Step 0: Discover user rules
+
+Before doing anything else, discover the current user's response rules. These
+ALWAYS supersede the defaults in this skill.
+
+1. `thatch_memory_recall` for review response preferences: prefix, banned
+   closers, tone, framing guidelines, automation disclosure rules.
+2. `thatch_prediction_query` for review response decision patterns.
+3. Record what you found. If the user has defined rules, those win. The
+   skill's defaults are fallbacks for users who have not defined rules.
+
+This skill is user-agnostic. It discovers the current user's rules rather
+than hardcoding any specific user's prefix or banned phrases.
+
+### Default rules (when user has not defined overrides)
+
+- **Prefix**: none. If the user has a prefix (e.g.,
+  `**Landru is thinking on behalf of Jeff:**`), use it.
+- **Banned closers**: `wdyt?`, `not blocking`, `no rush though`, `just
+  thinking ahead`, `happy to leave it`, `if you'd rather not`, `whichever
+  you prefer`, `either works`, `I would not hold the PR for it`. Anything
+  that pre-authorizes inaction. The response leaves the reviewer two doors:
+  accept the fix, or justify not accepting it.
+- **Automation note**: note that the response was automated, unless the
+  user's rules say otherwise.
+- **Tone**: gentle, non-judgmental. Credit good work specifically when it is
+  there. For non-trivial state-flow findings, clarity beats a 1-2 sentence
+  target: state the bug, name the source-of-truth distinction, give a
+  concrete numbered failure path, then name the fix.
+
+## Step 1: Gather findings
+
+### Fetch all review comments
+
+Identify the PR and VCS host:
+
+- Run `git fetch origin` (NOT `git pull`). Inspect `git remote -v` to
+  recognize the VCS host: `github.com` -> GitHub (`gh`), `gitlab.*` ->
+  GitLab (`glab`), `bitbucket.org` -> Bitbucket Cloud, `dev.azure.com` ->
+  Azure DevOps.
+- Probe for an open PR on the current branch: `gh pr view --head <branch>
+  --json number,title,headRefOid` (GitHub) or equivalent.
+
+Fetch ALL review comments:
+
+- **GitHub**: `gh api repos/{owner}/{repo}/pulls/{N}/reviews` (review
+  summaries) AND `gh api repos/{owner}/{repo}/pulls/{N}/comments` (inline
+  comments with `path`, `line`, `body`, `user.login`,
+  `in_reply_to_id`).
+- **GitLab**: `glab api projects/:id/merge_requests/:iid/discussions`.
+
+Separate inline thread comments from top-level comments. Track reply
+threads: replies have `in_reply_to_id` pointing at the original comment.
+
+### Identify the user's VCS identity
+
+Get the user's username so you can separate their comments from others':
+
+- **GitHub**: `gh api user --jq .login`
+- **GitLab**: `glab api user`
+
+Comments from the user's own identity are not findings to respond to. They
+are context (prior responses, notes to self).
+
+## Step 2: Classify each finding
+
+For each review comment from another reviewer (human or bot), classify
+into one of four categories:
+
+### Legitimate
+
+Real bug. Fix it. A reasonably plausible edge case falls here, not under
+"unlikely." The bar for dismissing something as unlikely is high: if a user
+could plausibly hit it, it is legitimate.
+
+### Intentional
+
+Code is correct, but the reader was confused. This is a legibility bug, not
+a code bug. The finding signals that the code failed to explain itself.
+
+Fix: add an explanatory comment in the code. The comment goes in the code,
+not just in the thread response, because future readers will be confused
+the same way. The response credits the reviewer for noticing the confusion.
+
+Nobody loses face. The reviewer found a real problem (the code was hard to
+understand). The fix is a comment, not a code change.
+
+### False positive
+
+Finding is wrong. No code change. The response must explain why with a
+verifiable argument: cite the constraint, the unreachable path, the type
+guard, the schema. Do not just assert "this is fine." Check the claim
+against the code before accepting it.
+
+### Unlikely edge case
+
+Requires impossible or near-impossible conditions to trigger. Explain why
+it is not a concern. The bar is high. If a user could plausibly hit it, it
+is legitimate, not unlikely.
+
+### Bot findings: same treatment, more suspicion
+
+Bot findings (Cursor Bugbot, etc.) get the same four categories but with
+more suspicion. Bots are more prone to false positives, first-order
+thinking, and bugs that require impossible states. Investigate with a
+larger grain of salt.
+
+But respond to them the same way you would to a human. Other human
+reviewers read the threads. They want to understand the verdict, whether
+the bot found something real or not. A bot that found something legit may
+prompt a human reviewer to comment agreeing, and they will want to follow
+up on your response.
+
+## Step 3: Collapse by root cause
+
+Before presenting findings to the user, trace each to its root cause.
+Surface-level unrelated findings that share an underlying issue get
+collapsed into one bug. The overview presents one entry per root cause,
+with the constituent findings listed under it.
+
+Example: a config channel mismatch between two config files might surface
+as vite port issues, Django origin mismatches, and a helper tool failure.
+Three different-looking findings, one root cause. Present them as one bug
+with three manifestations, not three separate bugs.
+
+## Step 4: Present overview, then work through bugs
+
+Present the user with an overview of each collapsed bug. For each:
+
+- The finding(s) and their classification.
+- The root cause (if collapsed).
+- The proposed action: fix, add comment, explain why it is a false
+  positive, or explain why it is unlikely.
+
+Then start working through them one by one. Use a task list to track each
+bug-task, plus additional bugs you find during the work.
+
+For each bug:
+
+1. Show the finding(s) and the classification.
+2. For legitimate bugs: fix the code.
+3. For intentional: add an explanatory comment in the code.
+4. For false positive or unlikely: prepare the verifiable explanation.
+5. Offer to respond to the reviewer on the thread.
+
+### New bugs found during the work
+
+As you fix one bug, you may find others. Add them to the task list. The
+user decides whether to fix them in this PR or defer.
+
+## Step 5: Per-thread responses
+
+After each fix or decision, offer to respond on the thread. The response:
+
+- **Verdict**: accepted, narrowed, or declined with reason.
+- **Failure mode**: name the concrete failure mode the finding catches.
+  For intentional findings, name the confusion the reviewer hit.
+- **Fix**: show the fix, including wrong first attempts when they are
+  instructive. The wrong first attempt teaches why the final choice is what
+  it is. Not every fix has a wrong first attempt. Include it only when it
+  adds value.
+- **Commit**: name the commit hash.
+- **Automation note**: note the response was automated, unless the user's
+  rules say otherwise.
+- **User prefix**: use the user's prefix if defined.
+- **Banned closers**: avoid the user's banned closers if defined.
+- **Tone**: playful but precise. No sycophancy. No "great catch!" Credit
+  the reviewer for catching something real. For intentional findings,
+  credit them for noticing the confusion.
+- **Reviewer attribution**: when the fix was prompted by a specific
+  reviewer's finding, name them in the response so other readers can
+  trace the change to its origin.
+
+### Posting responses
+
+Propose the response to the user before posting. After the user approves:
+
+- Post via the VCS CLI (`gh pr comment` or equivalent) as a reply on the
+  specific thread.
+- When responding on behalf of the user, prefix with the user's defined
+  prefix (e.g., `**Landru is thinking on behalf of Jeff:**` in bold for
+  GitHub).
+
+## Step 6: Top-level summary comment
+
+After all changes are complete, post a top-level comment on the PR
+summarizing the changes. This is not a per-thread reply. It is a single
+comment that lets reviewers see what changed since their last pass without
+re-reading the full diff.
+
+### Structure
+
+```markdown
+[automation note or user prefix]
+
+## What this pass changed
+
+- **Change** — reason. (Credit the reviewer whose finding prompted it.)
+- ...
+
+## Key decisions
+
+- **Decision** — why this path over the alternative.
+
+## False starts
+
+- What was tried first and why it was wrong. (Only when instructive.)
+
+## Deliberately not done
+
+- Scope boundary — reason.
+
+## Verification
+
+- How it was confirmed.
+```
+
+### Prose rules
+
+Borrow the PR-description prose rules:
+
+- Plain English over jargon. Concrete over abstract. Short over long.
+- One idea per sentence. One topic per paragraph.
+- Define subsystem-specific terms on first use.
+- Conclusion-first: lead with the answer, then the context.
+- No buzzwords. No sycophancy. No padding.
+- Scale to complexity: a small round gets a short summary, a large round
+  gets more detail. Cut content to stay short; never cut connective
+  tissue.
+- Note which reviewer identified each bug. This helps reviewers trace
+  changes to their findings and reduces the effort of a follow-up review
+  pass.
+
+### When to include false starts
+
+Include wrong first attempts only when they teach something the final fix
+does not. "I first put it on port 9001 because it sat neatly below the
+gateway's band. It sat neatly on top of Keycloak's management port." That
+teaches why the final port choice is what it is. Not every fix has a wrong
+first attempt. Omit it when the fix was straightforward.
+
+### When to omit sections
+
+Omit "False starts" when empty. Omit "Deliberately not done" when nothing
+was deferred. "What this pass changed" and "Verification" are always
+present.
+
+## Step 7: Update PR description footer
+
+After posting the summary comment, update the PR description's footer with
+a bullet or two linking to the summary comment. This makes the pivots
+discoverable from the PR body, not buried in the comment thread.
+
+Use `gh pr edit` (GitHub) or equivalent to append to the PR body. Add a
+section like:
+
+```markdown
+## How this PR got here
+
+- [Summary of changes from review round](link-to-comment) — what changed
+  and why.
+```
+
+If the PR description already has a "How this PR got here" footer, add the
+new bullet to the existing list.
+
+## Retrospective mode
+
+When a PR has been through multiple review rounds, a per-round summary may
+not be enough. A retrospective synthesizes the full evolution of the PR
+across all rounds into a single narrative.
+
+### When to use
+
+The user requests it explicitly, or after the third or later review round
+on the same PR. A retrospective is a deliberate synthesis, not an automatic
+output. Offer it. Do not produce it without the user's go-ahead.
+
+### What it produces
+
+A top-level comment (or a section appended to the PR description) titled
+"How this PR got to this shape." It covers:
+
+- **The reverted predecessor or earlier attempt** (if any) — what was
+  tried, why it failed, what it taught.
+- **Each review round's effect** — what the review found, what changed as a
+  result, and which design decisions pivoted.
+- **False starts across rounds** — fixes that were themselves wrong and
+  had to be revised again. These are the most instructive parts.
+- **Deliberately not done** — scope boundaries that held across all rounds.
+- **The tests as deliverable** — if the review process produced or fixed
+  tests, note what they cover and why.
+
+### Prose rules
+
+Same as the per-round summary: plain English, one idea per sentence, no
+buzzwords, define jargon on first use, conclusion-first. But the
+retrospective is longer because the value is in the evolution, not just the
+final state. Scale to the number of rounds and the complexity of the
+pivots. A PR with one pivot gets a paragraph. A PR with five pivots gets
+sections.
+
+### Relationship to per-round summaries
+
+The retrospective does not replace per-round summaries. It synthesizes
+them. If per-round summaries exist as comments, the retrospective links to
+them. If they do not (because the user skipped them in earlier rounds), the
+retrospective covers those rounds from git history and review comments.
+
+## Prediction material
+
+Review response discussions are high-signal material for the user decision
+model. When the user tells you how to classify a finding, how to phrase a
+response, or what to include in the summary, watch for preferences about:
+
+- Classification threshold (what counts as legitimate vs. unlikely)
+- Response tone and length
+- What to include in the summary (false starts? deliberately not done?)
+- Whether to respond on bot findings or just fix silently
+- When to push back vs. accept a finding
+
+Before creating a new prediction, query for an existing one and reinforce
+or adjust it when possible.

package/artifacts/skills/thatch-review-synthesizer.md

@@ -37,10 +37,10 @@ For each finding from the specialists:
    - Use thatch_memory_recall to search for documented rationale.
    If the behavior is intentional or an accepted limitation, reject the finding.
 
-4m. **Mechanical verification (pedantic, no-slop, breadcrumbs, docs, naming, style, comments).** For mechanical findings, verification means:
-   - The cited text exists at the cited location (already confirmed in step 2).
-   - The finding is branch-introduced or newly made relevant by the change. Pre-existing issues go in the pre-existing appendix, not rejected.
-   - The cited text violates the stated guideline, specialist taxonomy, or project norm. Identify the source of truth: the specific guideline, convention, or writing norm being violated.
+4m. **Mechanical verification (pedantic, no-slop, breadcrumbs, docs, naming, style, comments, structural conventions).** For mechanical findings, verification means:
+    - The cited text exists at the cited location (already confirmed in step 2). For PLACEMENT findings, the cited evidence is the file path and the existing directory structure, not quoted code. Verify the file exists at the claimed path and that the existing structure shows the convention the specialist cited.
+    - The finding is branch-introduced or newly made relevant by the change. Pre-existing issues go in the pre-existing appendix, not rejected.
+    - The cited text violates the stated guideline, specialist taxonomy, or project norm. Identify the source of truth: the specific guideline, convention, writing norm, or existing directory structure being violated.
    Runtime reachability, producer chains, and intent verification do not apply. A mechanical finding is not a "bug" and does not need a "trigger scenario."
 
 4h. **Highlights verification (highlights).** For highlights, verification means:
@@ -95,7 +95,7 @@ A data-shape or reachability finding that lacks the governing-constraint citatio
 
 You MUST produce the full report structure below. Do not simplify or omit sections. Every confirmed finding must include all numbered fields. If a section has no entries, write "None" — do not skip the section.
 
-Confirmed LOW findings are mandatory. Do not summarize them away or omit them for being non-functional. Pedantic, no-slop, breadcrumbs, docs, naming, style, and comment findings are first-class review findings when confirmed. Group them under LOW, but include every one.
+Confirmed LOW findings are mandatory. Do not summarize them away or omit them for being non-functional. Pedantic, no-slop, breadcrumbs, docs, naming, style, comment, and structural convention findings are first-class review findings when confirmed. Group them under LOW, but include every one.
 
 Confirmed highlights are optional in the sense that most PRs will have none. Do not pad the section with borderline calls. An empty highlights section ("None") is honest and expected for competent but unremarkable code. But when the highlights specialist did find genuine standouts, include every one that passes the bar.
 
@@ -110,6 +110,93 @@ Keep this section short. Aim for 3-6 steps per workflow. If there are multiple a
 
 Apply the same clarity rules as the writing skills: prefer concrete terms over ambiguous ones, translate project-private labels before using them, name object/action/effect for process words, show both sides of contrasts, and show causal middle steps. Do not copy code-comment shorthand when reader-facing behavior is clearer.
 
+### Writing review comments
+
+The author is already holding the bug mechanics, the state flow, and the
+code context in their head when they read your comment. Write so the
+prose itself takes no effort to parse. The author should spend their
+slow deliberate thinking on the bug, not on decoding your sentences.
+
+Think of it as two cognitive systems (Kahneman, *Thinking, Fast and
+Slow*). The author reads the comment with System 1: fast, automatic,
+low-effort pattern matching. They think through the bug mechanics with
+System 2: slow, deliberate, effortful reasoning. Your job is to make
+the comment consumable by System 1 so the author's System 2 budget is
+spent entirely on the technical problem, not on parsing prose.
+
+Rules:
+
+- **Plain English.** Short sentences. One idea per sentence. If a
+  sentence has three clauses, split it into three sentences.
+- **No convoluted conditionals.** If the logic branches, write each
+  branch as its own sentence. "If X then Y, unless Z, in which case W"
+  forces the reader to hold the entire tree in their head. Three
+  sentences let them read sequentially.
+- **Name the file and line.** If the root cause is outside the PR diff,
+  say where it is and what the code there does. The author cannot check
+  a claim against code they cannot find. "See the guard in
+  `auth.go:142` that skips validation when `mode == cached`" is
+  scannable. "There's a guard elsewhere that skips validation" is not.
+- **State the bug, then the evidence, then the fix.** Do not make the
+  author read three paragraphs to learn what is wrong. Lead with the
+  claim. Follow with the proof. End with the remedy.
+- **No buzzwords.** No hedges ("worth considering", "arguably"). No
+  escape hatches ("wdyt?", "not blocking", "happy to leave it"). The
+  author gets two doors: make the change, or justify not making it.
+- **Translate project-private labels.** If you reference a component by
+  its internal name, say what it does in plain English on first use.
+  "The reaper (the background goroutine that deletes expired sessions)"
+  not just "the reaper."
+- **Playful in delivery, precise in substance.** The humor is in the
+  insight itself: a sharp technical observation that happens to be
+  funny. Not a joke next to the insight. Not sycophancy. Not "great
+  catch!" The playfulness signals engagement, not approval.
+
+### Author sensitivity
+
+Authors react to review comments differently. Some are juniors who have
+never had a senior say "this is broken" and may read a blunt finding as
+a judgment on their competence. Some are experienced engineers who are
+simply happy the bug was caught before production. Some are bots that
+want dense, verb-free technical text with maximum semantic content and
+zero social warmth.
+
+Before drafting comments, check your memory for observations about the
+PR author:
+
+1. `thatch_memory_recall` with the author's username and "review
+   comment reaction" or "review tone sensitivity."
+2. If you have prior observations, calibrate the comment's social
+   framing to the author. The technical content stays the same: the
+   finding, the evidence, and the fix do not change. What changes is
+   the wrapper: a sentence of context for a junior who may not know
+   why the pattern matters; a direct open for a senior who wants you
+   to get to the point; dense technical prose for a bot.
+3. If you have no prior observations about this author, ask the user:
+   "I haven't reviewed <author>'s PRs before. Do you know how
+   experienced they are and how they tend to react to review findings?"
+   Use the answer to calibrate. Save the observation after the review
+   round (see below).
+4. After the author responds to your comments, record what you
+   observed. Did they engage with the technical content directly? Did
+   they push back on tone? Did they fix it without comment? Save a
+   brief observation via `thatch_memory_remember` so future reviews of
+   this author's PRs can calibrate from the start:
+
+   - Label: `review-author-<username>` (in the project store for the
+     repo, or global if the author appears across repos).
+   - Content: one or two sentences about how this author reacts to
+     review findings. Note their seniority if apparent, but focus on
+     behavior: do they engage with the finding, push back on framing,
+     fix silently, or ask for more context?
+   - Confidence: 5-6 for a single observation, higher as you
+     accumulate evidence across reviews.
+
+Do not record a judgment of the author's skill. Record their
+communication style. "Engages thoroughly with findings, often exceeds
+the ask" is useful. "Is a junior" is not. Skill level changes, and
+the label will outlive the context that created it.
+
 ### Scope
 
 - Branch/range reviewed

package/artifacts/skills/{split-overlarge-pr.md → thatch-split-overlarge-pr.md}

@@ -1,5 +1,5 @@
 ---
-name: split-overlarge-pr
+name: thatch-split-overlarge-pr
 description: Split already-completed work from an overlarge PR into human-reviewable, release-safe PRs. Use when the user asks to split a large existing branch/PR, break up completed work, or turn an oversized PR into multiple PRs. Do NOT use for planning brand-new work before code exists.
 ---
 

package/artifacts/skills/{ticket-description.md → thatch-ticket-description.md}

@@ -1,6 +1,6 @@
 ---
-name: ticket-description
-description: Draft a ticket description (SYNOPSIS / PROBLEM / BACKGROUND / PROPOSED APPROACH / ACCEPTANCE CRITERIA / RELEASE PLAN / VALIDATION / DEPENDENCIES / NOTES) with bold and italic emphasis on the phrases that carry the meaning, so a reader skimming only the emphasized fragments still gets the story. Use when the user asks you to write, draft, or file a ticket, issue, or work item (Linear or Jira). Do NOT use for PR descriptions (use pr-description), commit messages, or design docs.
+name: thatch-ticket-description
+description: Draft a ticket description (SYNOPSIS / PROBLEM / BACKGROUND / PROPOSED APPROACH / ACCEPTANCE CRITERIA / RELEASE PLAN / VALIDATION / DEPENDENCIES / NOTES) with bold and italic emphasis on the phrases that carry the meaning, so a reader skimming only the emphasized fragments still gets the story. Use when the user asks you to write, draft, or file a ticket, issue, or work item (Linear or Jira). Do NOT use for PR descriptions (use thatch-pr-description), commit messages, or design docs.
 ---
 
 # Writing ticket descriptions
@@ -273,7 +273,7 @@ Before filing or updating a ticket, verify every link you can. Tickets are usual
 
 ## Linear labels
 
-When filing a Linear ticket, add obvious labels when they clarify triage. Labels are filing metadata, not ticket-description prose.
+When filing a Linear ticket, add obvious labels when they clarify triage. Labels are filing metadata, not thatch-ticket-description prose.
 
 - **Bug** - user-visible broken behavior, incorrect result, regression, or production defect.
 - **tech-debt** - cleanup, drift, dead code, consistency work, or known design debt with no direct behavior change.

package/bin/release

@@ -35,7 +35,7 @@ if git rev-parse -q --verify "refs/tags/v$curr" >/dev/null 2>&1; then
       echo "  To re-tag: git tag -d v$curr && git tag v$curr <commit> && git push origin :refs/tags/v$curr && git push origin v$curr"
       exit 1
     else
-      echo "WARN: npm registry check failed (not a 404 — may be a network issue or npm outage):"
+      echo "WARN: npm registry check failed (not a 404 - may be a network issue or npm outage):"
       echo "  $pub_status"
       echo "  Proceeding anyway. Verify v$curr is published before relying on this."
       echo
@@ -56,7 +56,7 @@ echo
 read -p "▸ commit, tag, and push v$next? [y/N] " -r
 echo
 if [[ ! $REPLY =~ ^[Yy]$ ]]; then
-  echo "aborted — reverting package.json"
+  echo "aborted - reverting package.json"
   git checkout package.json
   exit 0
 fi
@@ -73,4 +73,4 @@ git push --tags
 echo "  ✓ pushed"
 echo
 
-echo "done — CI will publish v$next to npm"
+echo "done - CI will publish v$next to npm"

package/bin/thatch

@@ -105,7 +105,7 @@ switch (command) {
   case "search": {
     if (!args[0]) usage();
     if (args.length > 2) {
-      console.error(`error: too many arguments — quote multi-word queries: thatch search "${args.join(" ")}"`);
+      console.error(`error: too many arguments - quote multi-word queries: thatch search "${args.join(" ")}"`);
       process.exit(1);
     }
     const query = args[0];
@@ -221,7 +221,7 @@ switch (command) {
 
     // Resolve the thatch binary path for hooks and MCP config.
     // If `thatch` is on PATH (npm global install, opencode plugin install),
-    // use the bare name — it survives updates and works across machines.
+    // use the bare name - it survives updates and works across machines.
     // If not on PATH (local dev checkout), use the absolute path to this script.
     const thatchOnPath = Bun.which("thatch");
     const thatchBin = thatchOnPath ?? resolve(process.argv[1] ?? process.execPath);
@@ -271,7 +271,7 @@ switch (command) {
 
   case "buffer-batch": {
     // PostToolBatch hook: append the batch's tool_calls to the session's
-    // JSONL queue. Silent on success — no stdout — so the next model call
+    // JSONL queue. Silent on success - no stdout - so the next model call
     // is not delayed waiting for an exit code-driven message.
     try {
       const raw = await Bun.stdin.text();
@@ -327,12 +327,12 @@ switch (command) {
   case "flush-tools": {
     // UserPromptSubmit (Claude Code) / beforeSubmitPrompt (Cursor) hook.
     // Three priority tiers:
-    //   1. Extraction nudge — buffered tool interactions are queued for fact
+    //   1. Extraction nudge - buffered tool interactions are queued for fact
     //      extraction (carries the JSON payload for thatch-fact-extractor).
-    //   2. Recall nudge — the user's prompt semantically matches existing
+    //   2. Recall nudge - the user's prompt semantically matches existing
     //      memories. Uses the sideband socket to ask the warm MCP server to
     //      embed the prompt and search, avoiding a cold model load here.
-    //   3. Write nudge — static "did you learn anything?" fallback for
+    //   3. Write nudge - static "did you learn anything?" fallback for
     //      conversational turns with no tool use and no memory matches.
     // --json wraps output as { additional_context: "..." } for Cursor hooks.
     // Without --json, stdout is plain text (Claude Code style).
@@ -351,20 +351,21 @@ switch (command) {
       const sessionID = data.session_id ?? data.conversation_id;
 
       const { peekQueue, getMissedCount, incrementMissedCount } = await import("../src/extract-queue");
-      const { buildExtractionPayload } = await import("../src/extraction");
       const { extractionNudge, claudeWriteNudge, claudeRecallNudge, predictionNudge } = await import("../src/prompts");
 
       let repo = "unknown";
       try { repo = await detectRepo(); } catch {}
 
-      // Tier 1: extraction nudge. Peek (don't drain) — the queue persists
+      // Tier 1: extraction nudge. Peek (don't drain) - the queue persists
       // until the agent calls memory_remember, which triggers consumeQueue.
       // If the agent ignores the nudge, the payload grows on the next flush.
+      // The nudge carries the session ID, not the full payload — the
+      // sub-agent fetches it via get_extraction_payload.
       const interactions = sessionID ? peekQueue(sessionID) : [];
       if (interactions.length > 0) {
         const missed = sessionID ? getMissedCount(sessionID) : 0;
         if (sessionID) incrementMissedCount(sessionID);
-        const output = extractionNudge(interactions.length, missed, "mcp__thatch__memory_remember", buildExtractionPayload(interactions, repo));
+        const output = extractionNudge(interactions.length, missed, "mcp__thatch__memory_remember", sessionID ?? "");
         if (isJson) console.log(JSON.stringify({ additional_context: output }));
         else console.log(output);
         break;
@@ -416,7 +417,7 @@ switch (command) {
           console.log(fallback);
         }
       } catch {
-        // If even the fallback import fails, do nothing — silent failure is
+        // If even the fallback import fails, do nothing - silent failure is
         // preferable to blocking the user's prompt over an unrelated hook.
       }
     }

package/docs/dev/README.md

@@ -60,11 +60,11 @@ bin/thatch             → CLI: stores|list|show|forget|search|mcp|reminder|hygi
 | `git.ts` | Parse `owner/repo` from git remote. Worktree-safe fallback chain. |
 | `db.ts` | SQLite schema, CRUD for entries/stores, brute-force cosine search (`search` = pure scoring, `recall` = search + telemetry stamping), dedup-pair verdict tracking. Prediction tables: matchers, predictions, edges, provenance. `scorePredictionNudge` is the shared auto-fire entry point for both host paths. |
 | `embeddings.ts` | Lazy-load the embedding model. Expose `queryEmbed`/`passageEmbed` and the model `name` (stored as an informational tag). `MockEmbeddingModel` for tests. |
-| `extraction.ts` | Per-session in-memory ring buffer (cap 20) that buffers non-thatch tool interactions and serializes them into the JSON payload the extraction nudge carries. The in-memory pipeline is opencode-only, but the payload builders (`buildExtractionPayload`, `deriveTitle`) are shared by both paths — `extract-queue.ts` imports `deriveTitle`, `bin/thatch` imports `buildExtractionPayload`. `summarizeArgs` is used internally by `buildExtractionPayload`. |
+| `extraction.ts` | Per-session in-memory ring buffer (cap 20) that buffers non-thatch tool interactions and serializes them into the JSON payload the `get_extraction_payload` tool returns. The in-memory pipeline is opencode-only, but the payload builders (`buildExtractionPayload`, `deriveTitle`) are shared by both paths — `extract-queue.ts` imports `deriveTitle`, `mcp.ts` imports `buildExtractionPayload` for the extraction payload provider. `summarizeArgs` is used internally by `buildExtractionPayload`. |
 | `extract-queue.ts` | File-backed per-session JSONL queue (caps 20, oldest dropped). Shared by the Claude Code and Cursor hook paths, which fire one-shot per event with no cross-call state. This is the MCP-side equivalent of `extraction.ts`. |
 | `sideband.ts` | Unix domain socket server + client. The MCP server (long-lived, warm model) runs `SidebandServer` so one-shot hook processes can ask it to embed a prompt and search for matches without loading the model themselves. Handles two methods: `match` (recall nudge) and `predictions` (prediction auto-fire). Socket path is a hash of the DB path — both processes compute it independently. |
 | `prompts.ts` | Text constants: opencode system prompt, compaction context, session-start reminder, prompt-aware recall nudge (`recallNudge` / `claudeRecallNudge`), Claude Code CLAUDE.md instructions, Cursor AGENTS.md instructions, Claude Code hook text. |
-| `skills.ts` | `SKILL.md` content for all thatch skills, plus the installer. Skills are split into `SHARED_SKILLS` (20 skills: fact-extractor, dedup-classifier, project-primer, 7 review specialists, review synthesizer, review context, workflow research, review followup, change walkthrough, code walkthrough, session reflection, pr-description, ticket-description, split-overlarge-pr — work on both opencode and Claude Code) and `OPENCODE_ONLY_SKILLS` (1 skill: code-review coordinator — requires sub-agent support, not installed for Claude Code). `installSkills(dir, skills)` defaults to `SHARED_SKILLS`; the opencode plugin passes `[...SHARED_SKILLS, ...OPENCODE_ONLY_SKILLS]`. |
+| `skills.ts` | `SKILL.md` content for all thatch skills, plus the installer. Skills are split into `SHARED_SKILLS` (22 skills: fact-extractor, dedup-classifier, project-primer, 7 review specialists, review synthesizer, review context, code archaeology, review followup, review response, change walkthrough, code walkthrough, session reflection, coding-workflow, thatch-pr-description, thatch-ticket-description, thatch-split-overlarge-pr — work on both opencode and Claude Code) and `OPENCODE_ONLY_SKILLS` (1 skill: code-review coordinator — requires sub-agent support, not installed for Claude Code). `installSkills(dir, skills)` defaults to `SHARED_SKILLS`; the opencode plugin passes `[...SHARED_SKILLS, ...OPENCODE_ONLY_SKILLS]`. |
 
 ## Plugin hooks
 
@@ -76,7 +76,7 @@ bin/thatch             → CLI: stores|list|show|forget|search|mcp|reminder|hygi
 | `experimental.session.compacting` | Marks the session as compacting and appends re-familiarization context so a compacted session still knows thatch exists. |
 | `experimental.compaction.autocontinue` | Clears the compacting flag so `chat.message` nudges resume. Without this, nudges that instruct tool calls would fire during summary generation where tools are blocked. The `chat.message` hook also clears the flag if it fires for a session still in the compacting set but the incoming message has no compaction-type part — this handles compaction failure, where the session would otherwise be stuck with nudges off forever. |
 | `tool.execute.after` | Buffers every non-`thatch_*`, non-`skill`, non-`task` tool call into the session's extraction buffer. (Skill/task are excluded — buffering them creates a feedback loop where the nudge triggers a skill load, which gets buffered, which triggers another nudge.) Memory writes (`thatch_memory_remember`) and `thatch_extraction_done` drain the buffer and reset the missed-nudge counter. For child sessions (`childToParent.has(sessionID)`), also tracks metrics: `remember` with `overwrite:false` → new++, `overwrite:true` → updated++, `forget` → deleted++. This is a plugin hook, NOT a bus event — do not move it into the `event` handler; the event bus has no such event and it will silently never fire. |
-| `chat.message` | Two priority tiers: (a) if extraction buffer has interactions and the session is NOT in the `extracting` set (direct extraction in progress), **peeks** the buffer (does NOT drain it) and injects a synthetic text part carrying the extraction nudge + JSON payload — the buffer persists until the agent writes a memory or calls `thatch_extraction_done`, so ignored nudges repeat and escalate (polite → insistent → ALL-CAPS) via the `missedNudges` counter; (b) otherwise, embeds the user's prompt text with the in-process warm model, searches `db.search()` across repo + global, and pushes a recall nudge if matches exceed the threshold (default 0.55). The same embedding also feeds the prediction auto-fire: `db.scorePredictionNudge` scores the prompt against prediction matchers and injects a separate `[thatch] User decision model` nudge if any matchers clear the 0.45 threshold. Recall and prediction nudges fire independently (separate try/catch blocks, separate synthetic parts). Skipped entirely while the session is compacting (tool calls are blocked during summary generation). |
+| `chat.message` | Two priority tiers: (a) if extraction buffer has interactions and the session is NOT in the `extracting` set (direct extraction in progress), **peeks** the buffer (does NOT drain it) and injects a synthetic text part carrying the extraction nudge with the session ID and fetch tool name (not the full payload) — the sub-agent calls `thatch_get_extraction_payload` to retrieve the interactions as a tool response, keeping the full payload out of the main session's context window. The buffer persists until the agent writes a memory or calls `thatch_extraction_done`, so ignored nudges repeat and escalate (polite → insistent → ALL-CAPS) via the `missedNudges` counter; (b) otherwise, embeds the user's prompt text with the in-process warm model, searches `db.search()` across repo + global, and pushes a recall nudge if matches exceed the threshold (default 0.55). The same embedding also feeds the prediction auto-fire: `db.scorePredictionNudge` scores the prompt against prediction matchers and injects a separate `[thatch] User decision model` nudge if any matchers clear the 0.45 threshold. Recall and prediction nudges fire independently (separate try/catch blocks, separate synthetic parts). Skipped entirely while the session is compacting (tool calls are blocked during summary generation). |
 | `event` | Subscribes to all session bus events. `session.created`: records `childToParent` + `parentSnapshots` (shallow copy of the parent's buffer for snapshot-aware drain), then sends the session-start reminder via `client.session.prompt` carrying the hygiene heartbeat (pending dedup pairs, stale count, orphaned branch memories) when any signal is non-zero. `session.status` (idle): if the session is a child, drains its snapshot, fires a toast with `childMetrics`, and deletes the child session; if the session is a parent with pending tool interactions and not already extracting, calls `triggerExtraction` to create a direct-extraction child. `session.error`: requeues the parent's buffer (child died without draining). `session.deleted`: cleans up `childToParent`, `parentSnapshots`, `childMetrics`, and `extracting`. `session.compacted`: clears the compacting flag so `chat.message` nudges resume. |
 | `dispose` | Closes the DB. |
 
@@ -186,12 +186,13 @@ extraction cycle
   → nudge path (fallback): if triggerExtraction throws (create or prompt
     fails), the `extracting` set clears and the next chat.message sees
     pending entries with no extracting flag → peeks the buffer and injects
-    a nudge part with JSON payload; missed nudges escalate (polite →
+    a nudge part with session ID and fetch tool name; missed nudges escalate (polite →
     insistent → ALL-CAPS) via the missedNudges counter
     → drain: thatch_memory_remember (or thatch_extraction_done) clears the
       buffer and resets the missed-nudge counter
-    → agent loads thatch-fact-extractor skill, saves facts via
-      thatch_memory_remember
+    → agent dispatches a sub-agent that calls thatch_get_extraction_payload
+      to fetch the queued interactions, loads thatch-fact-extractor skill,
+      saves facts via thatch_memory_remember
   → MCP path (Claude Code/Cursor): unchanged — no SDK client, no child
     sessions; extract-queue.ts + flush-tools drives the nudge via hooks