nhouseholder/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

This skill is for genuinely vague prompts only — where the user's intent cannot be determined from the message + conversation context + codebase evidence combined. Most "slightly ambiguous" messages should be handled by prompt-architect's normal inference. This skill is the heavy-duty fallback.

Invocation criteria (ALL must be true):

• The message lacks a clear target (what to change)
• Conversation context doesn't clarify the intent
• Codebase evidence doesn't narrow it to one interpretation
• Getting it wrong would waste significant effort

Do NOT invoke for:

• Short messages with clear context ("fix it", "try again", "that didn't work")
• Messages where prompt-architect can reasonably infer intent
• Messages where a quick one-line clarifying question would suffice (use smart-clarify instead)

Manual invocation:

• User explicitly asks for help clarifying their request
• Complex feature requests with multiple possible interpretations

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

Research strategies: Use WebSearch and Grep to gather context. Search the codebase for related patterns, check documentation, and look up best practices online when needed.

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)

Question patterns: Ask 2-3 specific multiple-choice questions focused on scope, approach, and constraints. Ground each option in codebase findings or established patterns rather than abstract possibilities.

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.

Examples

Example 1: Skill Invocation → Research → Questions → Execution

Hook evaluation: Determined prompt is vague Original prompt: "fix the bug" Skill invoked: Yes (prompt lacks target and context)

Research plan:

1. Check conversation history for recent errors
2. Explore codebase for failing tests
3. Grep for TODO/FIXME comments
4. Check git log for recent problem areas

Research findings:

• Recent conversation mentions login failures
• auth.py:145 has try/catch swallowing errors
• Tests failing in test_auth.py

Questions generated:

1. Which bug are you referring to?
   • Login authentication failure (auth.py:145)
   • Session timeout issues (session.py:89)
   • Other

User answer: Login authentication failure

Execution: Fix the error handling in auth.py:145 that's causing login failures

Example 2: Clear Prompt (Skill Not Invoked)

Original prompt: "Refactor the getUserById function in src/api/users.ts to use async/await instead of promises"

Hook evaluation: Passes all checks

• Specific target: getUserById in src/api/users.ts
• Clear action: refactor to async/await
• Success criteria: use async/await instead of promises

Skill invoked: No (prompt is clear, proceeds immediately without skill invocation)

See the examples above for how prompt types are evaluated and transformed.

Key Principles

1. Assume Vagueness: Skill is only invoked for vague prompts (evaluation done by hook)
2. Research First: Always gather context before formulating questions
3. Ground Questions: Use research findings, not assumptions or base knowledge
4. Be Specific: Provide concrete options from actual codebase/context
5. Stay Focused: Max 1-6 questions, each addressing one decision point
6. Systematic Approach: Follow 4-phase workflow (Research → Questions → Clarify → Execute)

Progressive Disclosure

This SKILL.md contains the complete workflow, research strategies, question patterns, and examples needed for prompt improvement. All guidance is inline — no external reference files required.