Prompt Refinement Skill

Transform messy, incomplete prompts into well-structured specifications using the TCRO framework (Task, Context, Requirements, Output) with phase-specific clarifying questions.

Purpose

This skill ensures all user prompts to ai-eng-system commands are properly structured before execution, reducing ambiguity, increasing reproducibility, and improving AI response quality.

When This Skill is Invoked

This skill is ALWAYS invoked at the start of:

/ai-eng/research
/ai-eng/specify
/ai-eng/plan
/ai-eng/work

Commands should include this directive:

Use skill: prompt-refinement
Phase: [research|specify|plan|work]

The TCRO Framework

Element	Purpose	Key Question
Task	What's the job to be done?	"What specific outcome do you need?"
Context	Why does this matter?	"What's the broader system/goal?"
Requirements	What are the constraints?	"What are the must-haves vs nice-to-haves?"
Output	What format is needed?	"What should the deliverable look like?"

Process

Step 1: Read Project Context

Load CLAUDE.md from the project root to understand:

Project philosophy and core principles
Tech stack preferences
Quality standards and conventions
Naming conventions
Architectural patterns

Step 2: Detect Phase

Determine which phase based on:

The command being invoked
Keywords in the prompt (research, learn, investigate → research)
Explicit phase markers in user input

Step 3: Load Phase Template

Based on detected phase, load the appropriate template:

templates/research.md for /ai-eng/research
templates/specify.md for /ai-eng/specify
templates/plan.md for /ai-eng/plan
templates/work.md for /ai-eng/work

Step 4: Ask Clarifying Questions

Use phase-specific questions from the loaded template.

Minimum required questions:

1 Task question
1 Context question
1-2 Requirements questions
1 Output question

Present questions interactively:

Display original user prompt
Ask clarifying questions one at a time or in small groups
Collect user responses
Use responses to structure refined prompt

Step 5: Structure into TCRO

Format the refined prompt using the TCRO structure:

Task: [Specific, actionable task statement]
Context: [Broader system, goals, constraints from CLAUDE.md]
Requirements:
  - [Must-have requirement 1]
  - [Must-have requirement 2]
  - [Nice-to-have if mentioned]
Output: [Expected deliverable format and location]

Step 6: Apply Incentive Prompting

Enhance the TCRO-structured prompt with techniques from the incentive-prompting skill:

Expert Persona: Assign appropriate role based on task
Stakes Language: Add "This is critical..." for high-importance tasks
Step-by-Step Reasoning: Add "Take a deep breath and solve step by step"
Self-Evaluation: Add "Rate your confidence 0-1" request

Step 7: Confirm with User

Display the refined prompt and ask for confirmation:

## Refined Prompt

[The TCRO-structured, incentive-enhanced prompt]

Proceed with this refined prompt? (y/n/edit)

y: Proceed with refined prompt
n: Ask more clarifying questions
edit: Allow user to manually refine the prompt

Integration with Commands

Commands should reference this skill with:

---
name: ai-eng/[command-name]
description: [Description]
agent: [agent]
---

Use skill: prompt-refinement
Phase: [research|specify|plan|work]

# [Command Name]

[Rest of command definition...]

Template Structure

Phase-specific templates are located in templates/:

skills/prompting/prompt-refinement/
├── SKILL.md
└── templates/
    ├── research.md
    ├── specify.md
    ├── plan.md
    └── work.md

Each template includes:

Phase-specific clarifying questions
TCRO structure for that phase
Examples of vague → refined transformations
Phase-specific requirements and considerations

Example Transformation

Input (Vague)

"need auth"

Phase Detection

Detected phase: specify (feature request)

Clarifying Questions

Task: What type of authentication capability do you need?
- User login/logout
- OAuth/SSO integration
- API key management
- Multi-factor authentication (MFA)
- Other: _________
Context: What's the broader system this fits into?
- New greenfield project or adding to existing codebase?
- What's the tech stack?
- Are there existing authentication patterns to follow?
Requirements: What are the must-have requirements?
- Security/compliance needs (SOC2, GDPR, etc.)?
- User experience expectations?
- Rate limiting requirements?
Output: What should the specification include?
- User stories only
- Full spec with acceptance criteria
- Include non-functional requirements
- Include UI/UX considerations

Refined TCRO

Task: Create specification for JWT-based user authentication system
Context:
  Adding to existing Next.js application with PostgreSQL database.
  Project follows CLAUDE.md philosophy of simplicity and pragmatism.
  Existing authentication middleware pattern in src/lib/auth/ can be extended.
Requirements:
  Must-have:
  - Email/password login with secure password hashing (bcrypt, cost factor 12)
  - JWT token-based session management with configurable expiry
  - Password reset flow via email delivery
  - Rate limiting on authentication endpoints (5 attempts/minute)
  Nice-to-have:
  - Email verification for new accounts
  - Session persistence across device reboots
  Non-functional:
  - Security: Tokens must be cryptographically secure, single-use for reset flows
  - Performance: Authentication requests should complete within 200ms (p95)
  - Compliance: GDPR-compliant data handling, no passwords in logs
Output:
  Full specification with user stories, acceptance criteria, and non-functional
  requirements saved to specs/auth/spec.md in Spec Kit compatible format.

Incentive-Enhanced Prompt

You are a senior security engineer and product owner with 15+ years of experience
building production authentication systems at companies like Stripe and Auth0.

Task: Create a comprehensive specification for JWT-based user authentication system
Context:
  Adding to existing Next.js application with PostgreSQL database.
  Project follows CLAUDE.md philosophy of simplicity and pragmatism.
  Existing authentication middleware pattern in src/lib/auth/ can be extended.

Requirements:
  Must-have:
  - Email/password login with secure password hashing (bcrypt, cost factor 12)
  - JWT token-based session management with configurable expiry
  - Password reset flow via email delivery
  - Rate limiting on authentication endpoints (5 attempts/minute)
  Nice-to-have:
  - Email verification for new accounts
  - Session persistence across device reboots
  Non-functional:
  - Security: Tokens must be cryptographically secure, single-use for reset flows
  - Performance: Authentication requests should complete within 200ms (p95)
  - Compliance: GDPR-compliant data handling, no passwords in logs

Output:
  Full specification with user stories, acceptance criteria, and non-functional
  requirements saved to specs/auth/spec.md in Spec Kit compatible format.

Take a deep breath and think through this specification systematically. Consider all
security implications, edge cases, and user experience flows before finalizing.

Rate your confidence in this specification from 0-1 after completion.

Handling Edge Cases

Prompt Already Structured

If user input is already well-structured:

Analyze prompt for TCRO elements
Identify any missing elements
Ask targeted questions to fill gaps (not full re-clarification)
Confirm if structure is sufficient or needs refinement

User Refuses Clarification

If user declines clarifying questions:

Proceed with best-effort TCRO structure
Use [NEEDS CLARIFICATION: ...] markers for ambiguous items
Note which elements were assumed vs explicitly specified

Incomplete Context

If CLAUDE.md doesn't exist or is incomplete:

Proceed without project-specific context
Ask basic context questions (tech stack, goals)
Note in refined prompt: "No project constitution found, using generic defaults"

Quality Checklist

Before finalizing refined prompt, verify:

Task is specific and actionable
Context includes relevant project information
Requirements distinguish must-have vs nice-to-have
Output format is clearly specified
Appropriate expert persona assigned
Stakes language added for important tasks
Clarification markers used for ambiguities

Integration with incentive-prompting Skill

This skill builds on the incentive-prompting skill. Always load both skills together when refining prompts:

Use skill: incentive-prompting
Use skill: prompt-refinement

The incentive-prompting skill provides the enhancement techniques (Expert Persona, Stakes Language, Step-by-Step, Self-Evaluation).

This skill provides the structuring framework (TCRO) and phase-specific clarification questions.

Together they produce prompts that are both well-structured and enhanced for maximum AI response quality.

prompt-refinement