Prompt refinement

Prompt Refinement

Overview

Prompt refinement transforms ambiguous or incomplete user requests into clear, structured task specifications suitable for multi-agent orchestration. This skill bridges natural language input and the precise specifications required by downstream agents.

Purpose

Ensure tasks entering the orchestration pipeline have:

• Clear Objectives: A single, well-defined goal that can be verified
• Actionable Steps: Concrete actions that agents can execute
• Measurable Outcomes: Success criteria that verification agents can check
• Appropriate Scope: Boundaries that prevent scope creep

When to Use This Skill

Apply prompt refinement when:

• User input contains ambiguous terms ("fix it", "make it better")
• The request lacks specific targets (files, components, systems)
• Multiple interpretations of the request are possible
• Pre-processing is required for /orchestrate or /plan commands

Key Principles

1. Ask First, Act Second: When genuinely ambiguous, clarify before proceeding
2. One Question at a Time: Never overwhelm users with multiple clarification requests
3. Provide Options: Give concrete choices to speed up clarification
4. Default Gracefully: Make reasonable assumptions when users don't respond
5. Preserve Intent: Refinement should clarify, not change the user's goal

---

Refinement Template

Standard Format

**Goal**: <one-sentence objective stating what will be accomplished>

**Description**: <2-3 sentences providing context and scope>

**Actions**:
1. <specific, atomic action with clear target>
2. <specific, atomic action with clear target>
3. ...

**Constraints**: <what must not be broken, changed, or violated>

**Assumptions**: <what is taken for granted — surfaces risks early>

Template Guidelines

Field	Requirements	Example
Goal	Single sentence, verb-first, specific outcome	"Implement rate limiting on /api/users endpoint"
Description	Context, scope boundaries	"Add rate limiting to prevent API abuse. Limit to 100 req/min per IP."
Actions	Numbered, ordered, atomic steps	"1. Explore existing middleware patterns"
Constraints	Non-negotiable requirements; what must stay intact	"Must not alter existing auth cookie format"
Assumptions	Preconditions taken for granted	"Redis is already provisioned"

After capturing all five fields, the orchestrator classifies task_complexity (trivial/exploratory/implementation/complex/research) and persists the structured intent to the state file via --set-intent-goal, --set-intent-description, --set-intent-actions, --set-intent-constraints, --set-intent-assumptions, and --set-task-complexity. These values are passed verbatim (no re-summarization) to all downstream agents.

Action Step Pattern

1. Explore: Investigate existing code, patterns, dependencies
2. Plan: Design approach based on exploration
3. Implement: Execute the core changes
4. Test: Add or update tests
5. Verify: Confirm implementation meets requirements

---

Ambiguity Detection

Quick Detection Checklist

A prompt likely needs clarification if:

• No identifiable action (what to do)
• No specific target (where to do it)
• No expected outcome (success criteria)
• Insufficient context (constraints, environment)

Ambiguity Signals

Signal	Example	Issue
Missing scope	"fix the bug"	Which bug? Where?
Vague outcome	"make it better"	Better how?
Multiple meanings	"update the API"	Which endpoint? What change?
Implicit assumptions	"deploy it"	Where? How?

For detailed ambiguity detection, see references/ambiguity-detection.md.

---

Clarification Strategy

Question Format

Before I proceed, I need to clarify:

<single focused question>

Options:
A) <most likely option>
B) <second most likely>
C) <third option if applicable>
D) Something else (please specify)

Clarification Rules

Rule	Rationale
Single question	Reduces cognitive load
Concrete options	Speeds up response
Max two rounds	Avoids frustration
Include escape hatch	Prevents forced incorrect choice

When to Clarify vs. Assume

Always Clarify:

• Could cause data loss
• Affects security
• Mutually exclusive interpretations
• Production system impact

Safe to Assume:

• Obvious default exists
• Context suggests intent
• Low-risk, reversible operations

For detailed clarification strategies, see references/clarification-strategies.md.

---

Orchestration Detection

Prompts Requiring Orchestration

Category	Example
Multi-file changes	"Add authentication to all routes"
Feature implementations	"Implement dark mode"
Bug investigation	"Fix the login issue"
Refactoring	"Refactor user service"
Integration	"Integrate Stripe"

Pass-Through Prompts

Category	Example
Questions	"What does this function do?"
Single-file edits	"Add comment to line 42"
Git operations	"Commit these changes"
Documentation lookups	"Show API endpoints"

Quick Decision

Is it a question about existing code? -> Pass through
Does it require code changes? -> If no, pass through
Is target explicit AND single file? -> Pass through
Otherwise -> Refine for orchestration

For detailed orchestration detection, see references/orchestration-detection.md.

---

Refinement Process

Step 1: Classify Prompt

Is it orchestration-related?
├── NO -> Pass through unchanged
└── YES -> Continue to Step 2

Step 2: Detect Ambiguity

Check ambiguity signals
├── High ambiguity -> Go to Step 3 (Clarify)
└── Low ambiguity -> Go to Step 4 (Refine)

Step 3: Request Clarification

1. Identify primary ambiguity
2. Formulate single focused question
3. Provide 3-4 concrete options
4. Wait for response (max 2 rounds)

Step 4: Apply Template

1. Extract Goal (single sentence, specific)
2. Build Description (context, scope, constraints)
3. Decompose Actions (atomic, ordered steps)
4. Validate completeness

---

Quick Reference

Ambiguity Score Quick Guide

Score	Action
0-2	Proceed with refinement
3-4	State assumption and proceed
5+	Ask clarifying question

Short imperative with a concrete target → state assumption and proceed, do not ask.

Refinement Decision Matrix

Prompt Type	Action
Clear + orchestration	Refine to template
Ambiguous + orchestration	Clarify then refine
Clear + non-orchestration	Pass through
Ambiguous + non-orchestration	Minimal clarification

---

Additional Resources

Reference Files

• references/ambiguity-detection.md - Detecting ambiguous prompts
• references/clarification-strategies.md - Clarification question strategies
• references/orchestration-detection.md - Orchestration eligibility detection
• references/refinement-techniques.md - Advanced refinement techniques

Examples

• examples/refinement-scenarios.md - Worked refinement examples

Related Skills

• task-classification: Receives refined prompts for complexity assessment
• agent-behavior-constraints: Ensures refinement stays within agent boundaries
• verification-gates: Uses refined specifications for verification criteria