Prompt Refiner

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:

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

Converted and distributed by TomeVault — claim your Tome and manage your conversions.