@jeffober/thatch 0.1.19 → 0.1.21

package/src/prompts.ts

@@ -46,15 +46,17 @@ workflows. The host auto-discovers them, but reach for them proactively:
 - \`thatch-session-reflection\` — record what you learned at end of session.
 - \`thatch-fact-extractor\` — extract durable facts from recent tool interactions (auto-triggered by the extraction pipeline).
 - \`thatch-dedup-classifier\` — resolve duplicate memory pairs from \`thatch_find_duplicates\`.
-- \`pr-description\` — draft a PR description using instructional-design scaffolding with bold and italic emphasis on the phrases that carry the meaning, so a reviewer skimming only the emphasized fragments still gets the story.
-- \`ticket-description\` — draft a ticket, issue, or work item (Linear or Jira) using instructional-design scaffolding with bold and italic emphasis for scanning.
+- \`pr-description\` — draft a PR description with SYNOPSIS / PURPOSE / DESCRIPTION / WALK-THROUGH / NOTES, using bold and italic emphasis on the phrases that carry the meaning.
+- \`ticket-description\` — draft a ticket, issue, or work item (Linear or Jira) with clear sections and bold/italic emphasis for scanning.
 - \`split-overlarge-pr\` — split already-completed work from an overlarge PR into human-reviewable, release-safe PRs targeting main.
 
 ## When to Write
 
 **One signal is enough.** Do not wait for confirmation.
 Save immediately on: feedback, preferences, corrections, emotional signals,
-new project knowledge, conventions, architectural decisions, investigation results.
+new project knowledge, conventions, architectural decisions, investigation
+results that produced durable knowledge (not point-in-time facts about the
+current state of the code).
 
 ## Before Responding
 
@@ -64,6 +66,16 @@ whether you've discovered knowledge worth persisting. Use thatch_memory_recall
 to check for duplicates, then thatch_memory_remember for new findings. Then
 deliver your response.
 
+## Background Task Completions
+
+When a background task completes and its result is injected into the session,
+the completion is informational — it is not user input and not approval to
+proceed with anything you were discussing. Do not narrate what the task did or
+summarize its output. If you were mid-conversation with the user, continue
+that thread. If the user's last message has been fully addressed, stop and
+wait. Do not treat the completion as a trigger to advance work the user has
+not greenlit.
+
 ## User Decision Model
 
 A statistical model of the user's decision-making preferences is maintained by
@@ -85,6 +97,14 @@ about their preferences:
 2. Use thatch_prediction_update to create, reinforce, or weaken a prediction
 3. Use thatch_prediction_delete to remove a prediction created in error
 
+Code review discussions are high-signal prediction material. When working
+through potential review comments with the user, watch for preferences about
+review threshold, severity, tone, evidence, scope, false positives, or what is
+worth posting. This applies whether the user invoked a review skill, is
+reviewing your changes, or asked you to review their changes or another LLM's
+changes. Before creating a new prediction, query for an existing one and
+reinforce or adjust it when possible.
+
 ## What to Store
 
 - **Global store**: user observations, agent personality, system environment
@@ -92,8 +112,9 @@ about their preferences:
   component relationships, conventions, operational playbooks
 - **Branch-scoped**: branch purpose, feature design decisions, PR status,
   temporary workarounds
-- **Insights**: ALWAYS save non-obvious gotchas, patterns, and architectural
-  lessons discovered during implementation. Never prompt the user; just do it.
+- **Insights**: Save non-obvious gotchas, patterns, and architectural
+  lessons discovered during implementation, but only if they remain true
+  across sessions. Never prompt the user; just do it.
 
 ## How to Write
 
@@ -108,6 +129,16 @@ about their preferences:
 Session-specific context, incomplete/unverified info, anything already in
 CLAUDE.md or OPENCODE.md, speculative conclusions.
 
+Apply the durability test: will this still be true and useful in a future
+session that knows nothing about this branch, commit, or session? If not,
+do not save it. Do not store:
+- Point-in-time values (migration indices, line numbers, file counts) that
+  will be stale by next session
+- Commit hashes and branch-specific history narratives. Git is the source
+  of truth for this; do not duplicate it in memory
+- Anything re-derivable from the codebase faster than recalling it (current
+  file locations, type signatures, function names)
+
 ## Archived Memories
 
 Memories can be marked \`archived\` — a flag for stable, long-term historical
@@ -212,15 +243,17 @@ workflows. The host auto-discovers them, but reach for them proactively:
 - \`thatch-session-reflection\` — record what you learned at end of session.
 - \`thatch-fact-extractor\` — extract durable facts from recent tool interactions (auto-triggered by the extraction pipeline).
 - \`thatch-dedup-classifier\` — resolve duplicate memory pairs from \`find_duplicates\`.
-- \`pr-description\` — draft a PR description using instructional-design scaffolding with bold and italic emphasis on the phrases that carry the meaning, so a reviewer skimming only the emphasized fragments still gets the story.
-- \`ticket-description\` — draft a ticket, issue, or work item (Linear or Jira) using instructional-design scaffolding with bold and italic emphasis for scanning.
+- \`pr-description\` — draft a PR description with SYNOPSIS / PURPOSE / DESCRIPTION / WALK-THROUGH / NOTES, using bold and italic emphasis on the phrases that carry the meaning.
+- \`ticket-description\` — draft a ticket, issue, or work item (Linear or Jira) with clear sections and bold/italic emphasis for scanning.
 - \`split-overlarge-pr\` — split already-completed work from an overlarge PR into human-reviewable, release-safe PRs targeting main.
 
 ## When to Write
 
 **One signal is enough.** Do not wait for confirmation.
 Save immediately on: feedback, preferences, corrections, emotional signals,
-new project knowledge, conventions, architectural decisions, investigation results.
+new project knowledge, conventions, architectural decisions, investigation
+results that produced durable knowledge (not point-in-time facts about the
+current state of the code).
 
 ## Before Responding
 
@@ -251,6 +284,14 @@ about their preferences:
 2. Use prediction_update to create, reinforce, or weaken a prediction
 3. Use prediction_delete to remove a prediction created in error
 
+Code review discussions are high-signal prediction material. When working
+through potential review comments with the user, watch for preferences about
+review threshold, severity, tone, evidence, scope, false positives, or what is
+worth posting. This applies whether the user invoked a review skill, is
+reviewing your changes, or asked you to review their changes or another LLM's
+changes. Before creating a new prediction, query for an existing one and
+reinforce or adjust it when possible.
+
 ## What to Store
 
 - **Global store**: user observations, agent personality, system environment
@@ -258,8 +299,9 @@ about their preferences:
   component relationships, conventions, operational playbooks
 - **Branch-scoped**: branch purpose, feature design decisions, PR status,
   temporary workarounds
-- **Insights**: ALWAYS save non-obvious gotchas, patterns, and architectural
-  lessons discovered during implementation. Never prompt the user; just do it.
+- **Insights**: Save non-obvious gotchas, patterns, and architectural
+  lessons discovered during implementation, but only if they remain true
+  across sessions. Never prompt the user; just do it.
 
 ## How to Write
 
@@ -274,6 +316,16 @@ about their preferences:
 Session-specific context, incomplete/unverified info, anything already in
 CLAUDE.md, speculative conclusions.
 
+Apply the durability test: will this still be true and useful in a future
+session that knows nothing about this branch, commit, or session? If not,
+do not save it. Do not store:
+- Point-in-time values (migration indices, line numbers, file counts) that
+  will be stale by next session
+- Commit hashes and branch-specific history narratives. Git is the source
+  of truth for this; do not duplicate it in memory
+- Anything re-derivable from the codebase faster than recalling it (current
+  file locations, type signatures, function names)
+
 ## Archived Memories
 
 Memories can be marked \`archived\` — a flag for stable, long-term historical
@@ -440,15 +492,17 @@ workflows. The host auto-discovers them, but reach for them proactively:
 - \`thatch-session-reflection\` — record what you learned at end of session.
 - \`thatch-fact-extractor\` — extract durable facts from recent tool interactions (auto-triggered by the extraction pipeline).
 - \`thatch-dedup-classifier\` — resolve duplicate memory pairs from \`find_duplicates\`.
-- \`pr-description\` — draft a PR description using instructional-design scaffolding with bold and italic emphasis on the phrases that carry the meaning, so a reviewer skimming only the emphasized fragments still gets the story.
-- \`ticket-description\` — draft a ticket, issue, or work item (Linear or Jira) using instructional-design scaffolding with bold and italic emphasis for scanning.
+- \`pr-description\` — draft a PR description with SYNOPSIS / PURPOSE / DESCRIPTION / WALK-THROUGH / NOTES, using bold and italic emphasis on the phrases that carry the meaning.
+- \`ticket-description\` — draft a ticket, issue, or work item (Linear or Jira) with clear sections and bold/italic emphasis for scanning.
 - \`split-overlarge-pr\` — split already-completed work from an overlarge PR into human-reviewable, release-safe PRs targeting main.
 
 ## When to Write
 
 **One signal is enough.** Do not wait for confirmation.
 Save immediately on: feedback, preferences, corrections, emotional signals,
-new project knowledge, conventions, architectural decisions, investigation results.
+new project knowledge, conventions, architectural decisions, investigation
+results that produced durable knowledge (not point-in-time facts about the
+current state of the code).
 
 ## Before Responding
 
@@ -479,6 +533,14 @@ about their preferences:
 2. Use prediction_update to create, reinforce, or weaken a prediction
 3. Use prediction_delete to remove a prediction created in error
 
+Code review discussions are high-signal prediction material. When working
+through potential review comments with the user, watch for preferences about
+review threshold, severity, tone, evidence, scope, false positives, or what is
+worth posting. This applies whether the user invoked a review skill, is
+reviewing your changes, or asked you to review their changes or another LLM's
+changes. Before creating a new prediction, query for an existing one and
+reinforce or adjust it when possible.
+
 ## What to Store
 
 - **Global store**: user observations, agent personality, system environment
@@ -486,8 +548,9 @@ about their preferences:
   component relationships, conventions, operational playbooks
 - **Branch-scoped**: branch purpose, feature design decisions, PR status,
   temporary workarounds
-- **Insights**: ALWAYS save non-obvious gotchas, patterns, and architectural
-  lessons discovered during implementation. Never prompt the user; just do it.
+- **Insights**: Save non-obvious gotchas, patterns, and architectural
+  lessons discovered during implementation, but only if they remain true
+  across sessions. Never prompt the user; just do it.
 
 ## How to Write
 
@@ -502,6 +565,16 @@ about their preferences:
 Session-specific context, incomplete/unverified info, anything already in
 AGENTS.md, speculative conclusions.
 
+Apply the durability test: will this still be true and useful in a future
+session that knows nothing about this branch, commit, or session? If not,
+do not save it. Do not store:
+- Point-in-time values (migration indices, line numbers, file counts) that
+  will be stale by next session
+- Commit hashes and branch-specific history narratives. Git is the source
+  of truth for this; do not duplicate it in memory
+- Anything re-derivable from the codebase faster than recalling it (current
+  file locations, type signatures, function names)
+
 ## Archived Memories
 
 Memories can be marked \`archived\` — a flag for stable, long-term historical