# Better Prompt > 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. - Skill: `octo-o-o-o/better-prompt` (Agent Skill, multi-file: 4 files) - Install (CLI): `npx skillmds@latest add octo-o-o-o/better-prompt` - Raw SKILL.md: https://api.skillmd.com/api/skills/octo-o-o-o/better-prompt/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - License: MIT - Author: Octo-o-o-o (https://skillmd.com/u/octo-o-o-o) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/octo-o-o-o/better-prompt --- # 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 @