@jeffober/thatch 0.1.21 → 0.1.24

package/README.md

@@ -21,12 +21,15 @@ everything runs on your machine.
 ```
 
 On next start, OpenCode npm-installs thatch and its tools are available
-immediately. For background extraction sub-agents:
+immediately. For async extraction (child sessions run in the background):
 
 ```bash
 export OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true
 ```
 
+Without this env var, extraction still works — the child session runs
+synchronously (fire-and-forget) instead of asynchronously.
+
 Then **prime your project memory** with by running `thatch prime` in your project directory.
 This will launch an `opencode` session to build an initial map of the code base and its architecture to seed the memory.
 
@@ -67,7 +70,7 @@ Include thatch's instructions in your agent's system prompt manually; see
 - **Prediction engine**: a statistical model of user decision-making
   preferences. When a prompt matches learned contexts, predictions fire
   alongside the recall nudge.
-- **Skills**: 19 skills for memory workflows, structured multi-specialist
+- **Skills**: 20 skills for memory workflows, structured multi-specialist
   code review, change walkthroughs, and writing tasks (PR descriptions,
   tickets, PR splitting).
 

package/artifacts/skills/common.md

@@ -18,6 +18,9 @@ For every potential finding, you MUST describe a concrete scenario where a real
 
 Before claiming a value can hold a problematic state (NULL, orphaned, out-of-range, wrong-type), read the artifact that governs that state: the column definition, type declaration, FK/NOT NULL constraint, validation, or guard. Quote it in your finding. If a schema constraint, type, or guard makes the state unreachable, it is not a finding. "The join could drop rows" requires proving a droppable row can exist — cite the constraint that permits it.
 
+## Security attack-chain gate
+For any finding labeled a security concern, spell out what an attacker would actually need: the capability they must hold, the entrypoint they reach, the exploit path, and the impact. A label is not a finding. A dead CSP allowlist entry or an unused dependency on the supply chain is only a concern given a separate injection bug and a compromise path to exploit it. Size it honestly: name the prerequisites and let the reader judge. Most security observations land on chore or nitpick rather than issue, because the attack chain requires conditions the application does not create. Do not report a security finding without the chain that makes it real.
+
 ## Intent verification
 Before flagging behavior as a bug, verify intent:
 1. **Trace callers.** Read every caller of the cited code. The behavior may be intentional given how the feature is actually used.
@@ -45,6 +48,9 @@ Code may contain `TODO ($TICKET-ID): description` comments that mark intentional
 - DO flag it if you can verify the referenced ticket is closed or merged (the TODO is now stale).
 - If your briefing includes a context brief that lists the deferred work, use it to determine whether the ticket is still pending.
 
+## Severity calibration
+Inflating one finding is expensive, because it is the reason the next one gets discounted. A reader who sees an over-labeled finding will trust the next label less. Pick the severity that matches the actual impact, not the one that sounds cautious. When unsure, the lower label is correct.
+
 ## Output format
 Produce findings as markdown. For each finding:
 

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

@@ -53,7 +53,7 @@ Dispatch a sub-agent using the Task tool to research the code workflows affected
 
 The sub-agent produces a code guide with one section per affected workflow or feature. Wait for it to complete and collect the guide.
 
-This guide gives specialists the code-level context (purpose, data flow, evolutions, constraints) they need to avoid false positives about intentional behavior and long-standing design decisions, and reduces duplicate code-tracing across the six specialist lenses.
+This guide gives specialists the code-level context (purpose, data flow, evolutions, constraints) they need to avoid false positives about intentional behavior and long-standing design decisions, and reduces duplicate code-tracing across the seven specialist lenses.
 
 For small changes (a single file or trivial diff), you may do this research inline instead of dispatching a sub-agent. Use your judgment: if the workflow research would require reading more than 3-4 files, dispatch a sub-agent to preserve your context for orchestration.
 
@@ -83,11 +83,11 @@ 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 six 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 seven specialists are:
 
 1. **Pedantic** — mechanical correctness: spelling, naming, doc accuracy, specs, guidelines, stale artifacts. Dispatch a sub-agent with instructions to: read every changed file in the unit, check comments/docs/naming/specs/style, report findings.
 
-2. **Acceptance** — behavioral/product review: UX coherency, behavioral delta, integration effects, user assumptions. Dispatch a sub-agent with instructions to: read the before-state with git show, evaluate behavioral changes, walk the user journey, check integration boundaries.
+2. **Acceptance** — behavioral/product review: UX coherency, behavioral delta, integration effects, user assumptions, ticket alignment, description accuracy. Dispatch a sub-agent with instructions to: read the before-state with git show, evaluate behavioral changes, walk the user journey, check integration boundaries, compare the diff against ticket scope and PR description claims.
 
 3. **State Flow** — data flow and contracts: module boundaries, implicit FSMs, error propagation, separation of concerns. Dispatch a sub-agent with instructions to: trace contracts across module boundaries, trace end-to-end paths, identify implicit state machines, check error paths.
 
@@ -97,11 +97,22 @@ For each review unit, dispatch sub-agents using the Task tool. Each sub-agent ru
 
 6. **MarkAndSweep** — mechanical change completeness: renames, flag removals, API substitutions. Dispatch a sub-agent with instructions to: extract old identifiers from removed diff lines, sweep the whole repo with git grep for stragglers, verify touchpoint neatness (dead branches, orphaned imports, stale comments, config/test residue). Self-selects: if the diff shows no mechanical change patterns, it reports "No mechanical change detected" and produces no findings.
 
+7. **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.
+
 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.
 - Top-level coherence — does the overall change make sense as a unit?
 
+## Step 6b: Handle timed-out or failed specialists
+
+Background sub-agents can hang or time out. The thatch plugin watchdog cancels sub-agents stuck for longer than the configured timeout (default 5m) and injects a synthetic notification into the parent session.
+
+When a specialist times out or fails:
+1. **Re-dispatch once.** Re-dispatch the same specialist with the same briefing. Do not re-dispatch more than once — a second failure likely indicates an intractable prompt, not a transient hang.
+2. **Simplify on re-dispatch.** If the first re-dispatch also fails or times out, note the gap in the synthesis: "The [specialist] lens could not be completed due to repeated sub-agent failures. The review may have gaps in [area]." Do not retry again.
+3. **Never silently drop a specialist.** Every specialist must appear in the final report — either with findings or with an explicit coverage-gap note explaining why it could not run.
+
 ## Step 7: Synthesize
 
 After all sub-agents complete, load the thatch-review-synthesizer skill to verify findings, deduplicate across specialists, classify (CONFIRMED/REJECTED/UNVERIFIABLE), and produce the final report.
@@ -116,23 +127,25 @@ The final user-facing report MUST begin with a concise explanation of the workfl
 
 Confirmed LOW findings are mandatory in the final report, including mechanical findings (pedantic, no-slop, breadcrumbs, docs, naming, style, comments). Do not omit them for being non-functional.
 
+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.
+
 **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.
+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.
 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, findings grouped by severity, and coverage gaps noted. Include every confirmed LOW finding.
+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.
 
 ## Specialist briefing template
 
 When dispatching each sub-agent, include in the prompt:
 - The git range to review
 - The specific files in this unit's scope
-- The specialist focus (from the six specialists above)
+- The specialist focus (from the seven 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.
@@ -140,5 +153,5 @@ 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 to apply the reachability gate (including reading and citing governing constraints for data-state claims) and intent verification before reporting
+- 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-fact-extractor.md

@@ -17,7 +17,8 @@ You will be given a JSON payload with:
 3. Do not save session-specific state, ephemeral debugging details, or info already in CLAUDE.md.
 4. Apply the durability test before saving: will this still be true and useful in a future session that knows nothing about this branch, commit, or session? If not, skip it. Do not store point-in-time values (migration indices, line numbers, file counts), commit hashes or branch history narratives (git is the source of truth), or anything re-derivable from the codebase faster than recalling it.
 5. Write for a future session with zero current context. No "we", "our session", "just now".
-6. Your final message must be exactly: "Extraction complete." — do not list or summarize what you saved. The memories are in the store; the parent session does not need a report.
+6. Call thatch_extraction_done to mark the run complete. Do this even when nothing was worth saving: the parent session holds the buffered interactions until a completion signal arrives, and a memory write is not one on a no-save run.
+7. Your final message must be exactly: "Extraction complete." — do not list or summarize what you saved. The memories are in the store; the parent session does not need a report.
 
 ## What to extract
 

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

@@ -51,7 +51,21 @@ For each user-facing feature touched by the changes:
 - Could the change break workflows that span multiple features?
 - Are there shared resources (config, state, files) where the change creates new conflicts or race conditions visible to users?
 
-### 6. Prove the workflow inputs
+### 6. Check ticket alignment
+If your briefing includes a ticket or PR description with stated scope or acceptance criteria, compare the diff against what was actually asked for:
+- Is anything in scope that the diff does not deliver? Missing work is a finding, not a deferred item, unless the context brief explicitly marks it as deferred.
+- Is there work in the diff that falls outside the stated scope? Out-of-scope work may belong in a separate PR.
+- If no ticket is linked and the PR description has no acceptance criteria, skip this step.
+
+### 7. Check description accuracy
+Compare the PR title and body against the actual diff:
+- Do claims in the description match what the code does? Flag specific claims that contradict the diff.
+- Is the description stale or templated (copy-pasted from another PR, describing work that is not in this diff)?
+- If the description has a Testing section, does it reflect what the tests actually do? Flag a Testing section that lists steps the diff does not cover.
+
+This is about metadata honesty. A description that misrepresents the code wastes the time of future git-archaeologists and human reviewers who rely on it to orient.
+
+### 8. Prove the workflow inputs
 For any finding that depends on bad state, malformed data, or surprising cross-feature behavior, identify:
 - Which user action or entrypoint starts the workflow
 - Which code path produces the relevant state/data
@@ -66,5 +80,7 @@ If the issue only exists when someone manually fabricates invalid state/data out
 - **INCONSISTENCY**: Mismatch with existing behavior, conventions, or user expectations
 - **SILENT_FAILURE**: Operation appears to succeed but doesn't do what user expects
 - **BREAKING**: Previously working workflow is now broken or produces wrong results
+- **SCOPE_GAP**: The diff is missing work the ticket or PR description says it delivers, or includes work outside the stated scope
+- **DESCRIPTION_DRIFT**: The PR title or body does not match the actual diff — claims that contradict the code, a stale description, or a Testing section that does not reflect reality
 
 Report findings as behavioral observations, not code complaints. Do NOT report internal code quality issues unless they directly manifest as user-visible problems.

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

@@ -96,6 +96,7 @@ For each prior comment, record:
 - Original commit SHA, file, line range (or `summary` for non-inline review)
 - Comment body (quoted)
 - The semantic claim raised (what the reviewer said was wrong — paraphrase the core issue, one sentence)
+- Resolution rationale, if the thread was resolved: the recorded reason why the concern was settled. Read the reply that resolved the thread (often the last comment before the resolve action), the commit message that addressed it, or the author's own follow-up. Capture the reasoning in one sentence. This is what keeps a future round from re-raising a settled point — the rationale, not just the resolved flag, tells you *why* it was dismissed.
 - VCS resolve state if available (GitLab `resolved`/`resolved_by`; GitHub `isResolved` via GraphQL if accessible)
 
 #### Addressed-check methodology
@@ -145,6 +146,7 @@ List the prior-comments register (one entry per prior comment):
 - Author and submitted date
 - Original location (`file:line @ commit-SHA`, or `summary review`) and current HEAD location (`file:line`) if locatable
 - The semantic claim raised (one-sentence paraphrase)
+- Resolution rationale, if the thread was resolved (one-sentence paraphrase of why it was settled)
 - Preliminary status: `addressed` / `still active` / `unclear` — with the code-state evidence (a short quote from the current HEAD that supports the verdict)
 - VCS resolve flag if applicable (and any disagreement with the code-state verdict)
 

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

@@ -0,0 +1,111 @@
+---
+name: thatch-review-highlights
+description: 'Positive finding detection — notably clever solutions, cleanup done along the way, documentation that meaningfully helps. Medium-high bar: no generic praise, no baseline competence. Use for post-implementation review of a branch, PR, or commit range.'
+---
+
+You are a highlights reviewer. Your job is to find things in the changed code that are genuinely worth calling out: clever solutions, cleanup done along the way, documentation that will save someone time. You are NOT a praise generator. Most PRs will have zero highlights, and that is fine.
+
+## 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
+
+Medium-high. You are looking for things a senior engineer would pause on and think "oh, that is a nice way to handle that." Not things any competent developer would write. Not things that follow the project's existing conventions. Not things that are simply correct.
+
+The test: could this compliment apply to any well-written PR? If yes, it does not meet the bar. A highlight must be specific to what THIS author did in THIS change, and it must be above the baseline of "wrote correct code."
+
+If nothing rises above the bar, report: "No highlights — nothing rose above the bar." Do not manufacture positives. An empty highlights section is honest. A highlights section full of generic praise is worse than none at all, because it reads as inauthentic and trains people to ignore the section.
+
+## What to look for
+
+### CLEVER_SOLUTION
+An approach to a problem that is notably better than the obvious solution. The kind of thing where you would tell a coworker "look at how they handled this."
+
+What counts:
+- Solving a hard problem with an approach that is simpler, more robust, or more efficient than what the obvious path would produce
+- Using a language or framework feature in a way that eliminates a whole class of potential bugs
+- A data structure or algorithm choice that makes a subtle correctness or performance problem disappear
+
+What does NOT count:
+- Using the standard pattern for the framework (that is following conventions, not cleverness)
+- Writing correct code (that is the baseline)
+- Using the right data structure for an obvious case (that is competence)
+
+### CLEANUP
+The author found existing code that was bad and fixed it, even though the fix was not required for their change to work. They did the dishes while cooking.
+
+What counts:
+- Cleaning up code that was genuinely gross: dead code, confusing logic, broken comments, copy-paste duplication that was actively harmful
+- The cleanup was not part of the task. The author went out of their way to improve the codebase.
+- The cleanup meaningfully improves readability, maintainability, or correctness for future developers
+
+What does NOT count:
+- Formatting or renaming in new code the author just wrote (you wrote it, of course it is clean)
+- Refactoring that was the explicit goal of the PR (you were asked to do it)
+- Deleting code that the change made dead (that is just completing the change)
+- Tidying that is cosmetic and does not affect understanding
+
+### DOC_IMPROVEMENT
+Documentation that was added or improved and will save future developers real time. Not just "added a docstring" — documentation that explains a non-obvious concept, clarifies a confusing workflow, or warns about a gotcha.
+
+What counts:
+- A comment that explains WHY code behaves a certain way, where the why is non-obvious and the reader would have been confused without it
+- Documentation that fills a gap that would have caused someone to waste time or make a wrong assumption
+- A comment that translates a subtle contract or invariant into plain language
+
+What does NOT count:
+- A one-line docstring on a new function that just restates the function name
+- JSDoc/docstrings that describe parameters and return types (that is boilerplate, not insight)
+- Comments that describe WHAT the code does when the code is already self-explanatory
+
+### GOOD_INSTINCT
+The author anticipated a failure mode or edge case that is not obvious and handled it correctly. Or they chose the right thing when the easy thing would have been wrong.
+
+What counts:
+- Handling an edge case that is realistic but easy to miss, where the handling is correct and the failure mode is not obvious
+- Choosing a more careful approach over a faster but riskier one, when the risk is real and the carefulness is warranted
+- Adding a guard or validation that prevents a subtle bug that would have been hard to trace
+
+What does NOT count:
+- Standard error handling that any developer would write (null checks, try/catch)
+- Defensive code for states that cannot actually occur (that is noise, not instinct)
+- Handling edge cases that the framework or language already handles
+
+## What NOT to highlight
+
+- Code that simply follows the project's existing conventions
+- Tests that cover the new functionality (that is expected, not noteworthy)
+- Code that is clean because it was written fresh
+- Correct use of types, interfaces, or abstractions (that is the baseline)
+- Any compliment so generic it could apply to any PR
+
+## Method
+
+1. Use the diff stat from your scope gathering to identify changed files.
+2. For each changed file, read the full current version. Also read the diff to understand what the author added versus what was already there.
+3. For CLEANUP findings, use git show with the base commit to read the ORIGINAL version. You need to see what was there before to judge whether the author cleaned it up. A cleanup highlight requires that the bad code existed before this change and the author chose to fix it.
+4. For each potential highlight, apply the bar test: is this above baseline competence? Is this specific to what this author did? Could this compliment apply to any PR?
+5. If the highlight passes the bar, report it with the exact quoted code and a concrete explanation of why it stands out.
+
+Do NOT report on files you did not actually read.
+
+## Output format
+
+Produce highlights as markdown. For each highlight:
+
+### [CATEGORY] — file:line
+- **Highlight**: what the good thing is, in one sentence
+- **Evidence**: exact code quoted from the cited location (copy-paste, do not paraphrase)
+- **Why it stands out**: what makes this above the bar — be specific about what the author did and why it is better than the obvious or baseline approach
+
+Categories: CLEVER_SOLUTION, CLEANUP, DOC_IMPROVEMENT, GOOD_INSTINCT.
+
+If no highlights, say so explicitly: "No highlights — nothing rose above the bar." Do not pad the section with borderline calls to avoid an empty report. An empty highlights section is the correct output when the code is competent but unremarkable, which is the common case.

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, no-slop, breadcrumbs, mark-and-sweep). 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, 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.
 
 ## Static analysis only
 You review code by reading it. Do NOT run tests, linters, compilers, or any build commands.
@@ -43,10 +43,17 @@ For each finding from the specialists:
    - 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.
    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:
+   - The cited text exists at the cited location (already confirmed in step 2).
+   - The claim is accurate: the code actually does what the highlight says it does.
+   - The bar is met: the highlighted thing is genuinely above baseline competence, not generic praise. Apply the highlights skill's own bar test — could this compliment apply to any well-written PR? If yes, reject it.
+   - 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.
+
 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.
-   - **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.
-   - **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.
+   - **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 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 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).
+   - **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. 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
 
@@ -90,6 +97,8 @@ You MUST produce the full report structure below. Do not simplify or omit sectio
 
 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 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.
+
 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:
@@ -118,6 +127,18 @@ For each affected workflow:
 2. **N/A**
    - **NOW** — _one sentence describing a new stage this PR adds._
 
+### Highlights
+
+Things the author did that are genuinely worth calling out: notably clever solutions, cleanup done along the way, documentation that will save time, good instincts on subtle edge cases. Only include highlights that pass the bar — above baseline competence, specific to this change, not a compliment that could apply to any PR. If none, write "None."
+
+For each highlight:
+1. **Category** (CLEVER_SOLUTION, CLEANUP, DOC_IMPROVEMENT, GOOD_INSTINCT)
+2. **Source**: highlights specialist
+3. **Location**: file:line
+4. **Highlight**: what the good thing is
+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
+
 ### Confirmed findings
 
 For each finding, grouped by severity (BLOCKING > HIGH > MEDIUM > LOW). Each finding MUST include all of these fields:
@@ -155,3 +176,7 @@ If no prior-comments register was provided (local-branch review or first round o
 ### Coverage gaps
 
 Note which files or areas were NOT covered by any specialist.
+
+### Human-verifiable unknowns
+
+Flag conclusions that rest on something static analysis cannot reach: a rollout state, a config value in a different environment, a deploy order, a feature flag setting, a migration that has not run. These are things a human reviewer can check and the review cannot. Each entry names the unknown and where to check it. If none, write "None."

package/artifacts/skills/ticket-description.md

@@ -44,7 +44,7 @@ Sections, in order: SYNOPSIS, PROBLEM, BACKGROUND (conditional), PROPOSED APPROA
 
 **SYNOPSIS, PROBLEM, PROPOSED APPROACH, and ACCEPTANCE CRITERIA are mandatory.** A small ticket gets short sections, not fewer sections. Conditional sections appear only when warranted; omit them when empty. Never emit an empty header.
 
-**Scale the body to the work's conceptual size.** A one-line fix gets a one-line PROBLEM, a one-line PROPOSED APPROACH, and one or two acceptance criteria. A multi-PR feature gets full sections with real depth. The implementer should be able to start work after reading the ticket, but they should not have to read a novel to fix a guard clause.
+**Scale the body to the work's complexity, not its size in files or lines.** Estimate complexity by how much new mental model the implementer must build (see the point-based budgets in Length and style). A one-line fix gets a one-line PROBLEM, a one-line PROPOSED APPROACH, and one or two acceptance criteria. A multi-PR feature gets full sections with real depth. The implementer should be able to start work after reading the ticket, but they should not have to read a novel to fix a guard clause. Most of this skill's guidance exists to tame large tickets; applying it wholesale to a small one produces exactly the bloat the skill warns against.
 
 ### SYNOPSIS
 
@@ -66,11 +66,13 @@ The reader should know what the problem is before they read why it happens.
 
 No solution yet. The reader should finish this section agreeing there is something to address, even with zero code knowledge.
 
-Cover three things, each in its own paragraph:
+Cover three things, each in its own paragraph when the ticket has the complexity to warrant it:
 1. **What is wrong**, concretely. Name the component, the behavior, and the failure mode.
 2. **Why it matters.** Incident history, risk rating, customer impact, or "preventive: blocks a class of bug we keep almost-hitting."
 3. **Hazard rating and motivation.** How likely is the bad outcome, and under what conditions? Then answer "why now?": if the risk is low, what motivates this ticket? A prior PR identified it as a follow-up, the API still permits a failure shape, or the next planned change would make it worse. The lead's question is "should I prioritize this?" - give them the answer. _PLAT-135's ticket did this well: it named the cross-wait, then said "why it never fired" and rated the window as once-per-process cold load._
 
+A small ticket covers all three in a single paragraph; split into one paragraph per topic only when the content earns it.
+
 If the problem is preventive (no current defect), say so plainly. Then say why it is worth fixing despite the low risk.
 
 ### BACKGROUND (conditional)
@@ -89,6 +91,8 @@ Omit when the problem is self-contained. A one-line "follow-up from #6838" can l
 
 The design concept. Not a full implementation plan. Enough that the implementer knows the direction: "load key material outside the mutex" not "restructure ActiveKey to use cachedKey/publish helpers with a publish function that zeroizes the loser's DEK." The implementer writes the implementation plan; the ticket sets the compass heading.
 
+Present each mechanism in one short paragraph: what it does, plus the constraint that justifies its existence. Keep a justification when it answers an objection the reader will have (a lock that looks redundant, a retry that looks pointless). Compress failure-mode sagas to their consequence: "a leaked lock blocks every later attempt" carries what a paragraph of driver internals would. Reasons of the form "why not X" (no metric, no kill switch, no singleflight) go in NOTES as declined alternatives.
+
 For investigative tickets, this is "investigate X and propose a solution" rather than a concrete approach. Say so explicitly so the implementer knows the ticket expects analysis before implementation.
 
 This is where the ticket diverges most from a PR description. A PR description describes a change that already happened. A ticket proposes one that hasn't. The prose is prescriptive ("the fix should...") rather than descriptive ("this PR moves...").
@@ -105,7 +109,9 @@ Bad criteria are vague:
 - "improve the locking situation" (untestable)
 - "restructure ActiveKey" (implementation detail, not a behavior)
 
-If the criterion has a test shape, name it: "SetMaxOpenConns(1) with the connection held by a tx that also resolves the key." This gives the implementer the test design without dictating the implementation.
+If a criterion's test design is non-obvious, name the test shape: "SetMaxOpenConns(1) with the connection held by a tx that also resolves the key." This gives the implementer the test design without dictating the implementation. "Tested explicitly" is not a test shape.
+
+Keep the list coarse: three to seven criteria cover most tickets. This section defines "done"; it is not a test inventory. Merge parallel checks that verify the same behavior under different triggers. Drop criteria that restate PROPOSED APPROACH as a checklist - the criterion must add an observable gate, not echo the design.
 
 ### RELEASE PLAN (conditional)
 
@@ -115,7 +121,7 @@ Rollout strategy for tickets that change production behavior. Only when the chan
 - Deploy sequence (which services, in what order).
 - Rollback path (what to do if it goes wrong).
 
-A pure internal refactor with no operator-visible behavior change does not need this section. A migration that gates on a backfill completing does.
+A pure internal refactor with no operator-visible behavior change does not need this section. Neither does a change whose rollout is a normal deploy: if the only available bullets say "nothing special happens," omit the section - its absence is the nothing-special signal. A migration that gates on a backfill completing, or a revert that is not free, does need it.
 
 ### VALIDATION (conditional)
 
@@ -129,10 +135,12 @@ Only when prod verification is non-trivial. A pure refactor with good tests does
 
 ### DEPENDENCIES (conditional)
 
-Blocking relationships and ordering constraints. "Blocked by PLAT-126" is the tracker field; the _why_ belongs here: "PLAT-125 partitions by location_fingerprint, so it can only run after backfill completes (count == 0), not merely after PLAT-124 merges." That kind of nuance is what prevents a well-intentioned lead from reordering the queue.
+The tracker's blocker links carry the what; this section carries only what links cannot. Write a bullet when there is a _why_ the link cannot express: "PLAT-125 partitions by location_fingerprint, so it can only run after backfill completes (count == 0), not merely after PLAT-124 merges." That kind of nuance is what prevents a well-intentioned lead from reordering the queue. "Blocked by PLAT-126" with nothing to add is the tracker field - set the link there and omit the bullet.
 
 Distinguish hard data dependencies (cannot run until X completes) from soft dependencies (should run after X for cleanliness, but technically works independently). Say which kind it is.
 
+If every bullet would restate a tracker link, omit the section and set the links.
+
 ### NOTES
 
 Always a `## NOTES` markdown header. Never a bare `Notes:` line ending a section.
@@ -195,12 +203,24 @@ These are hard rules, not suggestions.
 
 ## Length and style
 
-Target: the implementer can start work after one read. The lead can prioritize after reading SYNOPSIS and PROBLEM.
+Target: the implementer can start work after one read. The lead can prioritize after reading SYNOPSIS and PROBLEM. Err on the shorter side.
+
+Estimate the ticket's **complexity** (how much new mental model the implementer must build), not its size in files or lines. Complexity drives the word budget the way scrum points drive effort estimates:
+
+- **1 point** (one guard, one flag, one constant): the implementer needs to know what to change, not a lesson in the subsystem. ~100-200 words. SYNOPSIS one line, PROBLEM 2-4 sentences (still rate the hazard, even if it is "no current defect"), PROPOSED APPROACH 1-2 sentences, one to three acceptance criteria.
+- **2-3 points** (new function, restructured flow, multi-file refactor): the implementer needs a before/after they cannot infer from the code alone. ~200-400 words. Full mandatory sections; BACKGROUND only when prior work or project context earns it.
+- **5 points** (new feature, migration sequence): the implementer needs a mental model they do not have yet. ~400-600 words. RELEASE PLAN, VALIDATION, and DEPENDENCIES when prod coordination warrants.
+- **8 points** (multi-PR effort, subsystem redesign, constraint-dense work): ~800-1100 words. Complex tickets legitimately need more text; spend it on context and starting state, not on repetition. If PROPOSED APPROACH is longer than the rest of the ticket combined, the ticket is probably a design doc wearing a ticket costume; split it.
 
-Scale the body to the work's conceptual size:
-- Small fix (one guard, one flag, one constant): one paragraph per mandatory section, one to three acceptance criteria. ~20-line ceiling.
-- Moderate change (new function, restructured flow, multi-file refactor): full sections with real depth. No hard ceiling, but each paragraph earns its place.
-- Large change (new feature, multi-PR effort, migration sequence): full sections plus RELEASE PLAN and VALIDATION. May run a full page. If PROPOSED APPROACH is longer than the rest of the ticket combined, the ticket is probably a design doc wearing a ticket costume; split it.
+Estimate by: how many new concepts the implementer must learn, whether the problem and approach have non-obvious mechanics, whether the work spans multiple workflows or systems. Not by files the change will touch or sections present. A mechanical multi-file rename is 1 point. A one-line fix with subtle semantics is 2-3.
+
+**When a ticket runs long, take the section-level levers first.** Omit RELEASE PLAN, VALIDATION, DEPENDENCIES, or NOTES when they carry nothing a normal deploy or the tracker links already say. Coarsen ACCEPTANCE CRITERIA. Compress PROPOSED APPROACH failure sagas to their consequences. These levers remove duplication, not knowledge.
+
+**Then step up the abstraction ladder.** Do not compress terminology or cut connective tissue to hit a word count. Instead, replace a sequence of mechanism details with the principle that subsumes them.
+
+Example: instead of six claims about how a connection pool reuses connections, how session locks are session-scoped, how a lock taken by one statement does not guard the next, and how nothing reports the mismatch, write: "Some Postgres features attach to the connection, not the statement. The pool freely reuses connections between statements, so state set by one statement may not be there for the next, and nothing reports the mismatch." Same understanding, fewer words, no compression. The mechanism details belong in the linked design doc or the code itself, not in the ticket.
+
+Brevity means fewer ideas, not compressed claims. If the ticket is still too long after the levers and the ladder, cut the lowest-value claim entirely. Do not cut the connective tissue that makes the remaining claims parse on first read. The knowledge build-up - each section introducing what the next one needs - survives every trim; what goes is redundancy.
 
 Inside sections, telegraphic bullet style is fine for criteria and plans: lowercase start, abbreviations (`w/`, `1x`, `~`), parenthetical shorthand. Full sentences for PROBLEM and BACKGROUND prose.
 
@@ -231,6 +251,8 @@ Read project context when the request, existing ticket, code comments, branch na
 
 Use available source material: linked tickets, linked PRs, nearby docs, code comments, commit messages, and project memory. Build a private term map: term -> plain behavior -> source. Do not dump the map into the ticket. Use it to write the shortest useful BACKGROUND.
 
+When rewriting an existing ticket, mine the old text for facts - harm statements, platform behaviors, traps already discovered - but draft the new description from the sources, not from the old text. Editing the old ticket inherits its phrasing and its habits; the rewrite should stand on the plan docs, the code, and the mined facts.
+
 If a term or dependency controls the work and you cannot resolve it from available context, stop and ask the user. Do not guess. Do not write around the missing definition with vaguer words.
 
 Put project context in BACKGROUND only when it helps the implementer start work or helps a lead schedule it correctly. Omit generic backstory.
@@ -389,14 +411,14 @@ That reading alone conveys the shape, scope, and gates of all three tickets.
 1. **Gather**: read the code the ticket references. Check `git log` for recent changes to the same files. Identify the problem, the prior work, and the proposed direction.
 2. **Search before create**: search Linear/Jira for likely duplicate tickets. If one exists, surface it before drafting or filing.
 3. **Codebase comparison**: verify the problem still exists in the current code. If it was already fixed, tell the user. If it was partially mitigated, note the mitigation.
-4. **Read project context for planned work**: if the ticket is part of a larger project, depends on prior work, uses unexplained project terms, or has scheduling dependencies, read the linked tickets, PRs, docs, comments, and memory before drafting. Build a private term map. If a term or dependency controls the work and you cannot resolve it, ask the user.
+4. **Read project context for planned work**: if the ticket is part of a larger project, depends on prior work, uses unexplained project terms, or has scheduling dependencies, read the linked tickets, PRs, docs, comments, and memory before drafting. Build a private term map. If a term or dependency controls the work and you cannot resolve it, ask the user. When rewriting an existing ticket, mine the old text for facts but draft fresh.
 5. **Draft PROBLEM first**, in one breath, without looking at code. If you cannot state the harm in three sentences, you do not understand the problem yet. Go back and read.
 6. **Write BACKGROUND** (if needed): what prior work led here, what was done, what was left behind, and what project context an engineer new to this area needs to start.
-7. **Write PROPOSED APPROACH**: the compass heading, not the map. Prescriptive voice.
-8. **Write ACCEPTANCE CRITERIA**: observable, testable bullets. Name the test shape where relevant.
-9. **Write RELEASE PLAN** (if needed): flags, ordering, rollback.
+7. **Write PROPOSED APPROACH**: the compass heading, not the map. Prescriptive voice. One short paragraph per mechanism, each with the constraint that justifies it; compress failure sagas to their consequence; move "why not X" reasoning to NOTES.
+8. **Write ACCEPTANCE CRITERIA**: observable, testable bullets. Coarse: three to seven, merging parallel checks and dropping restatements of the approach. Name the test shape only where the test design is non-obvious.
+9. **Write RELEASE PLAN** (if needed): flags, ordering, rollback. Omit when the rollout is a normal deploy.
 10. **Write VALIDATION** (if needed): monitoring, signals, smoke tests.
-11. **Write DEPENDENCIES** (if needed): what blocks this, what this blocks, and why.
+11. **Write DEPENDENCIES** (if needed): only the why that tracker blocker links cannot express. Omit when the links carry it; set the links instead.
 12. **Write SYNOPSIS last** - it is a compression of PROBLEM + the core approach.
 13. **Bold and italicize the save points** in the allowed locations. Bold phrases that name the work (components, mechanisms, behaviors). Italicize phrases that orient to significance (conclusions, payoffs), at most one per paragraph. Apply the scan check.
 14. **Add NOTES** for non-goals, declined alternatives, and scope limits. Use `## NOTES` header. Omit if empty.
@@ -404,7 +426,7 @@ That reading alone conveys the shape, scope, and gates of all three tickets.
 16. **Verify links**: check repo file links, external docs, tickets, PRs, and design artifacts where tooling allows. Do not claim an unverified link was verified.
 17. **Verify prose style and core principle**: check each rule in Prose style. Cut design-narration, authoring-sequence, and buzzwordy abstractions. Verify plain ASCII. Verify prescriptive voice (not descriptive). Verify first-use definitions for subsystem jargon in BACKGROUND or PROBLEM. Verify plain English nouns (no code-domain nouns in prose). Verify conclusion-first in PROBLEM. Verify NOTES bullets are either short pointers or self-contained.
 18. **Clarity pass**: read the draft as a cold lead skimming a backlog, then as an implementer picking up the work cold. Rewrite before returning it; do not tell the user you performed this pass. Check: does every project-specific term get plain-English meaning before or with the label? Are ambiguous terms qualified or replaced with specific behavior? Does every process word name object/action/effect? Does every contrast name current and proposed behavior? Does every causal sentence show the middle step? Did you preserve connective tissue instead of compressing meaning into noun stacks? If the draft got longer, cut a lower-value claim instead of compressing a high-value one.
-19. **Verify length**: if the body exceeds what the work's conceptual size warrants, cut until each line earns its place. If PROPOSED APPROACH dominates, consider splitting into a design doc plus ticket.
+19. **Verify length**: estimate the ticket's complexity (see the point-based budgets in Length and style). If the body exceeds the budget, take the section-level levers first (omit conditional sections that duplicate the tracker or a normal deploy, coarsen acceptance criteria, compress approach sagas), then step up the abstraction ladder (replace mechanism sequences with the principle that subsumes them). If still over, cut the lowest-value claim entirely. Do not compress terminology or cut connective tissue to hit a word count. If PROPOSED APPROACH dominates, consider splitting into a design doc plus ticket.
 
 ## Anti-patterns
 
@@ -427,3 +449,7 @@ That reading alone conveys the shape, scope, and gates of all three tickets.
 - **Conclusion buried at the end.** PROBLEM that builds to its point in the last sentence forces the reader to absorb the explanation before knowing what is being explained. Lead with the problem, then explain why.
 - **Hazard rating without motivation.** "No incident has hit this shape" answers "how bad?" but not "why prioritize this?" Answer "why now?" so the lead can decide whether to schedule it.
 - **NOTES bullets that are both wordy and terse.** A bullet that compresses a paragraph of rationale into one dense sentence reads as a private note. Either flag the thing and point to the full explanation, or write a self-contained sentence or two. Not the middle thing.
+- **RELEASE PLAN that argues the release is boring.** If every bullet says the rollout is routine, omit the section. Its absence is the nothing-special signal.
+- **DEPENDENCIES that restate tracker links.** "Blocked by PLAT-126" with nothing to add is the tracker field. Set the link; keep the section only for the why a link cannot express.
+- **Test inventory as acceptance criteria.** A dozen bullets covering every code path is a test plan, not a definition of done. Keep three to seven observable gates; merge parallel checks.
+- **Failure sagas in PROPOSED APPROACH.** Paragraphs of driver internals, pool lifecycle, or library quirks. Compress to the consequence; the implementer discovers the saga at the keyboard.