refactor: consolidate and clarify tool prompts for standalone use

- Remove cross-references between discard/extract tools so each works independently
- Add decision hierarchy in both-mode: discard as default, extract for preservation
- Consolidate redundant 'WHEN TO X' scenarios with trigger lists
- Change trigger lists to focus on timing ('evaluate when') vs prescriptive action
- Remove confusing 'minimal distillation for cleanup' concept from extract prompts
- Standardize structure across all system prompts and nudges

Author: Tarquinen

lib/prompts/discard-tool-spec.txt

@@ -19,7 +19,7 @@ Use `discard` for removing tool outputs that are no longer needed **without pres
 
 ## When NOT to Use This Tool
 
-- **If you need to preserve information:** Use the `consolidate` tool instead when you want to keep distilled findings from the tool outputs.
+- **If you need to preserve information:** Keep the raw output in context rather than discarding it.
 - **If you'll need the output later:** Don't discard files you plan to edit, or context you'll need for implementation.
 
 ## Best Practices

lib/prompts/extract-tool-spec.txt

@@ -24,7 +24,6 @@ You MUST provide distilled findings in the `distillation` parameter. This is not
 
 ## When NOT to Use This Tool
 
-- **If you don't need to preserve information:** Use the `discard` tool instead for completed tasks or noise removal.
 - **If you need precise syntax:** If you'll need to edit a file, grep for exact strings, or reference precise syntax, keep the raw output. Distillation works for understanding; implementation often requires the original.
 - **If uncertain:** Prefer keeping over re-fetching. The cost of retaining context is lower than the cost of redundant tool calls.
 

lib/prompts/nudge/nudge-both.txt

@@ -2,9 +2,9 @@
 **CRITICAL CONTEXT WARNING:** Your context window is filling with tool outputs. Strict adherence to context hygiene is required.
 
 **Immediate Actions Required:**
-1. **Task Completion:** If a sub-task is complete, discard the tools used.
-2. **Noise Removal:** If you read files or ran commands that yielded no value, discard them NOW.
-3. **Extraction:** If you are holding valuable raw data, you *must* use the `extract` tool to distill the insights and remove the raw entry.
+1. **Task Completion:** If a sub-task is complete, decide: use `discard` if no valuable context to preserve (default), or use `extract` if insights are worth keeping.
+2. **Noise Removal:** If you read files or ran commands that yielded no value, use `discard` to remove them.
+3. **Knowledge Preservation:** If you are holding valuable raw data you'll need to reference later, use `extract` to distill the insights and remove the raw entry.
 
 **Protocol:** You should prioritize this cleanup, but do not interrupt a critical atomic operation if one is in progress. Once the immediate step is done, you must perform context management.
 </instruction>

lib/prompts/nudge/nudge-discard.txt

@@ -2,8 +2,8 @@
 **CRITICAL CONTEXT WARNING:** Your context window is filling with tool outputs. Strict adherence to context hygiene is required.
 
 **Immediate Actions Required:**
-1. **Task Completion:** If a sub-task is complete, discard the tools used.
-2. **Noise Removal:** If you read files or ran commands that yielded no value, discard them NOW.
+1. **Task Completion:** If a sub-task is complete, use the `discard` tool to remove the tools used.
+2. **Noise Removal:** If you read files or ran commands that yielded no value, use the `discard` tool to remove them.
 
 **Protocol:** You should prioritize this cleanup, but do not interrupt a critical atomic operation if one is in progress. Once the immediate step is done, you must discard unneeded tool outputs.
 </instruction>

lib/prompts/nudge/nudge-extract.txt

@@ -2,9 +2,8 @@
 **CRITICAL CONTEXT WARNING:** Your context window is filling with tool outputs. Strict adherence to context hygiene is required.
 
 **Immediate Actions Required:**
-1. **Task Completion:** If a sub-task is complete, extract findings and remove the raw tool outputs.
-2. **Noise Removal:** If you read files or ran commands that yielded no value, extract them with minimal distillation NOW.
-3. **Extraction:** If you are holding valuable raw data, you *must* use the `extract` tool to distill the insights and remove the raw entry.
+1. **Task Completion:** If you have completed work, extract key findings from the tools used. Scale distillation depth to the value of the content.
+2. **Knowledge Preservation:** If you are holding valuable raw data you'll need to reference later, use the `extract` tool with high-fidelity distillation to preserve the insights and remove the raw entry.
 
-**Protocol:** You should prioritize this cleanup, but do not interrupt a critical atomic operation if one is in progress. Once the immediate step is done, you must extract and remove unneeded tool outputs.
+**Protocol:** You should prioritize this cleanup, but do not interrupt a critical atomic operation if one is in progress. Once the immediate step is done, you must extract unneeded tool outputs.
 </instruction>

lib/prompts/system/system-prompt-both.txt

@@ -8,19 +8,24 @@ TWO TOOLS FOR CONTEXT MANAGEMENT
 - `discard`: Remove tool outputs that are no longer needed (completed tasks, noise, outdated info). No preservation of content.
 - `extract`: Extract key findings into distilled knowledge before removing raw outputs. Use when you need to preserve information.
 
+CHOOSING THE RIGHT TOOL
+Ask: "Do I need to preserve any information from this output?"
+- **No** → `discard` (default for cleanup)
+- **Yes** → `extract` (preserves distilled knowledge)
+- **Uncertain** → `extract` (safer, preserves signal)
+
+Common scenarios:
+- Task complete, no valuable context → `discard`
+- Task complete, insights worth remembering → `extract`
+- Noise, irrelevant, or superseded outputs → `discard`
+- Valuable context needed later but raw output too large → `extract`
+
 PRUNE METHODICALLY - BATCH YOUR ACTIONS
 Every tool call adds to your context debt. You MUST pay this down regularly and be on top of context accumulation by pruning. Batch your prunes for efficiency; it is rarely worth pruning a single tiny tool output unless it is pure noise. Evaluate what SHOULD be pruned before jumping the gun.
 
-WHEN TO PRUNE? THE SCENARIOS TO CONSIDER
-1. TASK COMPLETION: When work is done, quietly discard the tools that aren't needed anymore.
-2. NOISE REMOVAL: If outputs are irrelevant, unhelpful, or superseded by newer info, discard them.
-3. CONTEXT EXTRACTION: When you have valuable context you want to preserve but need to reduce size, use `extract` with high-fidelity distillation. Your distillation must be comprehensive, capturing technical details (signatures, logic, constraints) such that the raw output is no longer needed. THINK: high signal, complete technical substitute.
-
-You WILL use `discard` or `extract` when ANY of these are true:
+You WILL evaluate pruning when ANY of these are true:
 - Task or sub-task is complete
 - You are about to start a new phase of work
-- You have gathered enough information to extract from related tools and preserve their value via distillation
-- Context contains tool outputs that are unhelpful, noise, or made obsolete by newer outputs
 - Write or edit operations are complete (pruning removes the large input content)
 
 You MUST NOT prune when:

lib/prompts/system/system-prompt-discard.txt

@@ -10,14 +10,13 @@ CONTEXT MANAGEMENT TOOL
 DISCARD METHODICALLY - BATCH YOUR ACTIONS
 Every tool call adds to your context debt. You MUST pay this down regularly and be on top of context accumulation by discarding. Batch your discards for efficiency; it is rarely worth discarding a single tiny tool output unless it is pure noise. Evaluate what SHOULD be discarded before jumping the gun.
 
-WHEN TO DISCARD? THE SCENARIOS TO CONSIDER
-1. TASK COMPLETION: When work is done, quietly discard the tools that aren't needed anymore.
-2. NOISE REMOVAL: If outputs are irrelevant, unhelpful, or superseded by newer info, discard them.
+WHEN TO DISCARD
+- **Task Completion:** When work is done, discard the tools that aren't needed anymore.
+- **Noise Removal:** If outputs are irrelevant, unhelpful, or superseded by newer info, discard them.
 
-You WILL use `discard` when ANY of these are true:
+You WILL evaluate discarding when ANY of these are true:
 - Task or sub-task is complete
 - You are about to start a new phase of work
-- Context contains tool outputs that are unhelpful, noise, or made obsolete by newer outputs
 - Write or edit operations are complete (discarding removes the large input content)
 
 You MUST NOT discard when:

lib/prompts/system/system-prompt-extract.txt

@@ -5,21 +5,18 @@ ENVIRONMENT
 You are operating in a context-constrained environment and thus must proactively manage your context window using the `extract` tool. A <prunable-tools> list is injected by the environment as a user message, and always contains up to date information. Use this information when deciding what to extract.
 
 CONTEXT MANAGEMENT TOOL
-- `extract`: Extract key findings into distilled knowledge before removing raw outputs. Use this to preserve important information while reducing context size.
+- `extract`: Extract key findings from tools into distilled knowledge before removing the raw content from context. Use this to preserve important information while reducing context size.
 
 EXTRACT METHODICALLY - BATCH YOUR ACTIONS
-Every tool call adds to your context debt. You MUST pay this down regularly and be on top of context accumulation by extracting. Batch your extractions for efficiency; it is rarely worth extracting a single tiny tool output unless it is pure noise. Evaluate what SHOULD be extracted before jumping the gun.
+Every tool call adds to your context debt. You MUST pay this down regularly and be on top of context accumulation by extracting. Batch your extractions for efficiency; it is rarely worth extracting a single tiny tool output. Evaluate what SHOULD be extracted before jumping the gun.
 
-WHEN TO EXTRACT? THE SCENARIOS TO CONSIDER
-1. TASK COMPLETION: When work is done, extract any valuable findings and remove the raw outputs.
-2. NOISE REMOVAL: If outputs are irrelevant, unhelpful, or superseded by newer info, extract them with minimal distillation.
-3. CONTEXT PRESERVATION: When you have valuable context you want to preserve but need to reduce size, use `extract` with high-fidelity distillation. Your distillation must be comprehensive, capturing technical details (signatures, logic, constraints) such that the raw output is no longer needed. THINK: high signal, complete technical substitute.
+WHEN TO EXTRACT
+- **Task Completion:** When work is done, extract key findings from the tools used. Scale distillation depth to the value of the content.
+- **Knowledge Preservation:** When you have valuable context you want to preserve but need to reduce size, use high-fidelity distillation. Your distillation must be comprehensive, capturing technical details (signatures, logic, constraints) such that the raw output is no longer needed. THINK: high signal, complete technical substitute.
 
-You WILL use `extract` when ANY of these are true:
+You WILL evaluate extracting when ANY of these are true:
 - Task or sub-task is complete
 - You are about to start a new phase of work
-- You have gathered enough information to extract from related tools and preserve their value via distillation
-- Context contains tool outputs that are unhelpful, noise, or made obsolete by newer outputs
 - Write or edit operations are complete (extracting removes the large input content)
 
 You MUST NOT extract when: