Tracking: Q2 2026 prompt-quality roadmap (research synthesis) #26

Summary

Tracking issue for the Q2 2026 work on prompt-improver. Re-scoped May 2026 after a lens-driven re-evaluation — see the "Closed sub-issues" section at the bottom for what was dropped and why.

The original framing was: "Current detection fires only on clarity (vague vs. clear). The research suggests there is a wider set of failure modes worth catching." After implementing #29 as a prototype and then unshipping it (commit history + #29 close comment), that framing is now contested. The lens we now apply:

The plugin's stated philosophy is "rarely intervene, trust user intent." Surface-form detection of antipatterns (regex/keyword classifiers in the hook) pre-empts the wrapper's context-aware judgment. The eval wrapper + skill, with conversation history and CLAUDE.md, already handle clarity correctly. Pre-emptive intervention based on prompt text alone produces false positives whose cost (broken flow, eroded trust) exceeds the marginal token savings.

This rules out the entire "detect X in prompt → intervene" family. What survives the lens are infrastructure/architectural features that operate on signals the wrapper genuinely can't reach.

Token efficiency principles (binding on all surviving sub-issues)

The hook runs on every prompt submission. Every byte injected counts. All surviving sub-issues must conform to:

• Eval wrapper baseline: ~300 tokens today; no sub-issue may regress this
• Per-feature injection cap: any single nudge / guardrail / hint ≤80 tokens
• Conditional injection only — features add zero tokens when they don't fire
• Skill loads only on non-clear classification — clear prompts must not load the skill or its references
• No new dependencies — Python stdlib only; no imports outside json, sys, re, pathlib
• No network calls in hooks — hooks must complete in <100ms

Surviving sub-issues

These passed the lens — they address signals the wrapper cannot see, or are pure cleanup/efficiency improvements:

Suggested implementation order

1. Simplify hook output from JSON to plain text #17 hook output simplification — lowest risk, removes failure modes, unblocks future work
2. Add PreCompact hook to preserve original goal and hard constraints #27 PreCompact hook — addresses the highest-impact failure mode that only the hook layer can address
3. Add Stop hook to detect unauthorized scope expansion #28 Stop hook scope audit — once "meaningfully larger" is defined; observational, non-blocking
4. Route all skill research through Explore subagents #18 Explore-routed research — token efficiency on skill path
5. Track upstream updatedPrompt for UserPromptSubmit (anthropics/claude-code#27365) #32 upstream tracker — passive watch; revisit when updatedPrompt ships
6. Enhance eval wrapper with XML structure, parallel research, token budget awareness, and GOLDEN framework #8 (rescoped) parallel research — additive improvement to skill path

Closed sub-issues (lens-driven re-evaluation, May 2026)

The following sub-issues all proposed surface-form detection that pre-empts the wrapper's context-aware judgment. Each was closed as not-planned with issue-specific rationale. Common failure modes:

• Duplicates wrapper logic. The wrapper + skill already handle these cases when given conversation context.
• False positives erode trust. Keyword/regex detection of "vagueness" / "scope creep" / "contradiction" / "destructive intent" produces false fires on legitimate prompts.
• Wrong layer. Several proposed prompt-text safety checks duplicate Claude Code's tool-layer enforcement (which is enforceable, not advisory).
• Anthropic's own guidance says vagueness isn't always bad — exploratory prompts can be valuable.

Relevant new Claude Code features (Jan–May 2026)

Still informative for the surviving roadmap:

Design constraints (binding)

• Rarely intervene — most prompts pass through unchanged
• Trust user intent — only ask when genuinely unclear
• Bypass prefixes preserved — *, /, #
• Hook stays minimal — runs on every prompt submission; no heavy imports or network calls
• Token budgets binding — see table above
• The wrapper + skill is sufficient for clarity detection. Don't add parallel detection mechanisms in the hook.

References

• Claude Code changelog: https://code.claude.com/docs/en/changelog.md
• Hook reference: https://code.claude.com/docs/en/hooks
• Best practices: https://code.claude.com/docs/en/best-practices
• Anthropic prompting best practices: https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices
• Prompt defects taxonomy (arxiv): https://arxiv.org/html/2509.14404v1
• Upstream feature request: Feature Request: Add updatedPrompt support to UserPromptSubmit hook anthropics/claude-code#27365