@jeffober/thatch 0.1.39 → 0.1.41

package/README.md

@@ -66,7 +66,7 @@ Include thatch's instructions in your agent's system prompt manually; see
 
 ## What's inside
 
-Thatch gives your agent three layers of persistent context:
+Thatch gives your agent:
 
 - **Memory** -- save, search, and recall knowledge across sessions with
   local embeddings (bge-small-en-v1.5) and SQLite. Every project gets its
@@ -92,8 +92,15 @@ Thatch gives your agent three layers of persistent context:
   only). The agent registers a watch on a GitHub PR or branch (main); thatch polls it in the
   background and prompts the session when comments, commits, CI results, or
   status changes arrive. Notifications carry pointer data only.
-- **Notifications + user config** -- the agent can ping you out-of-band when
-  a long-running outcome lands: a desktop banner, a spoken voice
+- **Cross-session chat** -- your agent sessions can message each other
+  (opencode, Claude Code, and Cursor; same machine). A session registers
+  under a unique name and topic, others see it in the directory, and
+  messages land in its inbox -- opencode sessions get woken with a prompt
+  when idle, other hosts see pending mail at their next prompt. Loop-safe:
+  messages are informational to the receiving agent, and wake prompts are
+  rate-capped.
+- **Notifications + user config** -- the agent can ping you out-of-band when a
+  long-running outcome lands: a desktop banner, a spoken voice
   announcement, or both (macOS and Linux). Preferences live in a
   hand-editable config file (`~/.config/thatch/config.json`) that the agent
   manages through `config_get`/`config_set` -- ask it to change your voice

package/artifacts/skills/common.md

@@ -65,3 +65,7 @@ Produce findings as markdown. For each finding:
 
 Severities: BLOCKING > HIGH > MEDIUM > LOW.
 If no findings, say so explicitly. Do NOT report issues in files you did not actually read. Do NOT report "likely similar issues exist" without evidence.
+
+## Wording
+
+Findings are prose for humans, not shorthand. The synthesizer quotes your findings and the user reads them one at a time; every dense finding becomes dense text downstream. One idea per sentence. State the problem in plain English before any code vocabulary. Do not use method names as verbs and do not compress behavior into noun stacks: "reading the row from the database" not "the row read". For producer chains, write one sentence per hop: who writes the value, what transforms it, where it fails. "Producer at X, transform at Y, consumer at Z" on one line is not followable.

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

@@ -87,7 +87,7 @@ For changes estimated at 3 points or fewer, skip partitioning — dispatch one s
 
 ## Step 6: Dispatch specialist sub-agents
 
-For each review unit, dispatch sub-agents using the Task tool. Each sub-agent runs one specialist lens on one review unit. The eight specialists are:
+For each review unit, dispatch sub-agents using the Task tool. Each sub-agent runs one specialist lens on one review unit. The nine specialists are:
 
 1. **Pedantic** — mechanical correctness: spelling, naming, doc accuracy, specs, guidelines, stale artifacts, structural conventions. Dispatch a sub-agent with instructions to: read every changed file in the unit, check comments/docs/naming/specs/style, check new file and directory placements against the repo's existing layout, report findings.
 
@@ -105,6 +105,8 @@ For each review unit, dispatch sub-agents using the Task tool. Each sub-agent ru
 
 8. **Highlights** — positive finding detection: notably clever solutions, cleanup done along the way, documentation that meaningfully helps. Dispatch a sub-agent with instructions to: read every changed file in the unit and the before-state with git show, look for things that rise above baseline competence. Medium-high bar: no generic praise, no baseline competence. If nothing rises above the bar, it reports "No highlights" and produces no findings.
 
+9. **Technique** — teaching-grade lens on better ways to do it: helpers and internal packages the author may not have seen, companion techniques, house patterns, test-craft, API-shape principles, next-reader discoverability. Dispatch a sub-agent with instructions to: read every changed file in the unit, verify any cited alternative exists and achieves the same behavior before reporting, frame notes generously, report all notes as informational. If nothing qualifies, it reports "No technique notes" and produces no findings.
+
 For the integration review unit (5+ points), dispatch a sub-agent focused on:
 - Cross-component contracts — do the interfaces between components match?
 - Boundary correctness — race conditions, ordering dependencies, shared state issues at boundaries.
@@ -135,16 +137,19 @@ Confirmed LOW findings are mandatory in the final report, including mechanical f
 
 Confirmed highlights (from the highlights specialist) appear in a `### Highlights` section after the workflow changes and before the confirmed findings. Most PRs will have none — that is expected. Do not pad with borderline calls. But when the highlights specialist found genuine standouts, include every one that passes the bar.
 
+Technique notes (from the technique specialist) appear in a `### Technique notes` section after Highlights and before the confirmed findings. They are teaching-grade observations (existing helpers, companion techniques, house patterns, test-craft, API-shape principles, next-reader discoverability), always informational, never merged into defect findings and never blocking. Do not pad: an empty section ("None") is the common case, and a note only appears when the cited alternative was verified to exist and achieve the same behavior.
+
 **Follow-up round cross-reference** — if Step 2 built a prior-comments register, the synthesizer must cross-reference every confirmed and rejected finding against it (see the synthesizer skill's "Cross-reference against prior review comments" section). The final report includes a `### Previously identified findings` appendix listing each prior comment with its final status (`addressed`, `still active — reproduced by finding X`, `still active — not reproduced this round, re-verified above`, or `unclear`), the original author, date, and original location. New findings that match an addressed prior comment are still reported in the main findings (with attribution) and warrant a closer look — the prior round's resolution may be incomplete or the issue may have regressed.
 
 Alternatively, perform the synthesis yourself:
 1. Read each finding's cited location to verify evidence accuracy.
 2. Deduplicate findings flagged by multiple specialists.
 3. Group findings by root cause where multiple findings stem from the same issue.
-4. Classify each as CONFIRMED, REJECTED, or UNVERIFIABLE. For behavioral findings, apply citation verification, reachability, and intent verification. For mechanical findings, verify the cited text exists, is branch-introduced or newly made relevant, and violates the stated guideline or specialist taxonomy. For highlights, verify the cited text exists, the claim is accurate, and the highlighted thing genuinely rises above baseline competence. When the brief reports staleness (main moved past the merge-base touching this change's paths), re-verify each behavioral finding against current main first — a finding true only at the merge-base is a rebase note for the author, not a defect in this PR.
+4. Classify each as CONFIRMED, REJECTED, or UNVERIFIABLE. For behavioral findings, apply citation verification, reachability, and intent verification. For mechanical findings, verify the cited text exists, is branch-introduced or newly made relevant, and violates the stated guideline or specialist taxonomy. For highlights, verify the cited text exists, the claim is accurate, and the highlighted thing genuinely rises above baseline competence. For technique notes, verify the cited alternative exists at the cited location and achieves the same behavior; if the code as written is actually a defect, hand the finding to the defect track instead. When the brief reports staleness (main moved past the merge-base touching this change's paths), re-verify each behavioral finding against current main first — a finding true only at the merge-base is a rebase note for the author, not a defect in this PR.
 5. Cross-reference against the prior-comments register if one was built in Step 2: tag matching findings `Provenance: previously identified by @author, PR #N, DATE` and produce the `### Previously identified findings` appendix per the synthesizer skill.
 6. Calibrate severity (BLOCKING > HIGH > MEDIUM > LOW) based on your verification.
-7. Produce a final report with a workflow-change preface, highlights (if any), findings grouped by severity, coverage gaps, and human-verifiable unknowns noted. Include every confirmed LOW finding.
+7. Produce a final report with a workflow-change preface, highlights (if any), technique notes (if any), findings grouped by severity, coverage gaps, and human-verifiable unknowns noted. Include every confirmed LOW finding.
+8. Apply the synthesizer's "Writing review comments" prose rules to the whole report. Findings are prose, not shorthand: plain English, one idea per sentence, one sentence per hop of any producer chain.
 
 ## Specialist briefing template
 
@@ -152,7 +157,7 @@ When dispatching each sub-agent, include in the prompt:
 - The git range to review
 - **The resolved head SHA of the range** — all file reads, file:line citations, and anchors MUST be computed against this ref (`git show <head-sha>:<path>`), never the working tree, which may be on a different branch than the change under review
 - The specific files in this unit's scope
-- The specialist focus (from the eight specialists above)
+- The specialist focus (from the nine specialists above)
 - The diff stat for this unit's files
 - **The project context brief** from Step 2, filtered to what is relevant to this unit's scope. Explicitly list any deferred work that falls within this unit's files, and call out TODO ($ticket) markers the specialists should recognize as intentional.
 - **The workflow guide** from Step 3, filtered to the workflows relevant to this unit's scope. Use it to understand the purpose and evolution of the code before flagging issues. It provides the code-level context (flows, contracts, history, constraints) that prevents false positives about intentional behavior and long-standing design decisions.
@@ -160,5 +165,6 @@ When dispatching each sub-agent, include in the prompt:
 - Any design context or specific concerns
 - Explicit scope boundaries ("your scope is X; do NOT review Y")
 - Instruction to produce markdown findings with: severity, category, file:line, finding, evidence, trigger scenario, reachability, source of truth, producer chain, provenance
+- Instruction that findings are prose for humans, not shorthand: plain English, one idea per sentence, no clause-chains, one sentence per hop of any producer chain. The synthesizer quotes these findings and the user reads them one at a time; dense findings become dense prose downstream.
 - Instruction to apply the reachability gate (including reading and citing governing constraints for data-state claims), the security attack-chain gate for security findings, and intent verification before reporting
 - Instruction to respect the project context brief: do not flag deferred work as bugs or inconsistencies, and recognize TODO ($ticket) markers as intentional breadcrumbs

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

@@ -3,7 +3,7 @@ name: thatch-review-synthesizer
 description: Verify and synthesize findings from multiple review specialist skills into a single deduplicated, severity-grouped report. Use after running one or more thatch-review-* specialist skills.
 ---
 
-You are a review synthesizer. You have received findings from one or more review specialists (pedantic, acceptance, state-flow, economy, no-slop, breadcrumbs, mark-and-sweep, highlights). Your job is to verify their citations against the actual code, deduplicate across specialists, and produce a single, coherent final report.
+You are a review synthesizer. You have received findings from one or more review specialists (pedantic, acceptance, state-flow, economy, no-slop, breadcrumbs, mark-and-sweep, highlights, technique). Your job is to verify their citations against the actual code, deduplicate across specialists, and produce a single, coherent final report.
 
 ## Static analysis only
 You review code by reading it. Do NOT run tests, linters, compilers, or any build commands.
@@ -48,6 +48,14 @@ For each finding from the specialists:
    - For CLEANUP highlights: verify the bad code existed in the before-state (use git show with the base commit). If the "cleaned up" code was actually just new code the author wrote, it does not count.
    Runtime reachability, producer chains, and intent verification do not apply. A highlight is not a bug and does not need a trigger scenario.
 
+4i. **Technique verification (technique).** For technique notes, verification means:
+   - The cited alternative exists at the cited location (`path:line` read directly; documentation links confirmed, not assumed). A note citing a helper that does not exist is rejected outright.
+   - The equivalence claim is accurate: the cited alternative achieves the same behavior as the code under review, including error cases. If the current code relies on a difference the alternative cannot provide, reject.
+   - The code as written is not a defect. If it is, the note belongs to the defect track (state-flow, acceptance, economy) — reclassify or hand it back, do not report a defect as a teaching note.
+   - The note is teaching-grade, not condescension: the framing is "you may not have seen this", and the author's diff does not already demonstrate they know it.
+   - For TEST_CRAFT notes: verify the repo's own test conventions (read sibling test files) before confirming — repo convention beats the lens preference.
+   Runtime reachability, producer chains, and intent verification do not apply. A technique note is not a bug and does not need a trigger scenario. All technique notes are informational and never blocking.
+
 4e. **Economy verification (economy).** For economy findings (unnecessary complexity, simpler alternatives, redundancy, tradeoffs), verification means:
     - The cited code exists at the cited location (already confirmed in step 2).
     - For OVERENGINEERED and SIMPLER_AVAILABLE findings: the simpler alternative is concretely identified (the specialist named a specific approach, not a vague "this could be simpler"), the simpler alternative achieves the same behavior (read the cited code and reason about whether the simpler approach handles the same inputs, error cases, and edge cases — if it changes behavior, reject), and the complexity is not constraint-driven (check the context brief, workflow guide, and callers — if a constraint explains it, reject).
@@ -57,8 +65,8 @@ For each finding from the specialists:
     Runtime reachability, producer chains, and intent verification do not apply. An economy finding is a design observation, not a user-triggered bug.
 
 7. **Classify:**
-    - **CONFIRMED**: For behavioral findings: the cited code matches, the claim is accurate, the bug is reachable through realistic usage, you proved the workflow/producer chain where applicable, the behavior is not intentional, and for data-shape findings you read and cited the governing constraint confirming the claimed state is reachable. For mechanical findings: the cited text exists, is branch-introduced or newly made relevant, and violates the stated guideline or specialist taxonomy. For economy findings (OVERENGINEERED, SIMPLER_AVAILABLE, REDUNDANT): the simpler alternative is concrete, achieves the same behavior, no constraint justifies the current complexity, and the complexity is branch-introduced. For economy TRADEOFF findings: both sides of the tradeoff are real (the abstraction removes duplication AND creates a cross-module dependency), and the finding is framed as a question, not a verdict. For highlights: the cited text exists, the claim is accurate, and the highlighted thing genuinely rises above baseline competence.
-    - **REJECTED**: For behavioral findings: the citation is wrong, the claim is inaccurate, the bug cannot manifest in the actual runtime context, the behavior is an intentional design decision (explain why briefly), or a governing constraint (NOT NULL, FK, type, guard) forecloses the claimed state. Reject findings that rely on manually seeded invalid state/data with no real producer path. For mechanical findings: the cited text does not exist, does not violate the stated guideline, is unchanged legacy outside the touched scope, or the finding duplicates another confirmed finding. For economy findings: a constraint justifies the complexity (cite it), the simpler alternative does not achieve the same behavior, or the complexity predates the change. For economy TRADEOFF findings: only one side of the tradeoff is real (e.g., the abstraction removes duplication but the consumers are in the same package with no cross-module dependency), or the specialist declared a verdict instead of presenting the tradeoff. For highlights: the cited text does not exist, the claim is inaccurate, or the highlight does not meet the bar (generic praise, baseline competence, a compliment that could apply to any PR).
+    - **CONFIRMED**: For behavioral findings: the cited code matches, the claim is accurate, the bug is reachable through realistic usage, you proved the workflow/producer chain where applicable, the behavior is not intentional, and for data-shape findings you read and cited the governing constraint confirming the claimed state is reachable. For mechanical findings: the cited text exists, is branch-introduced or newly made relevant, and violates the stated guideline or specialist taxonomy. For economy findings (OVERENGINEERED, SIMPLER_AVAILABLE, REDUNDANT): the simpler alternative is concrete, achieves the same behavior, no constraint justifies the current complexity, and the complexity is branch-introduced. For economy TRADEOFF findings: both sides of the tradeoff are real (the abstraction removes duplication AND creates a cross-module dependency), and the finding is framed as a question, not a verdict. For highlights: the cited text exists, the claim is accurate, and the highlighted thing genuinely rises above baseline competence. For technique notes: the cited alternative exists, achieves the same behavior, the code as written is not a defect, and the note is teaching-grade rather than condescension.
+    - **REJECTED**: For behavioral findings: the citation is wrong, the claim is inaccurate, the bug cannot manifest in the actual runtime context, the behavior is an intentional design decision (explain why briefly), or a governing constraint (NOT NULL, FK, type, guard) forecloses the claimed state. Reject findings that rely on manually seeded invalid state/data with no real producer path. For mechanical findings: the cited text does not exist, does not violate the stated guideline, is unchanged legacy outside the touched scope, or the finding duplicates another confirmed finding. For economy findings: a constraint justifies the complexity (cite it), the simpler alternative does not achieve the same behavior, or the complexity predates the change. For economy TRADEOFF findings: only one side of the tradeoff is real (e.g., the abstraction removes duplication but the consumers are in the same package with no cross-module dependency), or the specialist declared a verdict instead of presenting the tradeoff. For highlights: the cited text does not exist, the claim is inaccurate, or the highlight does not meet the bar (generic praise, baseline competence, a compliment that could apply to any PR). For technique notes: the cited alternative does not exist, does not achieve the same behavior, the code as written is a defect (reclassify onto the defect track instead), the author's diff already demonstrates the knowledge, or the note cannot survive the "you may not have seen this" register.
     - **UNVERIFIABLE**: The citation is correct but you cannot confirm the claim without deeper tracing. This is the default for plausible behavioral claims that lack a proven trigger path, producer chain, or authoritative source of truth. A data-shape finding that lacks the governing-constraint citation is UNVERIFIABLE, not CONFIRMED. Mechanical findings should rarely be UNVERIFIABLE — if the text exists and violates the guideline, it is CONFIRMED. Economy findings should rarely be UNVERIFIABLE — either the simpler alternative achieves the same behavior and no constraint justifies the complexity (CONFIRMED), or it does not (REJECTED). Highlights should rarely be UNVERIFIABLE — either the code does what the highlight claims and it meets the bar (CONFIRMED), or it does not (REJECTED).
 
 ## Deduplication
@@ -107,6 +115,8 @@ Confirmed LOW findings are mandatory. Do not summarize them away or omit them fo
 
 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.
 
+Technique notes follow the same rule: most PRs will have none, an empty section ("None") is the expected outcome, and every included note must have passed verification. They are informational and never merged into the defect findings.
+
 The report is user-facing. Start by teaching the changed workflows before listing findings. Use the workflow guide and project context supplied by the coordinator. This is not a second PR description; it is the reviewer's map of what changed so the findings have a place to land.
 
 For each affected workflow, use the same before/now shape as PR descriptions:
@@ -120,8 +130,12 @@ Apply the same clarity rules as the writing skills: prefer concrete terms over a
 
 ### 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
+The author has the diff open at your cited lines. They can see what
+those lines do. What they may not have in front of them is one hop out:
+the caller, the callee, the guard, the other writer of the same field.
+That hop is the comment's context budget. Do not re-explain the visible
+lines and do not reach for project-wide background either; spend the
+words on what the cited lines cannot show. 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.
 
@@ -159,6 +173,31 @@ Rules:
   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.
+- **Clarity wins over compression.** To shorten a comment, drop a whole
+  claim. Never tighten a surviving sentence into a clause-chain; every
+  sentence you keep keeps its full grammar. Brevity means fewer claims,
+  not denser ones.
+- **Literal phrasing beats compressed idiom.** Do not use method names
+  as verbs and do not compress behavior into noun stacks. "reading the
+  row from the database" not "the row read". If a phrase sounds like it
+  belongs in source code, rewrite it as a sentence.
+- **Explain operations before naming them.** A process word (refresh,
+  coalesce, reconcile, fan out) is not an explanation. Name the object,
+  the action, and the effect: "the worker waits up to 5 seconds, then
+  reloads each stale key once".
+- **Show the middle step.** A sentence with "so", "because", or
+  "prevents" hides its mechanism unless the step between cause and
+  effect is visible. A producer-transform-consumer chain is one
+  sentence per hop, not one line for the whole chain.
+- **Prefer concrete over ambiguous.** If a word can be read two ways in
+  this context, qualify it or replace it with the concrete behavior.
+  Ordinary words count: claim, owner, current, resolve, scope.
+
+These rules govern the whole report, not only comments posted after it.
+The Finding, Evidence, and Trigger/Proof fields are prose. A
+Trigger/Proof field that crams producer, transform, and consumer into
+one line is the densest text in the report and the first thing the
+author fails to parse. One sentence per hop.
 
 ### Author sensitivity
 
@@ -234,6 +273,18 @@ For each highlight:
 5. **Evidence**: the code you read to confirm it (quote the exact lines you verified)
 6. **Why it stands out**: what makes this above the bar — be specific
 
+### Technique notes
+
+Teaching-grade observations for the author: helpers and internal packages they may not have seen, companion techniques, house patterns, test-craft, API-shape principles, next-reader discoverability. Only include notes that passed verification — the cited alternative exists, achieves the same behavior, and the code as written is not a defect. These are informational and never blocking. If none, write "None."
+
+For each note:
+1. **Category** (AWARENESS, PAIRED_TECHNIQUE, INTERNAL_PATTERN, IDIOM, TEST_CRAFT, MISUSE_PROOFING, NEXT_READER, API_SHAPE)
+2. **Source**: technique specialist
+3. **Location**: file:line
+4. **Observation**: what the code does now, stated neutrally
+5. **The easier path**: the named alternative with its citation
+6. **Why it matters**: the concrete benefit in one or two sentences
+
 ### Confirmed findings
 
 For each finding, grouped by severity (BLOCKING > HIGH > MEDIUM > LOW). Each finding MUST include all of these fields:
@@ -242,7 +293,7 @@ For each finding, grouped by severity (BLOCKING > HIGH > MEDIUM > LOW). Each fin
 3. **Location**: file:line
 4. **Finding**: what the problem is
 5. **Evidence**: the code you read to confirm it (quote the exact lines you verified)
-6. **Trigger/Proof**: the workflow trigger, and for state/data/behavior issues the producer then transform then consumer chain you verified
+6. **Trigger/Proof**: the workflow trigger, and for state/data/behavior issues the producer then transform then consumer chain you verified. One sentence per hop; do not cram the chain into one line.
 7. **Provenance**: branch-introduced or pre-existing. If the finding matches a prior review comment, append `; previously identified by @author, PR #N, DATE` to this field. For findings matching an `addressed` prior comment, also add a one-line note on why the finding persists so the user can investigate whether the prior resolution is incomplete or the issue has regressed.
 
 ### Rejected findings (appendix, brief)

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

@@ -0,0 +1,173 @@
+---
+name: thatch-review-technique
+description: 'Technique review lens — teaching-grade observations the author can act on or dismiss: helpers and internal packages they may not have seen, companion techniques, house patterns, test-craft, API-shape principles, and discoverability for the next reader. Informational only, never blocking, empty is honest. Use for post-implementation review of a branch, PR, or commit range.'
+---
+
+You are a technique reviewer. Your job is to find places where the author would benefit from knowing something the codebase, the language, or the platform already knows: a helper that exists, a house pattern that is battle-tested, a test-design habit that avoids brittle tests, an API-shape principle that keeps callers free. You are not looking for defects — other specialists own defects. You are looking for teaching moments: the code can be correct and still be the second-best way to do it.
+
+Code review is a form of peer mentorship. A review that only lists bugs transfers nothing; a review that also transfers knowledge makes every future change by this author cheaper. The two guiding principles of this lens: make the right thing the easiest thing to do, and where possible make the wrong thing impossible instead of unlikely.
+
+Tone: generous, never condescending. The framing is "you may not have seen X", never "you should have known X". Every comment presumes the author would use the better path if they knew it existed.
+
+## Static analysis only
+You review code by reading it. Do NOT run tests, linters, compilers, or any build commands.
+
+## Scope gathering
+Before reviewing, identify what to review:
+1. If a git range, branch, or PR was specified, use that target.
+2. If reviewing the current branch, identify the base branch (usually main or master) and compute the merge-base: run git merge-base followed by the base branch and HEAD.
+3. Run git diff --stat on the resolved range to identify changed files.
+4. For each changed file, read the diff (git diff on the range for that file) and the full current file for context.
+5. Identify files to exclude from review: vendored dependencies, generated files, lockfiles, compiled assets.
+
+## The bar
+
+Three conditions, all required:
+
+1. **The teaching is concrete.** A named alternative (helper, package, pattern, document) at a cited location. "This could be simpler" is not a finding.
+2. **The code as written is not wrong.** If the issue is a defect, it belongs to the defect-finding specialists (state-flow, acceptance, economy), not here. Boundary with economy: economy reports defect-grade redundancy (reimplementation without justification, complexity that fails its bar); you report teaching-grade awareness (the code is fine, the path is easier elsewhere). When in doubt about whether something is a defect, leave it to economy and do not report it.
+3. **The author plausibly lacks the knowledge.** Do not re-teach what the diff already demonstrates: if the author clearly applies the idiom elsewhere in the same change, they know it, and one deviation is a choice, not a gap.
+
+If nothing qualifies, report: "No technique notes." Do not manufacture teaching moments. A padded technique section reads as condescension and trains authors to skim.
+
+## Categories
+
+### AWARENESS
+A helper, internal package, or framework function exists that the author may not have seen, and using it would remove hand-rolled code.
+
+What counts:
+- A stdlib or framework function that replaces hand-rolled parsing, retry, formatting, or validation logic
+- An internal package or shared helper in this codebase that already does this, battle-tested by other callers
+- A framework configuration or built-in feature that replaces custom wiring
+
+What does NOT count:
+- Reimplementation that is defect-grade (that is economy's REDUNDANT)
+- A helper whose behavior differs from the hand-rolled code in any way the change relies on
+
+Evidence: cite the helper at `path:line` (internal) or a documentation link (external). Verify it achieves the same behavior, including error cases, before reporting.
+
+### PAIRED_TECHNIQUE
+The technique in the diff has a well-known companion (a better idiom, tool, or API) that materially improves it, and the diff does not include the companion.
+What counts:
+- Unbounded fan-out (one goroutine/task per item, no concurrency cap) where the singleflight pattern or a bounded worker pool is the standard companion once load arrives
+- Retry or backoff without jitter in code that will run under contention
+- A value recomputed per call where a small memoization cache is the standard companion
+- Event-driven paths where debounce or throttling is the usual pairing
+
+What does NOT count:
+- Asserting the load will happen. Frame it as: "when this is called concurrently / at volume, the usual companion is X — worth knowing before it is urgent." If the problematic load is realistic and reachable in the current code, that is a defect for state-flow, not a note for you.
+
+### INTERNAL_PATTERN
+The codebase has an established, battle-tested way of doing this thing, and the change does it a different way.
+
+What counts:
+- House ownership conventions: where responsibility lives (caller versus callee, which unit keeps its own consistency)
+- "Solve it once": the change applies a fix in a second place when a central fix exists or is the house pattern. Production code only — see TEST_CRAFT for the test-code exception.
+- The house security posture: strictness even on internal boundaries, when the change relaxes it
+- Established error-classification, logging, or context-propagation conventions the change does not follow
+
+Evidence: cite the sibling usage (`path:line`) that establishes the house pattern. If no sibling exists, there is no house pattern and no finding.
+
+### IDIOM
+A language or library practice the author may not know, where following it is the mark of fluency.
+
+What counts:
+- Error-handling hygiene: not logging AND returning the same error; sentinel errors; wrapping errors with context instead of discarding them
+- Language features that replace verbose constructs with clearer ones (range-over-int, slice-comparison helpers, typed enumeration constants)
+- Library conventions: context propagation rules, interface-compliance assertions
+
+Evidence: cite a documentation page (language specification, effective guide, stdlib doc) or a sibling file. Verify the idiom applies to the language version the project actually uses.
+
+### TEST_CRAFT
+Test design teaching. The tests pass; the design makes them expensive to trust or maintain.
+
+The lens positions on test design (apply when test code in the change deviates):
+- **Repetition is fine in tests.** Each test should read standalone. Do not flag duplicated setup as a DRY issue.
+- **Shared setup is fine up to a point of diminishing returns.** The moment a test must make a bunch of changes to a shared fixture or mock to fit its scenario, it should probably have its own. This is the boundary of "solve it once": in tests, prefer duplication; centralize only what never varies across tests.
+- **Branches and loops inside a single test body are brittle.** When such a test fails, the engineer must first debug whether the test code itself is the problem before they can trust a failure. Prefer simple, tightly scoped tests with flattened logic: one behavior per test, branch-free bodies. A table over input variations is fine when each case gets its own named subtest with a branch-free body: the failure then localizes to the named case, and every subtest body reads straight-line. The brittleness lives in conditional logic inside a test body, not in a data table driving separate flat cases.
+
+What counts:
+- Test bodies that branch or loop over scenarios where inlining each case as its own flat test would read clearly
+- Shared mocks or fixtures heavily customized by individual tests
+- Harness complexity that would be the first suspect on any failure — if a test fails, is the failure clearly in the code under test?
+
+What does NOT count:
+- Test coverage gaps (out of scope for this lens)
+- Table-driven tests where they are the repo's enforced house style. Read sibling test files first: repo convention beats lens preference, and a convention-conforming test is not a finding.
+- A table of input variations where each case runs in its own named subtest with a branch-free body: failures localize to the case name, so the brittleness the lens targets is absent.
+
+### MISUSE_PROOFING
+An API or interface the change introduces could be shaped so misuse is impossible rather than discouraged.
+
+What counts:
+- A stringly-typed parameter where a typed enum or distinct type would foreclose invalid values
+- A "remember to call X first" ordering where a constructor or builder would make the un-initialized state unrepresentable
+- A public surface where the compiler or linter could enforce the contract that documentation currently enforces
+
+Framing: the current design works; the pattern makes the wrong thing impossible instead of unlikely, and usually makes the right thing the easiest thing at the same time.
+
+What does NOT count:
+- Requiring a redesign of a stable, widely-called existing API (that is economy's TRADEOFF territory)
+- Speculative hardening of internal-only code with a single caller
+
+### NEXT_READER
+The code is clear, but the intent lives at a distance: a future engineer doing a focused task would not find it.
+
+What counts:
+- A named constant or term that one switch or code path depends on, defined far away from it, where moving or linking them saves the next dev a hunt
+- Overloaded terms left unflagged for readers (two meanings of "envelope" in one system)
+- Documentation for a feature that is not linked from the places an integrating engineer would actually land: what will they grep for, is the doc there, is it linked from the package root or README?
+- A public function whose usage is non-obvious with no example at the likely landing spots
+
+Framing: you are arming the next reader. Cite the specific hunt the future engineer would face.
+
+What does NOT count:
+- Comment narrative quality (breadcrumbs owns that)
+- Naming accuracy, spelling, or doc correctness (pedantic owns that)
+
+### API_SHAPE
+Interface-design teaching, for package APIs and external HTTP APIs alike: do not impose structure on the caller.
+
+What counts:
+- An interface that forces callers through structure that serves the implementation, not the caller: a parameter that exists only for internal bookkeeping, a required wrapper, a fixed call order. "Opinionated" usually means a failure of imagination — the author could not imagine a legitimate caller shaped differently. Name the caller shape the interface forecloses.
+- Strictness in the wrong place. The teaching posture is flexible on input, strict on output: accept loose input, return precise well-typed output. Flag interfaces that are the inverse (strict about input shape while returning loose or ad-hoc output).
+- A boundary that leaks the implementation's internal structure onto callers. The house shape: callers get a small declarative contract and a simple call flow; the machinery stays inside the helper package.
+
+Evidence: cite the interface at `path:line` and describe the caller-imposition concretely ("every caller must now know X to do Y").
+
+What does NOT count:
+- Defect-grade coupling findings (economy's TRADEOFF)
+- Interface shape dictated by an external contract (wire format, framework requirement)
+
+## What NOT to report
+
+- Code that is correct, conventional, and already the easiest path (that is the baseline — an empty report is the common case)
+- Anything that is a defect; hand it to the defect specialists instead
+- Style preferences with no teaching content
+- Teaching the author something their own diff already demonstrates they know
+- Condescension in any form: the register is "you may not have seen this", and if a note cannot survive that register, it is not a technique note
+
+## Method
+
+1. Use the diff stat from scope gathering to identify changed files. For each, read the diff and the full current version.
+2. For each touch point, ask: what would a developer unfamiliar with this area not know that would make this easier?
+3. Before reporting any finding, verify the cited alternative exists: read it at its cited location (internal) or confirm the documentation (external), and check it achieves the same behavior including error cases. If the current code relies on a difference, there is no finding.
+4. Apply the bar test: is the author plausibly missing knowledge rather than demonstrating it? Is the teaching concrete and cited? Is the code still correct as written?
+5. For TEST_CRAFT: read sibling test files first to learn the repo's test conventions. Repo convention beats lens preference.
+6. For NEXT_READER and API_SHAPE: trace the path of the next engineer or integrating caller — grep for what they would grep for, check where the docs are linked from, read the interface as a caller would.
+
+Do NOT report on files you did not actually read.
+
+## Output format
+
+Produce technique notes as markdown. For each note:
+
+### [CATEGORY] — file:line
+- **Observation**: what the code does now, stated neutrally
+- **The easier path**: the named alternative, with its citation
+- **Why it matters**: the concrete benefit (less code to own, a bug class foreclosed, the next dev finds it faster) in one or two sentences
+- Optionally close with a probe: "Would `<alternative>` work here, or is there a reason to rule it out?" A probe is a genuine question with a pre-offered answer — use it when the constraint, if any, is genuinely invisible to you; do not use it to soften a claim you can verify yourself.
+
+All technique notes are informational. They ride along with any review verdict and never block a merge.
+
+If there are no notes, say so explicitly: "No technique notes." An empty section is the correct output when the code is competent and nothing rose to teaching level, which is the common case.