Prompt Improver

Prompt Improver Skill

Purpose

Transform vague, ambiguous prompts into actionable, well-defined requests through systematic research and targeted clarification. This skill is invoked when the hook has already determined a prompt needs enrichment.

When This Skill is Invoked

Automatic invocation:

• UserPromptSubmit hook evaluates prompt
• Hook determines prompt is vague (missing specifics, context, or clear target)
• Hook invokes this skill to guide research and questioning

Manual invocation:

• To enrich a vague prompt with research-based questions
• When building or testing prompt evaluation systems
• When prompt lacks sufficient context even with conversation history

Assumptions:

• Prompt has already been identified as vague
• Evaluation phase is complete (done by hook)
• Proceed directly to research and clarification

Core Workflow

This skill follows a 4-phase approach to prompt enrichment:

Phase 1: Research

Create a dynamic research plan using TodoWrite before asking questions.

Research Plan Template:

1. Check conversation history first - Avoid redundant exploration if context already exists
2. Review codebase if needed:
   • Task/Explore for architecture and project structure
   • Grep/Glob for specific patterns, related files
   • Check git log for recent changes
   • Search for errors, failing tests, TODO/FIXME comments
3. Gather additional context as needed:
   • Read local documentation files
   • WebFetch for online documentation
   • WebSearch for best practices, common approaches, current information
4. Document findings to ground questions in actual project context

Critical Rules:

• NEVER skip research
• Check conversation history before exploring codebase
• Questions must be grounded in actual findings, not assumptions or base knowledge
• Route Glob, Grep, WebSearch, WebFetch, and multi-file Read through Task/Explore — never call them directly in main context
• Include conversation-relevant context (file paths, errors, prior decisions) in every Explore prompt — Explore cannot see prior turns

For detailed research strategies, patterns, and examples, see references/research-strategies.md.

Phase 2: Generate Targeted Questions

Based on research findings, formulate 1-6 questions that will clarify the ambiguity.

Question Guidelines:

• Grounded: Every option comes from research (codebase findings, documentation, common patterns)
• Specific: Avoid vague options like "Other approach"
• Multiple choice: Provide 2-4 concrete options per question
• Focused: Each question addresses one decision point
• Contextual: Include brief explanations of trade-offs

Number of Questions:

• 1-2 questions: Simple ambiguity (which file? which approach?)
• 3-4 questions: Moderate complexity (scope + approach + validation)
• 5-6 questions: Complex scenarios (major feature with multiple decision points)

For question templates, effective patterns, and examples, see references/question-patterns.md.

Phase 3: Get Clarification

Use the AskUserQuestion tool to present your research-grounded questions.

AskUserQuestion Format:

- question: Clear, specific question ending with ?
- header: Short label (max 12 chars) for UI display
- multiSelect: false (unless choices aren't mutually exclusive)
- options: Array of 2-4 specific choices from research
  - label: Concise choice text (1-5 words)
  - description: Context about this option (trade-offs, implications)

Important: Always include multiSelect field (true/false). User can always select "Other" for custom input.

Phase 4: Execute with Context

Proceed with the original user request using:

• Original prompt intent
• Clarification answers from user
• Research findings and context
• Conversation history

Execute the request as if it had been clear from the start.