prompt-refiner

# prompt-refiner > A prompt is not just wording polish — it is task clarification, boundary setting, and verification shaping. Refine vague user prompts into clear, actionable, verifiable versions. Show the refined result and let the user confirm before execution. Works as a closed loop with `session-learner`, which captures user choice preferences over time. ## Quick Reference | Situation | Action | |-----------|--------| | Vague request | Refine first | | Complete prompt | Execute directly, no popup | | Substantial improvement | Show refined + popup choose | | No substantial improvement | Skip popup, execute original | | User says "just do it" | Auto-apply | | User says "only optimize" | Return refined, don't execute | ## Continue Modes 1. **Popup-confirm (default)** — Show refined prompt, popup to choose refined vs original, execute after choice 2. **Auto-apply** — When user says "just do it / skip confirmation", show refined then execute immediately 3. **Optimize-only** — When user only asks to refine without executing, return refined result only ## When NOT to Use - User input is already well-structured with clear goals, constraints, and acceptance criteria - Single-step operations (delete a line, rename a variable, change a single string) - Simple factual questions or explanations - User explicitly says "don't optimize" or "just do it" ## Workflow 1. Extract original prompt and current session context (goals, constraints, tech stack, errors, expected output). 2. Generate refined prompt, ensuring: - Core intent unchanged - Goals and boundaries explicit - Output format verifiable - Language concise, no fluff 3. Produce result based on Continue Mode. 4. After user makes a choice, generate a **learning signal** for `session-learner` — capture preference pattern, never record full prompt text. ## Refined Prompt Structure Include the following blocks as needed (trim, don't mechanically stack): - Goal - Context - Constraints / Non-goals - Execution Requirements - Output Format - Acceptance Criteria For detailed patterns and examples, see `references/prompt-patterns.md`. ## Output Templates ### A) Popup-confirm (default) **First, judge whether refinement adds real value.** If the refined prompt only tweaks wording without adding explicit goals/constraints/output format/acceptance criteria, and doesn't significantly reduce ambiguity, it has **no substantial optimization value**. - **No substantial value**: Don't popup, don't interrupt. Execute with the original prompt directly. - **Has substantial value**: Execute the two steps below. Do not skip or merge them. **Step 1 (required): Output the refined prompt as plain text in the chat area first.** > **Optimized Prompt** > <full refined prompt content> **Step 2 (required, after step 1): Call AskUserQuestion popup for user to choose.** Options: - A: Use refined prompt to continue (recommended) - B: Use original prompt to continue Forbidden: - Do not popup without showing the refined prompt content first - Do not put the refined prompt inside AskUserQuestion description as a substitute for step 1 - Steps 1 and 2 must be in the same response Execute after user chooses. ### B) Auto-apply > **Optimized Prompt** > <refined prompt> --- Then execute immediately. ### C) Optimize-only > **Optimized Prompt** > <refined prompt> Do not execute the task. ## Heuristics - Rewrite vague phrases ("optimize it / make it better / fix it up") into actionable steps with clear criteria. - Fill in missing inputs, boundary conditions, and completion definitions. - For code tasks: specify scope, verification method, expected deliverables. - For content tasks: specify audience, tone, length, structure constraints. - If critical context is missing, ask the minimum necessary clarification; otherwise proceed. ## Integration with session-learner - When user chooses refined or rejects it, this is a **preference signal** for `session-learner`. - `session-learner` should only summarize rules (e.g., "user prefers seeing refined version before confirming"), never record full prompt text. - Over time, `session-learner` builds a preference profile that makes `prompt-refiner` increasingly aligned with user habits. ## Priority Rules - When user explicitly specifies a flow, follow user instructions. - When no explicit instruction, use Popup-confirm.