better-prompt

name	better-prompt
description	Apply a research-first, plan-review-implement-verify methodology to complex, vague, or open-ended technical requests. Triggers on verbs like "optimize", "configure", "tune", "refactor", "clean up", "ship-ready", and requests for the "best / ideal / perfect / 最佳 / 最优 / 完美 / 生产级" state of a system — vague directives without success criteria, performance targets with open paths ("LCP from 3s to 1s"), production-readiness assessments, or any task where the user expects Claude to figure out the right approach. Especially valuable when the user lacks deep technical background. Works at conversation start or mid-conversation (extracts prior context). Skip when (a) one-sentence diff or direct lookup, or (b) localized snippet with clear in/out; if the user prioritizes speed ("just do it"), apply a Light variant instead of skipping. Bias toward triggering when non-trivial; over-rigor wastes a little time, jumping to action on a real task produces wrong answers.
license	MIT
compatibility	Claude Code (CLI). Uses Read, Edit, Bash, Agent, and WebSearch/WebFetch when available. Optionally leverages context7 MCP for library docs and the Explore agent type for parallel context-gathering — both degrade gracefully if absent.

Better Prompt — Research-First Task Methodology

Why this skill exists

Vague prompts → generic answers. Users say "optimize my X" without specifying the environment, the success criterion, or the boundary. Default behavior jumps to generic best practices that don't fit their situation. The result is shallow, sometimes wrong, hard to verify.

This skill imposes a methodology that works:

Triage → Context → Research → Plan + self-review → Implement → Verify

The cost is a few minutes of upfront discipline. The benefit is solving the user's actual problem instead of producing a plausible-looking answer. The methodology is grounded in three pieces of well-known agent research — Plan-and-Solve (plan before acting beats raw chain-of-thought), Self-Refine (an LLM critiquing its own output and revising consistently improves quality), and Chain-of-Verification (drafting explicit verification questions catches errors that ad-hoc checking misses).

Step 0 — Triage: pick the right depth

Before anything else, decide which branch fits the request. Wrong branch is the most common failure mode: heavy methodology on a one-line fix wastes time; light methodology on an open-ended task produces bad answers.

Skip the skill entirely (just answer directly) when:

• The diff is describable in one sentence ("rename foo to bar in file.ts")
• The request is a direct lookup, explanation, or knowledge question ("what does this error mean", "what's the difference between X and Y")
• The optimization scope is a single localized snippet with clear input/output ("optimize this 20-line function", "rewrite this SQL")
• The user already supplied a complete spec / plan / linked issue
• The request is conversational, not a task

Light branch (mini version — read state + brief plan + simple verify, minimal asking) when:

• A single-file change with low blast radius
• A small, scoped fix where the goal is clear (e.g., "fix all lint errors")
• The user explicitly prioritizes speed over rigor ("just do it", "quick", "no need to plan heavily", "别问太多问题") — still apply Light, don't skip: the user wants the result fast, not wrong

Full branch (the whole methodology, with markdown artifacts) when:

• Multi-file or multi-system change
• Vague verbs without scope ("optimize", "refactor", "clean up", "tune", "完美", "最佳")
• Performance targets with open optimization paths ("LCP under 1.5s", "API latency under 200ms")
• Production-readiness assessments ("can we ship this?", "is this ready for production?")
• Unresolved nouns ("the system", "our config", "the network")
• Success criteria absent or implicit
• Touches production / infra / shared state
• The user signals they want a thorough job

When uncertain, go one level lighter than your instinct — but if the result feels wrong, escalate. Under-processing produces bad answers; over-processing wastes time.

Respecting "don't ask" directives. When the user signals they want speed, that's a directive about interaction style, not a license to skip the methodology. Apply Light: read state silently, infer the goal, do the work, verify. Surface assumptions in the result ("I assumed X — let me know if wrong"), so the user can correct cheaply after the fact instead of being interrupted before.

Follow-up turns within an ongoing Full task. Once you've established the Full context for a task, individual follow-up questions can use a lighter touch. "How do I revert change 3?" inside an ongoing Full task is a Skip — just answer. Don't drag every follow-up turn through the full methodology; that's the methodology becoming a ritual. Re-engage the heavier process only when the follow-up itself reopens a Phase 1 or Phase 3 decision.

Phase 1 — Establish complete context

Three things to nail down before doing anything else:

1a. Background — the user's environment

Map out what's relevant to this task:

• Stack and infra: language, framework, services, OS, network, deployment
• State: current config, current data, current behavior, recent changes
• Constraints: region, performance, cost, compliance, time pressure
• Prior decisions: what's been chosen, what's been rejected, why

Where to get it, in order of preference:

1. Read it. If a config file would answer the question, read it. Never ask the user for what you can read.
2. Extract from prior conversation (if mid-conversation — see Mid-conversation extraction below)
3. Ask the user only for things genuinely not in any artifact (intent, organizational context, things outside the workspace)

For a substantial task, delegate the context-gathering scan to a read-only search subagent — it keeps the main context lean and runs in parallel with your own work. In Claude Code, use the built-in Explore agent type if available; otherwise spawn a general-purpose agent constrained to read-only tools. Spawn it before reading files yourself if the search surface is large.

1b. Resources — what you can actually do

State explicitly:

• Files / configs you can read
• Files / configs you can modify
• Tools, MCPs, APIs at your disposal (web search, context7 for library docs, etc.)
• Things outside your control — these are boundaries, not failures

Naming the scope prevents misalignment. Users often assume you can do more or less than you actually can.

1c. Specific need — what does the user actually want?

"Optimize" is too vague. Pin down:

• Optimize for what dimension? (latency / throughput / cost / reliability / maintainability / security / UX)
• What's the success criterion? Make it measurable if possible.
• What's in scope vs. out of scope?

If the answer is material to design AND not inferable: ask (see Interaction Model). If inferable: state the inference explicitly so the user can cheaply correct ("I'm interpreting 'faster' as LCP under 2 seconds — say so if a different metric matters more").

Phase 2 — Research

2a. Read current state

Before proposing anything, inspect what's there:

• Read the relevant configs, code, schemas, docs
• For full-branch tasks: write findings to current-state.md in the working directory — gives you and the user a durable record
• For light-branch tasks: hold findings in conversation context

Artifact hygiene: current-state.md / plan.md / research.md are scratch artifacts. If a file with that name already exists and isn't from this task, use a task-prefixed name instead of overwriting. Don't commit these files unless the user asks.

Do not skip this. "I'll just fix it" without reading first is the single biggest cause of broken changes.

2b. Research best practices for the user's specific situation

Generic best practices often don't apply. Use the right tool, in this order of preference:

• A current-docs MCP (e.g., the context7 MCP if installed) for library / framework / SDK / CLI documentation — more current and accurate than the model's recall
• WebSearch / WebFetch for recent posts, authoritative blogs, known gotchas (look for material from the last 12 months when possible)
• The model's own knowledge — last resort, since it may be stale or version-specific

Watch for:

• Generic advice ≠ situational advice — "always do X" is rarely right for this user
• Old answers (a 2020 blog post about a 2026 tool is often wrong)
• AI-generated content masquerading as authority — cross-check

For full-branch tasks, the research output goes into current-state.md (or a separate research.md).

Phase 3 — Plan + self-review

3a. Draft the plan

Write the proposed changes. For each change, answer:

Field	What it says
What	The concrete change (file, line, value, command)
Why	The reason this change matters for this user's situation, not generically
Expected effect	What you expect to be different after
Risk	What could go wrong, and how likely
Rollback	How to undo it if it goes wrong

If any field is hard to fill in, the change isn't well thought through.

Scale the depth per change. A high-risk irreversible change deserves a paragraph per field. A trivial low-risk change (e.g., rename a scheduled task time) can use one-line Risk and Rollback ("极低 / 改回原时间"). The point is to think through each field, not pad the document.

Rank by ROI. When a plan has multiple changes, sort or annotate them by expected impact × effort. Users often want "if I only do one thing, which one?" — answer that in the plan. Put zero-risk high-value items first; expensive or risky items later.

Non-expert user — add a plain-language summary. If the user has indicated limited technical background (or the description triggered partly because of that), prepend the plan with a 1-2 paragraph plain-language summary: "Here's what I want to do, in 3 buckets: things I can do for free that should help right away, things that need you to spend money or time, and things to keep an eye on." The detailed change list still follows for accountability.

• For full-branch tasks: write the plan to plan.md in the working directory
• For light-branch tasks: structured list in conversation
• If the host has a native plan-approval mechanism active (e.g. Claude Code plan mode), present the plan through it instead of duplicating the approval step — plan.md then serves as the durable record, not a second gate

3b. Self-review along named lenses

Generic "review the plan" rarely catches issues. Walk through the plan applying each of these lenses explicitly:

1. Specificity — Is each change tied to this user's situation, or is it a generic best practice that may not apply? Replace generics with specifics or drop them.
2. Interactions — Are there changes that interact (ordering, conflicting effects, shared state)? Sequence them correctly.
3. Edge cases — What inputs / states / failures aren't handled? Add them or note explicitly that they're out of scope.
4. Reversibility — Is each change reversible cheaply? Is anything destructive? If so, plan the rollback.
5. Verification feasibility — Can each change actually be verified? If not, that's a design problem — adjust the plan to make verification possible.

If any lens surfaces an issue → fix the plan → re-walk the lenses. Loop until clean.

Skip lenses that are obviously N/A. For a plan with 8 changes, walking 5 lenses × 8 changes = 40 judgments. Many are obvious (Lens 4 on a config-tweak change: "trivially reversible, done"). State the obvious cases briefly, focus the work on the non-obvious ones. The point of the lenses is to catch issues, not to perform a ritual.

Partial vs. full re-lens after a fix. If a lens reveals a problem in one change, fix that change and re-lens that change plus its dependencies. If a lens reveals a problem in the root assumption (e.g., "the entire plan assumes the user has a Plex Pass and they don't"), re-lens the whole plan. Don't waste effort re-lensing unaffected changes, but don't be stingy when the root has shifted.

For high-stakes plans (production, irreversible, multi-system), spawn a fresh subagent reviewer — it has no commitment to your draft and catches issues you missed. Use whatever review-oriented subagent type is available in the host environment, or fall back to general-purpose with a review-focused prompt. Give it only the plan + the user's situation, not your own justifications — its value is independent skepticism.

Sign-off rule: show the plan to the user and get explicit go-ahead before executing when any of the following holds:

• Touches production or a live system the user depends on (including home infrastructure such as a NAS, router, or Home Assistant)
• Costs money or requires hardware purchases
• Has irreversible steps without a backup
• The user has explicitly asked for oversight
• The user has signaled they lack technical background and is trusting Claude to judge — surfacing the plan lets them confirm the priorities even if they can't audit every line

Otherwise, proceed. In a non-interactive session (see Interaction model), sign-off-gated changes are never executed — deliver them as a pending-approval list instead.

Phase 4 — Implement and verify

4a. Implement

Follow the validated plan. If you discover during execution that the plan was wrong, stop, update the plan, re-review — don't improvise.

Status updates: brief, factual, only when something notable happens. Silence and over-narration are both bad.

4b. Verify — draft verification questions, then answer them

Don't just run the change and call it done. Draft the verification questions first, then answer each one with evidence:

1. Structural — "Is the change actually in place?" → read back the file / config / state
2. Behavioral — "Does the intended behavior actually work?" → run the test, hit the endpoint, send a real request, observe the metric
3. Adjacent — "Is anything nearby broken that was working before?" → run existing tests, sanity-check related flows
4. Success criteria — "Are the Phase 1c criteria met?" → measure or demonstrate each one

Each question gets an answer with evidence. "Tests pass" is fine if you ran them; "Looks right to me" is not.

Verification ≠ tool call succeeded. A tool call can return 0 and the system can still be broken. Test behavior, not syntax.

For UI / frontend work specifically: structural + behavioral verification requires a real browser. Type-check passing is not "verified". If you can't drive a browser, say so explicitly rather than claiming success.

Async verification. Some verifications need wall-clock time — a scheduled task that runs once a week, a 24-hour stability check, a backup that runs tonight. Don't fake-claim success. Instead: mark those checks as PENDING (verifies on next run @ <time>) in the plan's status table, tell the user when to expect closure, and remind them in your final report. If the task is time-critical, offer a proxy check (e.g., manually trigger the scheduled task once to confirm it runs cleanly).

When verification surfaces problems → don't retry harder, loop back to Phase 3 with the new evidence.

Interaction model — when to ask, when to proceed

Default to autonomous. This skill is about removing the user's burden, not adding it.

Proceed without asking when:

• The user's message has enough to start
• Missing pieces can be read from the workspace
• The user has explicitly delegated ("you decide", "don't interrupt unnecessarily")
• Prior turns (mid-conversation) supply the missing context
• You can state the assumption explicitly and let the user correct cheaply

Ask the user only when:

• A design choice has material trade-offs that the user should decide (not you)
• The next action is destructive or hard to reverse
• The request rests on a wrong assumption you discovered during research
• The plan is high-stakes (see sign-off rule)

Non-interactive sessions (headless claude -p, CI, scheduled automation — no human will answer): never block on a question. AskUserQuestion may be unavailable or time out there. Convert every would-be question into an explicit assumption recorded in the plan. Sign-off-gated changes are not executed: do the reversible, low-stakes work, and deliver the gated items as a clearly-marked "awaiting approval" list with the exact commands/diffs ready to apply.

How to ask — strict rules:

1. Default cap: 3 questions per turn. More and users disengage. If you have more questions than that, prioritize: tier them P0 (blocks any meaningful work) and P1 (would refine but you can pick a default). Ask the P0s now, defer P1s as inferred assumptions stated in the plan. The AskUserQuestion tool hard-caps one call at 4 questions with 2-4 options each — never plan a bigger batch; anything beyond 4 must be deferred, not chained into a second prompt.
2. Use AskUserQuestion with multiple-choice options — not free-text questions. Free-text invites long answers and back-and-forth. Don't add an explicit "Other / something else" option — the tool renders a free-text "Other" automatically, so a hand-written one wastes one of the 2-4 option slots. In a host without that tool, ask the same multiple-choice questions as a compact numbered list in plain text.
3. Include a "Recommended" option as the first choice in each question, labeled with (Recommended). This lets the user one-click confirm your best guess. The Recommended option should minimize the user's effort, not yours. For a non-expert user, "paste this output here" usually beats "give me SSH access" even if SSH would be faster for you. Bias toward what the user can actually do in 10 seconds.
4. State your current understanding first so the user corrects efficiently rather than re-explaining.
5. Pre-commit to defaults if no reply. State each assumption explicitly in the plan; user can override cheaply later.

Good ask pattern:

Two things to confirm before I tune the OpenClash setup: [One AskUserQuestion call carrying both questions — Q1 "Traffic priority": 1) Work tools only (Recommended), 2) Work + streaming, 3) Add gaming priority Q2 "Tuning bias": 1) Stability over speed (Recommended), 2) Speed over stability]

If both defaults are fine, just say "go".

Batch all questions of a turn into one AskUserQuestion call (the questions array holds up to 4) — two back-to-back calls means two interruptions, which is exactly the drip-feed anti-pattern.

Bad asks to avoid:

• "What's your use case?" (free-text, vague, will drip-feed follow-ups)
• Asking what a config file would tell you
• Asking the same thing the user already told you 5 turns ago

Mid-conversation context extraction

If this skill triggers mid-conversation, do not restart. Extract from prior turns:

• Environment / stack — what's been established about the setup
• Goals and constraints — original goal, deadlines, anti-goals
• Decisions already made — approaches chosen and rejected, trade-offs accepted
• Execution state — what's done, what's tested, what's known to work or be broken
• User signals — corrections, preferences, "just do it" vs. "ask first" calibration

Then summarize in 2-3 sentences for the user so they can correct drift:

Based on the conversation so far: bypass-router + Mesh setup, we tuned OpenClash and verified Google/OpenAI access. You're now asking whether the whole stack is optimal. Sound right?

If the current request contradicts a prior decision, surface it explicitly rather than silently picking one. Silent drift is one of the most common ways agents produce subtly wrong results in long conversations.

If important prior context appears to have been compressed away (the user references something you don't remember), don't pretend — either ask for a quick recap, or re-read any artifacts you wrote earlier.

See references/context-extraction.md for more patterns.

Language

Match the user's language for everything user-facing — summaries, questions, status updates, and the content of plan / current-state markdown files. File names, code identifiers, and shell commands stay in English regardless of the user's language.

Anti-patterns to avoid

• Skipping Phase 1 because "I know what they mean" → generic, ill-fitting answers
• Asking what you could read → wastes the user's attention and signals you're not using your tools
• Drip-feeding questions one per turn → batch everything in one turn
• Free-text questions when a multiple-choice with a Recommended default would do
• Generic self-review instead of the named lenses → catches nothing
• "Tool call succeeded" = "verified" → false confidence
• Heavy methodology on a one-line fix → annoying and wasteful — use the Skip / Light branches
• Improvising mid-execution when the plan turns out wrong → stop, re-plan, don't drift
• Ignoring prior conversation when triggered mid-stream → re-asks what's known, signals inattention
• Treating the four phases as a strict pipeline → they're a loop; new evidence from any phase can send you back

Reference files

Read these when the main file doesn't give enough guidance — they're not required for every invocation:

• references/methodology-deep-dive.md — fuller treatment of each phase with edge cases and decision rules
• references/examples.md — before/after transformations across domains (network, code, data, frontend)
• references/context-extraction.md — patterns for extracting from prior turns, handling drift and missing context