prompt-optimizer

What this skill does

# Prompt Optimizer

This skill analyzes user prompts and provides optimized versions that are clearer, more specific, and more actionable.

## Purpose

Transform vague, incomplete, or ambiguous user requests into well-structured prompts that lead to better outcomes. By analyzing prompts against quality criteria and providing optimized versions, this skill helps users communicate their needs more effectively.

## When to Use This Skill

Use this skill when user prompts exhibit one or more of these issues:

### Clarity Issues
- Vague language: "something", "thing", "stuff", "it", "this"
- Ambiguous pronouns without clear referents
- Multiple possible interpretations
- Unclear desired outcome

### Specificity Issues
- Missing context about the problem domain
- No technical specifications (language, framework, version)
- Lack of examples when examples would help
- Undefined scope or boundaries

### Completeness Issues
- Missing required information or inputs
- No success criteria defined
- Undefined behavior for edge cases
- Missing constraints or requirements

### Structure Issues
- Disorganized information
- Complex requests without clear structure
- Mixing context with requests
- No logical flow

### Actionability Issues
- No clear action verb or request
- Passive voice making intent unclear
- Confusing or conflicting instructions
- Missing output format specification

## Activation Triggers

Activate this skill when detecting:
- Vague words: "something", "thing", "stuff", "it", "this", "that"
- Quality indicators: "better", "good", "nice" (without criteria)
- Incomplete requests: "help with...", "can you...", "fix..." (without details)
- Overly broad requests: "build an app", "create a system"
- Missing specifications in technical requests
- Requests without clear success criteria

## Analysis Workflow

**Two modes available:**

### Mode 1: Interactive Questionnaire (Recommended for Complex Requests)
Use the AskUserQuestion tool to guide users through structured questions. This collaborative approach helps users clarify their needs step-by-step.

**When to use**: Medium to complex requests, or when user prefers guided interaction.

### Mode 2: Direct Analysis (Fast)
Analyze the prompt and provide suggested improvements in one response.

**When to use**: Simple optimization needs, or when user wants quick results.

**Default**: Start with Mode 2 (Direct Analysis). If user requests interactive mode or if the request is very complex, switch to Mode 1.

---

## Mode 2: Direct Analysis Workflow

### Step 1: Receive and Read the Prompt

Carefully read the user's original prompt to understand their intent.

### Step 2: Identify Issues

Systematically check for issues using `references/optimization-principles.md`:

**Clarity Check**:
- Is the language specific and concrete?
- Are all terms clearly defined?
- Is there only one reasonable interpretation?

**Specificity Check**:
- Is sufficient context provided?
- Are technical requirements specified?
- Are examples included when helpful?

**Completeness Check**:
- Is all necessary information present?
- Are success criteria defined?
- Are edge cases considered?

**Structure Check**:
- Is information organized logically?
- Is the request easy to parse?
- Is context separated from the task?

**Actionability Check**:
- Is there a clear action requested?
- Is the output format specified?
- Are instructions unambiguous?

### Step 3: Categorize Issues

List all identified issues by category:
- Clarity problems: [list]
- Specificity gaps: [list]
- Completeness deficiencies: [list]
- Structure issues: [list]
- Actionability concerns: [list]

### Step 4: Generate Optimized Prompt

Create an improved version following these principles:

**Add Specificity**:
- Replace vague terms with concrete descriptions
- Add missing technical specifications
- Include relevant context

**Improve Clarity**:
- Use clear, unambiguous language
- Define all terms
- Eliminate multiple interpretations

**Ensure Completeness**:
- Add missing requirements
- Define success criteria
- Specify constraints

**Enhance Structure**:
- Organize information logically
- Use bullet points and sections
- Separate context from task

**Make Actionable**:
- Start with clear action verb
- Specify output format
- Provide concrete deliverables

Reference `references/optimization-principles.md` for patterns and examples.

### Step 5: Present Analysis

Provide a structured response:

1. **Original Prompt**: Show the user's original request

2. **Identified Issues**: List specific problems found
   - Categorized by type
   - Brief explanation of each

3. **Optimized Prompt**: Provide improved version
   - Well-structured
   - Complete
   - Actionable

4. **Key Improvements**: Highlight main changes
   - What was added
   - What was clarified
   - Why it's better

5. **Optional**: Offer to refine further or proceed with the optimized prompt

---

## Mode 1: Interactive Questionnaire Workflow

### When User Requests Interactive Mode

If the user explicitly asks for interactive/questionnaire mode, or if the prompt has multiple complex issues, use this workflow.

### Step 1: Quick Initial Analysis

Quickly identify the main categories of missing information:
- Technical specifications needed?
- Functional requirements unclear?
- Design/styling preferences missing?
- Scope or constraints undefined?

### Step 2: Design Question Set

Based on the analysis, prepare 1-4 targeted questions using AskUserQuestion tool.

**Question Structure**:
- Each question should have a clear header (max 12 chars)
- Provide 2-4 specific options
- Include descriptions explaining each option
- Allow "Other" for custom input (automatically provided)

**Question Categories**:

**For Code Requests**:
1. Technology Stack (React, Vue, vanilla JS, etc.)
2. Type System (TypeScript, JavaScript)
3. Styling Approach (Tailwind, CSS Modules, styled-components, etc.)
4. Feature Requirements (specific functionality needed)

**For Component Requests**:
1. Component Type (Button, Form, Card, Modal, etc.)
2. Variants Needed (primary/secondary, sizes, states)
3. Props/API (what should it accept?)
4. Use Cases (how will it be used?)

**For UI/Design Requests**:
1. Platform (Web, Mobile, Desktop app)
2. Design Style (Modern, Minimal, Colorful, Corporate)
3. Responsive Needs (Mobile-first, Desktop-only, Adaptive)
4. Key Features (what must be included?)

### Step 3: Use AskUserQuestion Tool

Call the AskUserQuestion tool with structured questions.

**Important**: Always include a final open-ended question that allows users to add custom requirements using the "Other" option.

```typescript
AskUserQuestion({
  questions: [
    {
      question: "What technology stack should this use?",
      header: "Tech Stack",
      multiSelect: false,
      options: [
        {
          label: "React + TypeScript",
          description: "Modern React with full type safety"
        },
        {
          label: "React + JavaScript",
          description: "React without TypeScript"
        },
        {
          label: "Vue 3",
          description: "Vue 3 Composition API"
        },
        {
          label: "Vanilla JavaScript",
          description: "Plain JS without frameworks"
        }
      ]
    },
    {
      question: "What styling approach would you like?",
      header: "Styling",
      multiSelect: false,
      options: [
        {
          label: "Tailwind CSS",
          description: "Utility-first CSS framework"
        },
        {
          label: "CSS Modules",
          description: "Scoped CSS with modules"
        },
        {
          label: "styled-components",
          description: "CSS-in-JS solution"
        }
      ]
    },
    {
      question: "Which features are needed?",
      header: "Features",
      multiSelect: true,
      options: [
        {
          label: "Multiple variants",
          description: "Different color/style variants (primary, secondary, etc.)"
        },