[FEATURE] Prompt Review Agent: Pre-flight Context Optimisation and Clarifying Questions

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Claude Code users waste significant time and context window on failed attempts due to vague or poorly-contextualised prompts. When working on complex codebases, I constantly need to:

• Manually add the same @mentions and context with every prompt
• Re-explain architectural decisions after context resets
• Retry commands multiple times because initial prompts were ambiguous
• Perform /clear operations when context becomes polluted from failed attempts

Current workflow pain points:

• No prompt validation: Vague prompts like "fix the bug" execute immediately, wasting tokens
• Manual context management: Must remember which files to @mention for each task type
• Repeated failures: Poor initial prompts lead to 3-5 retry cycles on average

Community evidence shows this is the #1 pain point - Issue #1345 documents users building 62-agent external systems just to manage context, and Issue #362 requesting predefined prompts has significant support.

Proposed Solution

What I want:

A "Prompt Review Agent" that acts as an intelligent intermediary between me and Claude Code. Before my prompt executes, this agent would analyse what I'm asking, identify any ambiguities or missing context, and help me refine my request to get better results on the first attempt.

Think of it like having a senior developer review your requirements before you start coding - they'd ask clarifying questions, point out what context you need, and help you frame the problem more clearly. This agent would do the same for my prompts to Claude Code.

Core concept:

• Intercept prompts before execution (opt-in, not forced)
• Analyse the prompt against current project context
• Identify users actual intent, and any gaps, ambiguities, or missing information
• Provide interactive assistance to enhance the prompt
• Execute with improved context and clarity

How this might work in practice:

When I activate the review mode (perhaps similar to Plan Mode with Shift+Tab), the agent would:

• Analyse my intent - Parse my prompt to understand what I'm trying to achieve
• Check current context - See what files are open, what's in the context window, recent changes
• Identify gaps - Detect missing information that would lead to poor outcomes
• Suggest improvements - Offer specific files to include, clarifying questions, or prompt reformulations
• Let me refine - Give me control to accept, modify, or skip suggestions
• Execute once - Run the enhanced prompt with proper context

Example interaction flow:

My prompt: "fix the bug in auth"

The agent recognises this is vague and could help by:

• Asking which auth component (login, logout, JWT validation)
• Checking recent error logs or TODOs for auth-related issues
• Suggesting relevant files that should be included in context
• Offering a more specific prompt based on the clarifications

I could then quickly select the relevant options and proceed with a well-formed prompt that includes all necessary context, rather than going through multiple failed attempts.

All while none of this would pollute the master code agents context.

Key principles:

Non-blocking: Always possible to skip and send original prompt
Intelligent: Uses project understanding to make smart suggestions
Learning: Remembers patterns to improve over time
Fast: Quick review (5-10 seconds) saves minutes of retry cycles

Integration approach:

This is how I would build on Claude Code's existing architecture:

• Similar UX pattern to Plan Mode (already familiar to users)
• Could be implemented as a specialized subagent that user can extend
• Leverages existing context management systems
• Uses repository analysis tools already available

The goal isn't to make prompt writing harder or slower - it's to make Claude Code more successful on the first attempt by catching issues before they waste time and context window.

Why this is different from existing features:

• Plan Mode helps Claude engineer the context to execute a task successfully, this feature would helps refine what to ask and context to inject. Both could be used in tandem for better outcomes.
• CLAUDE.md provides static context, this dynamically suggests what's needed
• Templates are rigid, this adapts to each specific request
• Current workflow is trial-and-error, this would be right-first-time

Alternative Solutions

Currently trying:

• Creating extensive CLAUDE.md files (doesn't adapt to specific tasks)
• Manually writing detailed prompts (time-consuming, breaks flow)
• Using the community claude-code-prompt-improver plugin (unofficial, limited integration)
• Building custom hooks for validation (requires coding for each project)

Considered but rejected:

• External prompt tools (breaks workflow continuity)
• Static templates only (too rigid for diverse tasks)
• Post-execution correction (wastes tokens on failures)

Priority

High - Significant impact on productivity

Feature Category

Interactive mode (TUI)

Use Case Example

Initial prompt: "update the API endpoint"

• Claude's response: Started modifying random API files
• Had to cancel and retry: "update the /api/users endpoint to add pagination"
• Still missing context: Had to add @api/users/route.ts @types/api.ts
• Finally worked: After 3 attempts and manual context addition

With Prompt Review Agent:

Type: "update the API endpoint"

Review triggers:

• "Which endpoint? Found: /users, /posts, /auth"
• "What type of update? Found recent TODOs about pagination"
• "Suggested files: @api/users/route.ts, @types/api.ts, @tests/users.test.ts"

One-shot success: Enhanced prompt executes correctly first time

This would save 5-10 minutes per complex task and prevent context pollution.

Additional Context

Similar Features in Other Tools:

• None found - No AI coding assistant currently offers automated prompt enhancement
• Cursor has a requested "AI Prompt Optimizer" (unimplemented)
• GitHub Copilot provides static documentation only

Community Validation:

• Reddit sentiment analysis: Context management is main complaint
• GitHub Issues: #1345, #362, #427, #7513 all relate to this problem
• Community workaround exists: severity1/claude-code-prompt-improver