@jeffober/thatch 0.2.1 → 0.2.3

package/README.md

@@ -194,8 +194,10 @@ Thatch gives your agent:
   auto-joining with `chat.autoRegister: false`).
 - **Slash commands** -- `/thatch/defrag` (consolidate duplicate memories),
   `/thatch/extract` (drain the extraction queue now), `/thatch/hygiene`
-  (tend stale and orphaned memories), and `/thatch/reflect` (persist what
-  the session learned) run on demand the same behaviors the nudges run on
+  (tend stale and orphaned memories), `/thatch/reflect` (persist what
+  the session learned), and `/thatch/refine` (refine a plan under the
+  project type's requirements, classifying the project first) run on
+  demand. The first four mirror the same behaviors the nudges run on
   their own schedule. Plus the opencode-only wrap-ups: `/thatch/compact` and
   `/thatch/exit` run a pre-flight checklist before a compaction or an exit:
   the agent flushes pending fact extraction, finishes promised memory

package/artifacts/skills/thatch-plan-refinement.md

@@ -1,6 +1,6 @@
 ---
 name: thatch-plan-refinement
-description: Refine a plan for a code change by dispatching a fresh-context reviewer subagent to hunt for gaps, unverified premises, and unexpected side effects, then revising and re-reviewing until consensus. Use when a plan is about to be implemented, when the user asks to refine, stress-test, or double-check a plan, or after a plan revision that incorporated prior findings. Quick mode is one fresh reviewer per round; deep mode adds a specialist lens fan-out (reuse, alternatives, hidden problems, safe-to-modify, archaeology).
+description: Refine a plan for a code change by dispatching a fresh-context reviewer subagent to hunt for gaps, unverified premises, and unexpected side effects, then revising and re-reviewing until consensus. Use when a plan is about to be implemented, when the user asks to refine, stress-test, or double-check a plan, or after a plan revision that incorporated prior findings. This is the generic core loop; when the project type should shape the refinement bar, load thatch-refine instead and it will apply a type delta on top of this loop. Quick mode is one fresh reviewer per round; deep mode adds a specialist lens fan-out (reuse, alternatives, hidden problems, safe-to-modify, archaeology).
 ---
 
 You are refining a plan before code exists. A plan written by the same context that researched the problem inherits that context's blind spots. A reviewer with no stake in the plan and no memory of writing it finds what the author cannot. Refinement is the loop: draft, review, revise, repeat until consensus. Each pass tightens the plan; a round with no findings means the plan is done, not that the loop failed.
@@ -75,7 +75,8 @@ One reviewer per round in quick mode; one lens fan-out total in deep mode, then
 
 ## Relationship to other skills
 
-- **`thatch-code-archaeology`** — the research skill for understanding the code; its output is often the plan's input. The archaeology lens is a targeted, plan-scoped re-run of its git-history step, not a replacement for it.
+- **`thatch-refine`** - the type-aware entry point. Different project types need different refinement bars: a team codebase owes coordination and breadcrumbs, a personal project allows cleverness, a shared library owes API hygiene. When the user runs `/thatch/refine` or the project's type should shape the bar, load `thatch-refine` first; it classifies and hands back a thatch-refine-* delta to apply on top of this loop. This skill stays the generic core.
+- **`thatch-code-archaeology`** - the research skill for understanding the code; its output is often the plan's input. The archaeology lens is a targeted, plan-scoped re-run of its git-history step, not a replacement for it.
 - **`thatch-coding-workflow`** — the procedure skill for executing the refined plan. Refinement ends where coding-workflow begins.
 - **`thatch-ticket-description` / `thatch-pr-description`** — if the refined plan feeds a ticket or PR description (or the session iterated on one using this skill), RE-LOAD the appropriate writing skill and draft within its contract. A plan is a working artifact for the session that wrote it; a ticket or PR description is a reader-facing document with its own sections, verbosity budget, and prose rules. Refinement output — findings, accepted risks, review rounds — is SOURCE MATERIAL for those skills, never a substitute for them. This holds the right level of detail for the medium and keeps the writing clear.
 - **`thatch-clear-writing`** — for any other human-facing text produced along the way (reports, comments, docs).

package/artifacts/skills/thatch-refine-infra.md

@@ -0,0 +1,66 @@
+---
+name: thatch-refine-infra
+description: Type-specific requirements for refining a plan that touches infrastructure (CI pipelines, Terraform, Kubernetes manifests, build and deploy configuration). Loaded by thatch-refine after classification; assumes the core loop in thatch-plan-refinement. Use when a wrong premise can break deploys or pipelines for everyone downstream.
+---
+
+You are refining a plan for an **infra** change: CI pipelines, Terraform,
+Kubernetes manifests, build and deploy configuration. The governing value
+is blast radius: a wrong premise here does not break one feature, it
+breaks every pipeline, environment, or developer downstream of it, often
+silently and often for everyone at once. Load `thatch-plan-refinement`
+for the core loop and apply the deltas below; where they disagree, these
+win.
+
+## What this type owes
+
+- **Near-absolute pattern-following.** Configuration is the worst place
+  for novelty. Copy the established pattern from a sibling pipeline,
+  module, or manifest even when a better one exists; propose the better
+  one as its own change, after this one lands.
+- **Rollback as a first-class deliverable.** Every change names how it
+  backs out, concretely (which command, which revert, which state to
+  re-apply), not "revert the commit if problems arise."
+- **Staged verification.** The plan verifies against a non-production
+  target first (staging environment, a canary job, a dry-run or plan
+  output) and names what a successful verification looks like before
+  production applies it.
+
+## How this changes the loop
+
+- **Deep mode is the default.** Infra changes almost always touch shared
+  persistent state that other consumers read, which is the core skill's
+  first deep-mode trigger.
+- **Premises verify against live state, not memory.** The most dangerous
+  infra premise is "the current setup is X" recalled from memory. Check
+  the actual manifests, the actual pipeline config, the actual running
+  versions, and cite where you checked. Terraform drift and manual
+  console changes make memory especially unreliable here.
+- **Consensus is unchanged**, but the reviewer prompt should emphasize
+  checking the rollback and verification sections explicitly.
+
+## Lens weights
+
+- **Hidden problems (pre-mortem) dominates.** The question is "who reads
+  this state that the plan does not know about?" - dependent pipelines,
+  environments sharing the module, developers relying on cache behavior,
+  jobs relying on timing. Enumerate the dependents by reading what
+  actually references the resource, not by recollection.
+- **Safe-to-modify is second.** An infra change landing in untested
+  configuration without a verification step is a finding.
+- **Alternatives and pattern/reuse mostly skip.** The pattern question
+  was answered above: follow it.
+
+## Extra plan sections
+
+- **Rollback plan.** Concrete and executable, as above.
+- **Verification step.** What runs in staging or dry-run first, and what
+  result counts as safe to proceed.
+- **Sequencing.** Infra changes often must land in an order (create
+  before reference, drain before delete). The plan states the order and
+  what breaks if it is violated.
+
+## Docs bar
+
+A one-paragraph change note for the team (what changed, why, how to
+roll back) is the deliverable. Config comments explain constraints the
+next person must not violate.

package/artifacts/skills/thatch-refine-oss-contribution.md

@@ -0,0 +1,68 @@
+---
+name: thatch-refine-oss-contribution
+description: Type-specific requirements for refining a plan for a contribution to an open source repository the user does not maintain. Loaded by thatch-refine after classification; assumes the core loop in thatch-plan-refinement. The maintainer's design authority and house style govern, and the diff stays minimal.
+---
+
+You are refining a plan for an **oss-contribution**: a change to a
+repository the user does not maintain. The governing value is the
+maintainer's design authority. It is their codebase; the contribution
+that gets merged is the one that fits their intent, not the one that
+would be best by your lights. Load `thatch-plan-refinement` for the core
+loop and apply the deltas below; where they disagree, these win.
+
+## What this type owes
+
+- **Conform to house style, even when it is worse.** A foreign codebase's
+  conventions are not up for improvement in this change. Do not import
+  patterns from other projects; do not refactor what the maintainer
+  wrote.
+- **Minimal diff.** No drive-by refactors, no reformatting of untouched
+  lines, no new dependencies, no new abstractions beyond what the change
+  strictly needs.
+- **The discussion comes first.** Significant design work waits until the
+  approach has a maintainer's nod: check CONTRIBUTING.md, search open
+  and closed issues and PRs for the same idea, and file or comment on
+  the proposal before investing in the implementation. A plan that
+  assumes acceptance is building on an unverified premise.
+
+## How this changes the loop
+
+- **Add a premise class: upstream status.** Every plan premise about the
+  maintainer's intent (is this wanted, is the approach acceptable, is
+  the issue still open) needs evidence: an issue thread, a maintainer
+  comment, a CONTRIBUTING instruction. No evidence means "unknown -
+  ask upstream," and the plan gates on that question, not on a guess.
+- **Consensus adds one test.** Alongside the core skill's consensus
+  criteria, the reviewer answers: "would a maintainer accept this
+  scope?" Scope findings are blockers. A contribution that solves the
+  issue plus three adjacent problems will sit unmerged.
+- **Round cap unchanged.** But a plan blocked on upstream discussion
+  pauses for the user to have that conversation; it does not loop.
+
+## Lens weights
+
+- **Pattern and reuse inverts.** In team code, existing patterns are a
+  strong default; here they are the requirement. A "better" pattern than
+  the house style is a finding against the plan, not for it.
+- **Hidden problems shrinks.** Consumers of internal state are the
+  maintainer's concern. Focus on the change's own footprint and its
+  interaction with in-flight upstream work (search open PRs for overlap).
+- **Alternatives mostly skips.** The maintainer chose the architecture.
+  The plan's job is fitting into it, and where the plan needs a
+  maintainer decision, that is an upstream question, not an alternatives
+  survey.
+
+## Extra plan sections
+
+- **Upstream discussion.** The issue or thread this change responds to,
+  and the maintainer signals (or absence of them) the plan relies on.
+- **House-style conformance.** The specific conventions the change will
+  follow, read from the project's own CONTRIBUTING and recent merged
+  PRs, not assumed.
+
+## Docs bar
+
+Match the project's own documentation conventions for any user-facing
+text (changelog entries, docs pages) and the house code-comment style.
+The writing skills still govern clarity, but the structure and tone
+follow the project's.

package/artifacts/skills/thatch-refine-personal.md

@@ -0,0 +1,61 @@
+---
+name: thatch-refine-personal
+description: Type-specific requirements for refining a plan in a solo personal project with no downstream consumers. Loaded by thatch-refine after classification; assumes the core loop in thatch-plan-refinement. Relaxes coordination requirements and allows cleverness and experimentation, while keeping premise verification honest.
+---
+
+You are refining a plan for a **personal** project: solo code with no
+downstream consumers. The coordination constraints that govern team code
+are relaxed. This is the place to show off cleverness and experiment with
+interesting techniques that would be inconsiderate in a shared codebase.
+Load `thatch-plan-refinement` for the core loop and apply the deltas
+below; where they disagree, these win.
+
+## What this type owes
+
+- **Almost nothing to anyone else.** No consistency obligation to
+  teammates, no reviewer to orient, no downstream API to protect.
+- **Still honest about facts.** Relaxed style does not mean relaxed
+  reality: every factual premise still carries a verified `file:line`
+  citation, and "unverified" is still marked. A plan built on a wrong
+  premise wastes your time in any project.
+
+## How this changes the loop
+
+- **The skip threshold drops.** Most personal-project plans can be tried
+  faster than they can be refined. Skip refinement whenever the change is
+  cheap to build and cheaper to rewrite; run the loop only when the plan
+  touches something expensive to get wrong (persistent state, a
+  hard-to-reverse migration, hours of build effort).
+- **Fewer rounds.** One quiet review round is enough consensus. The cap
+  drops from three rounds to two; a personal plan that has not converged
+  by then should just be built or abandoned.
+- **Degraded review is fine.** If the host cannot dispatch sub-agents, a
+  same-context self-review pass is usually enough. Saying so out loud, as
+  the core skill requires, is still worthwhile but the stakes are lower.
+
+## Lens weights
+
+- **Premise verification is the only load-bearing lens.** The fresh
+  reviewer's core job is checking the plan's factual model of the code.
+- **Pattern and reuse mostly skips.** There is no team to stay consistent
+  with. Flag reuse only when reinventing an existing wheel will genuinely
+  bite future-you.
+- **Alternatives turns exploratory.** The question shifts from "what is
+  safest?" to "what would I learn?" - one alternative worth trying for
+  the technique is a valid result even when the plan's choice is fine.
+- **Hidden problems shrinks to future-self.** The only consumer to
+  enumerate is you, six months from now, with no memory of this code.
+
+## Extra plan sections
+
+None required. Blast radius, migration plans, and reviewer orientation
+sections are skipped unless the change is in the expensive-to-get-wrong
+category that triggered refinement at all.
+
+## Docs bar
+
+- Future-self breadcrumbs only: comment the surprising spots, not the
+  obvious ones.
+- When a plan deliberately uses an experimental technique, record that in
+  one line (in the plan or a comment) so a future session knows the
+  oddity was chosen, not accidental.

package/artifacts/skills/thatch-refine-shared-lib.md

@@ -0,0 +1,69 @@
+---
+name: thatch-refine-shared-lib
+description: Type-specific requirements for refining a plan that touches a library's API surface, in any repo, including personal ones. Loaded by thatch-refine after classification; assumes the core loop in thatch-plan-refinement. Use whenever exported API, published packages, or downstream consumers are involved; API hygiene governs even solo projects.
+---
+
+You are refining a plan for a **shared-lib** change: work that touches an
+API other code consumes and keeps working against. This applies to any
+library with external callers, including a personal one. The governing
+value is API hygiene: you are writing for consumers you cannot see and
+cannot call back. Load `thatch-plan-refinement` for the core loop and
+apply the deltas below; where they disagree, these win.
+
+## What this type owes
+
+- **Flexible on input, strict on output.** Accept broad input types and
+  normalize them; return precise, well-defined types and never leak
+  internal representations. Callers write code against your output
+  shapes; widen what you accept, pin down what you emit.
+- **Keep special cases out of the API.** No caller-specific knobs, no
+  one-off escape hatches, no parameters that exist for exactly one
+  consumer. A special case is a design smell: handle it inside the
+  implementation or reject it at the boundary.
+- **Do not foreclose caller options.** Prefer returning data over making
+  decisions callers might want to make differently. Every shortcut the
+  library takes on the caller's behalf is a wall they hit later.
+- **Keep the surface small.** Every export is a permanent maintenance
+  promise. The best API change is often the one that exports nothing new.
+
+## How this changes the loop
+
+- **Deep mode is the default** for anything that adds, changes, or
+  removes an export. The abstraction gets locked in at ship time; after
+  release, changing it costs every consumer. This is the last cheap
+  moment to get the shape right.
+- **Alternatives works harder here.** "No better alternative found" must
+  be argued harder than the core skill's paragraph: enumerate the
+  plausible alternative shapes and say why the plan's shape wins for
+  callers, not just for the implementation.
+- **Backward compatibility findings are blockers by default.** A breaking
+  change without a deprecation path is a blocker, not a should-fix.
+
+## Lens weights
+
+- **Hidden problems reframes entirely.** Every consumer is a stranger;
+  you cannot grep your callers. Enumerate the contract the plan changes
+  and reason about the population of consumers you cannot see, including
+  the ones using the API in ways you never intended.
+- **Pattern and reuse applies to your own API first.** Consistency with
+  the library's existing API conventions is its own requirement: a
+  second method that disagrees with the first in naming or shape is a
+  finding even when both are internally fine.
+
+## Extra plan sections
+
+- **API surface diff.** Exactly what is exported, added, changed, or
+  removed, in a list a reviewer can check one line at a time.
+- **Semver impact and deprecation path.** The version bump this deserves,
+  what is deprecated, and how callers migrate.
+- **External documentation.** The docs and examples this change requires,
+  written for the reader: what the behavior is, when to use it, what it
+  does not do. "I'll document it later" is a finding.
+- **Caller migration notes.** For breaking or behavior-changing exports,
+  the note that goes in the changelog.
+
+## Docs bar
+
+Reader-facing documentation is a plan deliverable, not a follow-up. Draft
+it under the writing skills' contracts: define terms on first use,
+behavior stated precisely enough that a caller needs no source dive.

package/artifacts/skills/thatch-refine-spike.md

@@ -0,0 +1,53 @@
+---
+name: thatch-refine-spike
+description: Type-specific requirements for refining a plan for a throwaway prototype or time-boxed spike. Loaded by thatch-refine after classification; assumes the core loop in thatch-plan-refinement. Skips almost all of the loop, verifying only the premises the experiment's conclusion depends on.
+---
+
+You are refining a plan for a **spike**: throwaway code whose purpose is
+answering a question, not producing a maintained artifact. Almost all of
+the refinement loop is waste here. Load `thatch-plan-refinement` for the
+core loop, then apply the deltas below; where they disagree, these win.
+
+## What this type owes
+
+- **A stated question.** The plan opens with the question the spike
+  exists to answer, stated concretely enough that "done" is checkable
+  ("can Postgres full-text search handle our query volume?" not "explore
+  search options").
+- **A promotion test.** The plan states what would make this code worth
+  promoting into the real codebase versus rewriting it properly. Most
+  spikes end in a rewrite, and that is a success, not a failure.
+- **A time box.** The plan names its budget: hours or days, not open-
+  ended effort.
+
+## How this changes the loop
+
+- **Skip the loop by default.** No reviewer dispatch, no rounds, no
+  consensus machinery. One focused self-review pass is the whole
+  refinement: check the plan's few load-bearing premises, then build.
+- **Verify only conclusion-bearing premises.** The spike's conclusion is
+  only as good as the premises it depends on. If the experiment claims
+  "this approach is too slow," the benchmark setup and the
+  representativeness of the test data are the premises that matter, and
+  they get the verified-citation treatment. Everything else is
+  throwaway.
+- **Degraded review needs no apology.** The core skill's honest-degradation
+  notice is unnecessary; there is no real review to degrade.
+
+## Lens weights
+
+All specialist lenses skip except one consideration: **is the spike
+actually throwaway?** If the plan quietly assumes the prototype code will
+survive into production, stop and surface that. A spike that is really a
+production change wearing a costume should be refined under the type it
+actually is.
+
+## Extra plan sections
+
+- The question, the promotion test, and the time box above. Nothing else.
+
+## Docs bar
+
+No breadcrumb obligation. One comment or note recording the question and
+the answer is enough. The spike's real output is the answer, and it
+should be written down where the user will find it.

package/artifacts/skills/thatch-refine-team-app.md

@@ -0,0 +1,69 @@
+---
+name: thatch-refine-team-app
+description: Type-specific requirements for refining a plan in a multi-developer team codebase (production app or service shared by a team). Loaded by thatch-refine after classification; assumes the core loop in thatch-plan-refinement. Use when coordination cost, consistency, and reviewer comprehension are the governing constraints.
+---
+
+You are refining a plan for a **team-app** project: production code in a
+repository where multiple developers ship, review, and maintain each
+other's work. The governing value is org velocity through coordination and
+consistency. Code is read far more often than it is written, and most of
+its readers did not write it. Load `thatch-plan-refinement` for the core
+loop and apply the deltas below; where they disagree, these win.
+
+## What this type owes
+
+- **Consistency outranks local optimality.** Following the codebase's
+  existing pattern beats a "better" one that splits the codebase in two.
+  A novel approach must justify the divergence it imposes on every future
+  reader, not just prove it is cleverer.
+- **Implement for the junior reviewer.** The bar is that a developer with
+  no history in this area can review the change and debug it at 2am.
+  Cleverness is allowed only with a justification comment at the point of
+  cleverness, and only when the payoff is real.
+- **Intent is a deliverable.** Docstrings and comments are the breadcrumb
+  trail for the next maintainer. The plan says which comments and
+  docstrings it will write, and *why* is documented, not just *what*.
+
+## How this changes the loop
+
+- **Mode triage stays strict.** The skip threshold does not relax for
+  team code: anything another developer must review earns at least quick
+  mode. Established-pattern changes with no design decisions can still
+  skip, as the core skill already provides.
+- **Deep mode triggers broaden.** Beyond the core skill's triggers, deep
+  mode is warranted when the change alters a contract other teams build
+  on, or lands in an area with a history of review churn.
+- **Consensus is unchanged.** Same rounds, same cap, same escalation to
+  the user.
+
+## Lens weights
+
+- **Hidden problems (pre-mortem) carries the most signal.** In team code
+  the plan's biggest risk is an unenumerated consumer or an implicit
+  contract another team relies on.
+- **Safe-to-modify is second.** A plan that lands in an untested,
+  tangled section without a refactor-first dependency is a finding.
+- **Pattern and reuse tightens.** "Reuse the existing pattern" is the
+  default verdict, not one option among several. A plan that introduces a
+  parallel way to do something the codebase already does needs a strong,
+  evidenced reason.
+- **Alternatives stays a filter.** Two alternatives, one paragraph each,
+  as the core skill says; the judgment criterion is team cost, not
+  personal preference.
+
+## Extra plan sections
+
+- **Blast radius and consumers.** Who reads the state, tables, config, and
+  symbols this change touches, including other teams and services.
+- **Migration and rollback.** How the change ships safely and how it
+  backs out.
+- **Intent breadcrumbs.** The docstrings and comments the implementation
+  will write, and what future-reader question each answers.
+- **Reviewer orientation.** One paragraph a reviewer can read first: what
+  changed, why, and where to look.
+
+## Docs bar
+
+Comments and docstrings are part of the definition of done, and any
+reader-facing text produced along the way (PR description, ticket,
+changelog entry) is drafted under the writing skills' contracts.

package/artifacts/skills/thatch-refine.md

@@ -0,0 +1,84 @@
+---
+name: thatch-refine
+description: Classify the current project (audience, lifecycle, surface) and refine a plan under that type's requirements. Entry point for the thatch-refine-* family. Use when the user asks to refine a plan, runs /thatch/refine, or when a plan is about to be implemented and the project type should shape the refinement bar. For a bare "refine this plan" request, load this skill rather than thatch-plan-refinement directly - the router picks the type and applies its delta on top of the core loop.
+---
+
+You are the entry point for project-type-aware plan refinement. The core
+refinement loop (draft, fresh-context reviewer, revise, consensus) is the
+same everywhere; it lives in `thatch-plan-refinement`. What changes by
+project type is the bar: which lenses matter, what the plan must contain,
+how much documentation is owed, and when skipping refinement is honest.
+
+## The types
+
+| Type | Governing value | Skill |
+|------|-----------------|-------|
+| `team-app` | Coordination and consistency promote org velocity | `thatch-refine-team-app` |
+| `personal` | Freedom to experiment; low coordination cost | `thatch-refine-personal` |
+| `shared-lib` | API hygiene; never foreclose caller options | `thatch-refine-shared-lib` |
+| `spike` | Answering a question cheaply, not producing code | `thatch-refine-spike` |
+| `infra` | Blast radius across pipelines and environments | `thatch-refine-infra` |
+| `oss-contribution` | The maintainer's design authority | `thatch-refine-oss-contribution` |
+
+## Classification
+
+Classify on three axes, then pick the type whose requirements this plan
+must satisfy. Classify **the change**, not just the repo: a personal repo
+gaining a published API is a `shared-lib` plan for that change, even if the
+repo is `personal` overall.
+
+**Audience** - who reads and maintains this code.
+
+- Solo: one contributor in git history, no CODEOWNERS, no required reviews.
+- Team: CODEOWNERS, CONTRIBUTING.md, required PR review, multiple regular
+  authors.
+- Public: published package (npm/PyPI/etc. metadata, `publishConfig`), or
+  consumers outside the repo you cannot enumerate.
+
+**Lifecycle** - what this code owes anyone.
+
+- Production: protected main, CI gates, deploy configuration, semver
+  discipline.
+- Experimental: active WIP, churny main, thin or absent tests.
+- Throwaway: a question wearing a repository.
+
+**Surface** - what the change lives in.
+
+- Application: end-user or service code with no downstream importers.
+- Library: exported API that other code imports and keeps working against.
+- Infrastructure: CI, Terraform, k8s manifests, build and deploy config.
+
+Signals to gather (all cheap and read-only): `git log --format="%an" |
+sort -u | head`, presence of CODEOWNERS / CONTRIBUTING.md / required
+review config, package.json `private` and `publishConfig` fields, the
+publishing config of the relevant ecosystem, presence of `.github/workflows`,
+`terraform/` or k8s manifests, and what the package exports. Do not
+over-invest here; the classification should cost a minute, not a research
+pass.
+
+## Procedure
+
+1. If the user named a type explicitly (for example `/thatch/refine
+   shared-lib`), skip classification and use it.
+2. Otherwise gather the signals above and pick the type.
+3. State the classification in one line and why, and let the user override.
+   A wrong classification silently changes the requirements, so the user
+   sees the pick before it takes effect. When the signals conflict or are
+   too thin to pick, ask instead of guessing.
+4. Load `thatch-plan-refinement` (the core loop) and the type's skill.
+5. Run the core loop with the type skill's deltas applied. Where a delta
+   and the core skill disagree, the delta wins; that is its whole job.
+
+If no type fits (the repo serves a niche the table misses), run plain
+`thatch-plan-refinement` and say that the requirements are the generic
+ones.
+
+## Relationship to other skills
+
+- **`thatch-plan-refinement`** - the core loop. Always loaded; the type
+  skills only modify it.
+- **`thatch-coding-workflow`** - the procedure skill for executing the
+  refined plan. Refinement ends where it begins.
+- **`thatch-clear-writing`** and the writing skills - several type skills
+  make reader-facing documentation a plan deliverable. Draft that text
+  under the writing skills' contracts, not this one's.

package/bin/thatch

@@ -1054,15 +1054,19 @@ switch (command) {
       }
 
       // Tier 1: extraction nudge. Peek (don't drain) - the queue persists
-      // until the agent calls memory_remember, which triggers consumeQueue.
-      // If the agent ignores the nudge, the payload grows on the next flush.
-      // The nudge carries the session ID, not the full payload — the
-      // sub-agent fetches it via get_extraction_payload.
+      // until the extractor completes (extraction_done with the parent's
+      // session_id) or the parent writes a memory itself. The parent's
+      // dispatch-time ack resets the escalation counter but does NOT drain:
+      // a drain at ack time deleted the queue before the sub-agent fetched
+      // (the accept-before-fetch loss). If the agent ignores the nudge, the
+      // payload grows on the next flush. The nudge carries the session ID,
+      // not the full payload - the sub-agent fetches it via
+      // get_extraction_payload.
       const interactions = sessionID ? peekQueue(sessionID) : [];
       if (interactions.length > 0) {
         const missed = sessionID ? getMissedCount(sessionID) : 0;
         if (sessionID) incrementMissedCount(sessionID);
-        const output = extractionNudge(interactions.length, missed, "mcp__thatch__memory_remember", sessionID ?? "");
+        const output = extractionNudge(interactions.length, missed, sessionID ?? "");
         emit(output, versionWarning, isJson, chatLine);
         break;
       }

package/docs/dev/README.md

@@ -127,7 +127,7 @@ methods. The v1 hook shapes:
 | `command.execute.before` | Arms the wrap-up greenlight check: `/thatch/compact` and `/thatch/exit` mark their session in `pendingWrapUp`. The next `session.status` idle resolves it by inspecting the final assistant message for the greenlight token and, when present, triggering the TUI action (`session_compact` via `executeCommand`, `app.exit` via `publish`; the exit path unregisters the session from the chat directory first). See [features/session-lifecycle.md](features/session-lifecycle.md). |
 | `experimental.compaction.autocontinue` | Clears the compacting flag so `chat.message` nudges resume. Without this, nudges that instruct tool calls would fire during summary generation where tools are blocked. The `chat.message` hook also clears the flag if it fires for a session still in the compacting set but the incoming message has no compaction-type part — this handles compaction failure, where the session would otherwise be stuck with nudges off forever. |
 | `tool.execute.after` | Buffers every non-`thatch_*`, non-`skill`, non-`task` tool call into the session's extraction buffer. (Skill/task are excluded — buffering them creates a feedback loop where the nudge triggers a skill load, which gets buffered, which triggers another nudge.) Memory writes (`thatch_memory_remember`) and `thatch_extraction_done` drain the buffer and reset the missed-nudge counter. For child sessions (`childToParent.has(sessionID)`), also tracks metrics: `remember` with `overwrite:false` → new++, `overwrite:true` → updated++, `forget` → deleted++. For `thatch_chat_*` tool calls, builds the transcript echo (`chatEchoText`) and posts it as a visible non-synthetic `noReply` part. This is a plugin hook, NOT a bus event — do not move it into the `event` handler; the event bus has no such event and it will silently never fire. |
-| `chat.message` | Two priority tiers: (a) if extraction buffer has interactions and the session is NOT in the `extracting` set (direct extraction in progress), **peeks** the buffer (does NOT drain it) and injects a synthetic text part carrying the extraction nudge with the session ID and fetch tool name (not the full payload) — the sub-agent calls `thatch_get_extraction_payload` to retrieve the interactions as a tool response, keeping the full payload out of the main session's context window. The buffer persists until the agent writes a memory or calls `thatch_extraction_done`, so ignored nudges repeat and escalate (polite → insistent → ALL-CAPS) via the `missedNudges` counter; (b) otherwise, embeds the user's prompt text with the in-process warm model, searches `db.search()` across repo + global, and pushes a recall nudge if matches exceed the threshold (default 0.55). The same embedding also feeds the prediction auto-fire (`db.scorePredictionNudge`, injects `[thatch] User decision model`) and the behavior auto-fire (`db.scoreBehaviorNudge`, injects `[thatch] Situational behaviors`). All three nudges (recall, prediction, behavior) fire independently in separate try/catch blocks with separate synthetic parts. Chat transcript echoes (non-synthetic `noReply` parts whose text is entirely `[chat]`-prefixed bubbles) are skipped before any tier — no model turn reads them, so nudging them wastes an embedding. Skipped entirely while the session is compacting (tool calls are blocked during summary generation), and for task-dispatched sub-agent sessions (`childToParent` without `extractionChildren`) - their tool lists may exclude the thatch tools and their work is driven by the dispatch prompt. |
+| `chat.message` | Recall nudge: embeds the user's prompt text with the in-process warm model, searches `db.search()` across repo + global, and pushes a recall nudge if matches exceed the threshold (default 0.55). The same embedding also feeds the prediction auto-fire (`db.scorePredictionNudge`, injects `[thatch] User decision model`) and the behavior auto-fire (`db.scoreBehaviorNudge`, injects `[thatch] Situational behaviors`). All three nudges fire independently in separate try/catch blocks with separate synthetic parts. There is deliberately NO extraction nudge here - extraction is plugin-driven at session idle (see the extraction feature doc); the old model-driven handshake raced its own state machine and was removed. Chat transcript echoes (non-synthetic `noReply` parts whose text is entirely `[chat]`-prefixed bubbles) are skipped before any tier — no model turn reads them, so nudging them wastes an embedding. Skipped entirely while the session is compacting (tool calls are blocked during summary generation), and for task-dispatched sub-agent sessions (`childToParent` without `extractionChildren`) - their tool lists may exclude the thatch tools and their work is driven by the dispatch prompt. |
 | `event` | Subscribes to all session bus events. `session.created`: records `childToParent` + `parentSnapshots` (shallow copy of the parent's buffer for snapshot-aware drain), then sends the session-start reminder via `client.session.prompt` carrying the hygiene heartbeat (pending dedup pairs, stale count, orphaned branch memories) when any signal is non-zero. `session.status`: records the session's live status for the watcher and chat delivery gates; on idle, if the session is a child, drains its snapshot, fires a toast with `childMetrics`, and deletes the child session; if the session is a parent with pending tool interactions and not already extracting, calls `triggerExtraction` to create a direct-extraction child, then flushes pending watcher events and pending chat mail (the session just became deliverable). `session.error`: requeues the parent's buffer (child died without draining). `session.deleted`: cleans up `childToParent`, `parentSnapshots`, `childMetrics`, and `extracting`, cancels the session's watchers, and unregisters it from the chat directory (the crash path — a dead process fires no event — is covered by heartbeat staleness). `session.compacted`: clears the compacting flag so `chat.message` nudges resume. |
 | `dispose` | Stops the version checker, the watcher poller, and the chat poller, closes the DB. |
 
@@ -171,11 +171,11 @@ Two of these hooks were dead for weeks because failures were invisible.
    check for durable knowledge (via `thatch_memory_recall` for dedup, then
    `thatch_memory_remember`) before composing a final response after
    substantial work. No plugin hook fires between generation and response
-   delivery, so the only viable path is prompt instruction. The existing
-   `chat.message` extraction nudge stays as a fallback for the false-negative
-   case (agent forgot to save, next user turn arrives with buffer still
-   pending). This is an experiment — model reliability on meta-instructions
-   is uncertain.
+   delivery, so the only viable path is prompt instruction. If the agent
+   forgets to save, extraction still sweeps the buffered tool interactions
+   at the session's next idle (plugin-driven; there is no model-facing
+   extraction nudge any more). This is an experiment — model reliability on
+   meta-instructions is uncertain.
 10. **Background completion narration is suppressed, not prevented.** When a
     background sub-agent completes, opencode injects a `<task_result>` block
     into the parent session and triggers a full model generation. Thatch
@@ -243,27 +243,23 @@ extraction cycle
   → tool.execute.after buffers non-thatch, non-skill, non-task tool calls
     per session (max 20); for child sessions, also tracks new/updated/deleted
     metrics
-  → direct extraction (primary path, opencode-only):
+  → direct extraction (the only opencode path):
     parent goes idle (session.status idle) with pending tool interactions
-    → triggerExtraction adds parentID to the `extracting` set (suppresses
-      nudge in chat.message), creates a child session via
-      client.session.create, and prompts it with the extraction payload
+    → stale accepted entries requeue (15-min bound), then triggerExtraction
+      adds parentID to the `extracting` set, creates a child session via
+      client.session.create, and prompts it with extractionDirectPrompt
+      (the parent's session ID is interpolated by the plugin)
+    → child fetches the payload via thatch_get_extraction_payload - the
+      fetch records its claim (the delivery record)
     → child runs the fact-extractor skill, writes memories via
-      thatch_memory_remember → consumeSnapshot drains the parent's buffer
-      (snapshot-aware: removes only entries captured at dispatch time by
-      reference identity, preserving interleaved-turn entries)
-    → child goes idle → event handler drains remaining snapshot entries,
-      fires a toast with childMetrics, deletes the child session
-  → nudge path (fallback): if triggerExtraction throws (create or prompt
-    fails), the `extracting` set clears and the next chat.message sees
-    pending entries with no extracting flag → peeks the buffer and injects
-    a nudge part with session ID and fetch tool name; missed nudges escalate (polite →
-    insistent → ALL-CAPS) via the missedNudges counter
-    → drain: thatch_memory_remember (or thatch_extraction_done) clears the
-      buffer and resets the missed-nudge counter
-    → agent dispatches a sub-agent that calls thatch_get_extraction_payload
-      to fetch the queued interactions, loads thatch-fact-extractor skill,
-      saves facts via thatch_memory_remember
+      thatch_memory_remember - each write (or extraction_done) completes
+      the child's claimed delivery, consuming only what it received
+    → child goes idle → event handler finalizes, fires a toast with
+      childMetrics, deletes the child session
+  → failure recovery (no model-facing nudge exists): a child error or
+    deletion requeues what it held to pending; a completion signal that
+    never comes is bounded by the 15-minute stale reaper; either way the
+    next idle re-triggers extraction from the same pending buffer
   → MCP path (Claude Code/Cursor): unchanged — no SDK client, no child
     sessions; extract-queue.ts + flush-tools drives the nudge via hooks
 

package/docs/dev/features/cli.md

@@ -85,6 +85,7 @@ Read-only window on the cross-session chat directory ([cross-session-chat.md](cr
 | `THATCH_RECALL_THRESHOLD` | Cosine cutoff for recall nudge | `0.55` |
 | `THATCH_PREDICTION_THRESHOLD` | Cutoff for prediction auto-fire | `0.60` |
 | `THATCH_BEHAVIOR_THRESHOLD` | Cutoff for behavior auto-fire | `0.60` |
+| `THATCH_CHILD_RECONCILE_MS` | Reload window before a restored extraction child is judged finished (test knob) | `10000` |
 | `CLAUDE_PROJECT_DIR` | Claude Code project dir | `process.cwd()` |
 | `CURSOR_PROJECT_DIR` | Cursor project dir | falls through |
 | `CLAUDE_CONFIG_DIR` | Claude config dir | `~/.claude` |