prompt-refiner

name	prompt-refiner
description	Refine rough prompts into structured, high-quality prompts. Use this skill when the user has a vague request and wants to turn it into a well-structured prompt with clear objectives, constraints, and acceptance criteria. Triggers include "refine this prompt", "make this prompt better", "structure this request", or "help me write a better prompt".

Prompt Refiner

Transform rough, vague prompts into structured prompts that produce accurate, actionable results.

References

Use these templates in the references/ folder based on task type:

• template-exploration.md - Understanding code, finding implementations, tracing flows
• template-feature.md - Implementing new functionality, adding screens
• template-bugfix.md - Investigating and fixing bugs, crashes
• template-telemetry.md - Adding logging, events, instrumentation

Why This Matters

Vague prompts lead to:

• Hallucinated file names and patterns
• Generic advice instead of specific guidance
• Missing validation steps
• Wasted iteration cycles

Structured prompts lead to:

• Grounded responses with file paths and evidence
• Actionable next steps
• Built-in validation checkpoints
• Faster time-to-value

Refinement Workflow

Step 1: Analyze the Rough Prompt

Identify what's missing:

• Objective: What is the actual goal? (Often buried or implied)
• Scope: What's in/out of bounds?
• Constraints: What rules must be followed?
• Evidence requirements: Should responses cite files/code?
• Validation: How will we know if the answer is correct?

Step 2: Ask Clarifying Questions (if needed)

Before refining, ask the user 2-3 targeted questions:

• "Is this for new code or modifying existing code?"
• "Should this be behind a feature flag?"
• "What's the risk level? (experimental vs production-critical)"
• "Are there existing patterns in the codebase I should follow?"

Step 3: Generate the Refined Prompt

Use this template structure:

## Objective
[One clear sentence describing the goal]

## Context
[Brief background if needed - what problem this solves, why now]

## Constraints
- [Hard rule 1 - e.g., "Only reference files that exist in the repo"]
- [Hard rule 2 - e.g., "Do not modify existing public APIs"]
- [Hard rule 3 - e.g., "Must be behind a feature flag"]

## Scope
**In scope:**
- [What should be addressed]

**Out of scope:**
- [What should NOT be addressed]

## Acceptance Criteria
- [ ] [Specific, verifiable criterion 1]
- [ ] [Specific, verifiable criterion 2]
- [ ] [Validation step - e.g., "Compile check passes"]

## Output Format
[Specify what the response should look like - file paths, code snippets, plan, etc.]

Step 4: Add Domain-Specific Constraints

Based on the task type, add relevant constraints:

For code exploration/understanding:

• "Provide file paths and line numbers for all references"
• "Do not guess patterns—search the codebase first"
• "Show the call flow with actual function names"

For new feature implementation:

• "Wrap new functionality behind ExperimentationFeatureFlag"
• "Follow existing patterns in [similar feature area]"
• "Include unit test recommendations"

For bug fixes:

• "Identify root cause before proposing fix"
• "List potential regression risks"
• "Include validation steps to confirm fix"

For refactoring:

• "No behavioral changes—preserve existing functionality"
• "Show before/after for each change"
• "Ensure all existing tests still pass"

For telemetry/logging:

• "No PII in any logged fields"
• "Include local validation approach"
• "Specify sampling/flag configuration"

Output Format

When refining a prompt, provide:

1. The refined prompt (ready to copy/paste)
2. What was added (brief explanation of key improvements)
3. Suggested follow-ups (what to ask next after getting results)

Examples

Example 1: Code Exploration

Rough prompt:

"Where is authentication handled in this app?"

Refined prompt:

## Objective
Identify the entry points and core components responsible for authentication in this codebase.

## Constraints
- Only reference files that exist in the repo (provide file paths)
- Focus on the primary authentication flow, not edge cases
- Do not guess—search for actual implementations

## Acceptance Criteria
- [ ] Entry point(s) identified with file paths
- [ ] Key classes/functions listed with their responsibilities
- [ ] Call flow documented (what calls what)
- [ ] Links to relevant configuration files

## Output Format
Provide a brief architecture overview with file paths, then a numbered call flow.

What was added: Evidence requirements (file paths), scope limitation (primary flow), specific output format.

---

Example 2: New Feature

Rough prompt:

"Add a retry mechanism for failed API calls"

Refined prompt:

## Objective
Implement a retry mechanism for failed API calls with configurable retry count and backoff.

## Context
Some API calls fail transiently due to network issues. We need automatic retry with exponential backoff.

## Constraints
- Use existing HTTP client infrastructure (do not add new libraries)
- Wrap behind ExperimentationFeatureFlag.API_RETRY
- Only retry on transient errors (5xx, timeout), not client errors (4xx)
- Maximum 3 retries with exponential backoff (1s, 2s, 4s)

## Scope
**In scope:** Core retry logic, configuration, integration with existing client

**Out of scope:** UI changes, offline handling, request queuing

## Acceptance Criteria
- [ ] Retry logic implemented with configurable count
- [ ] Exponential backoff with jitter
- [ ] Feature flag integration
- [ ] Unit tests for retry scenarios (success after retry, max retries exceeded)
- [ ] Compile check passes: `.\gradlew app:compileProductionDebugKotlin`

## Output Format
1. Implementation plan (which files to modify)
2. Code changes with file paths
3. Test cases to add

What was added: Specific behavior (which errors to retry), constraints (feature flag, no new libs), concrete acceptance criteria.

---

Example 3: Telemetry

Rough prompt:

"Add logging for the sign-in flow"

Refined prompt:

## Objective
Add telemetry events to track sign-in flow success, failure, and duration.

## Constraints
- **No PII**: Do not log email, username, phone, device ID, or tokens
- Use existing telemetry service (SharedCoreLibrary logging)
- Events must be behind a feature flag or sampling config
- Each event must answer a specific business question

## Event Requirements
For each event, define:
- Event name (namespaced: `signin_*`)
- Purpose (what question does this answer?)
- Fields (name, type, example, PII risk)
- Trigger condition

## Acceptance Criteria
- [ ] 2-3 events defined with full schema
- [ ] Logging points identified (file paths + function names)
- [ ] Local validation approach documented
- [ ] No PII in any field
- [ ] Feature flag specified

## Output Format
Event table, then implementation locations, then validation steps.

What was added: Explicit PII prohibition, schema requirements, validation approach.

Anti-Patterns to Avoid

When refining prompts, watch for and fix these issues:

Anti-Pattern	Problem	Fix
"Make it good"	Subjective, unmeasurable	Add specific acceptance criteria
"Handle all cases"	Unbounded scope	Define in-scope vs out-of-scope
"Like other apps do"	Relies on assumptions	Reference specific patterns in THIS codebase
"ASAP"	Pressure without clarity	Define actual priority and constraints
No validation step	Can't verify correctness	Add "how do we know it's right?"

Quick Reference: Constraint Templates

Copy-paste these common constraints as needed:

Evidence-based responses:

- Only reference files that exist in the repo (provide file paths + line numbers)
- Do not guess patterns—search the codebase first
- Show actual code/config, not hypothetical examples

Safe implementation:

- Wrap new functionality behind ExperimentationFeatureFlag.[FLAG_NAME]
- No breaking changes to existing public APIs
- Follow existing patterns in [similar area of codebase]

Privacy/security:

- No PII in logs (email, phone, name, device ID, tokens)
- No hardcoded secrets or credentials
- Use SecureKeystoreLibrary for sensitive storage

Validation:

- Compile check: `.\gradlew [module]:compileProductionDebugKotlin`
- Existing tests pass: `.\gradlew [module]:test`
- Manual verification steps documented