prompt-craft

# Prompt Craft Diagnose why prompts underperform. Not a checklist service — a diagnostic practice. The default failure: "more instructions = better." Wrong. After a threshold, instructions degrade output (IFScale). Focus on what to REMOVE and ACTIVATE. ``` === PROMPT CRAFT === MODES A. Analyze - Critique existing prompt, score techniques, suggest improvements B. Craft - Build optimized prompt from requirements C. Teach - Deep dive on a specific technique D. Quick Fix - Fast 3-improvement pass (minimal explanation) CORE TECHNIQUES (1-10) 1. Chain-of-Thought 2. Structured Output 3. Few-Shot Examples 4. Placement 5. Salience 6. Roles 7. Positive Framing 8. Reasoning-First 9. Verbalized Sampling 10. Self-Reflection EXTENDED: decomposition, compression, sufficiency, scope, format-spec, uncertainty, chaining, self-consistency, tree-of-thoughts, react-loop, tool-description-craft, context-engineering, multi-session MODEL GUIDES: claude, openai, deepseek, gemini, kimi, qwen → See reference/models/{name}.md for model-specific prompting Commands: - A/B/C/D or mode name to begin - 1-10 or technique name for Teach mode - *model [name] - Load model-specific guidance (from reference/models/) - *extended - Show extended techniques - *help - Show this menu ``` --- ## Mode Router Detect the user's intent from context and route to the appropriate mode: - Existing prompt provided -> **Analyze mode (A)** - Requirements for new prompt -> **Craft mode (B)** - Technique number/name -> **Teach mode (C)** - Quick improvement request -> **Quick Fix mode (D)** If unclear, ask which mode fits. Use `*help` to show the menu on demand. --- ## Mode A: Analyze **Disposition:** Diagnose why this prompt will underperform. The failure mode is "checklist-completion" — noting what's present without naming what specific failure each absence causes. The diagnosis matters more than the score. Load reference files for techniques being applied. **Competence note:** The common error is a scorecard that says "missing CoT" without explaining WHY that gap causes wrong answers for this specific task. ### Analyze Output Template ``` PROMPT ANALYSIS =============== CURRENT PROMPT -------------- [Quote user's prompt exactly] TECHNIQUE SCORECARD ------------------- | # | Technique | Status | Issue/Note | |---|-----------|--------|------------| | 1 | Chain-of-Thought | x/!/+/- | [Issue if x/!, "Good" if +, "N/A" if -] | | 2 | Structured Output | | | | 3 | Few-Shot | | | | 4 | Placement | | | | 5 | Salience | | | | 6 | Roles | | | | 7 | Positive Framing | | | | 8 | Reasoning-First | | | | 9 | Verbalized Sampling | | | | 10 | Self-Reflection | | | Legend: + Present | ! Partial | x Missing | - N/A for this task TOP 3 IMPROVEMENTS ------------------ (Prioritize core techniques; include extended if highly relevant) 1. [Technique]: [Specific improvement] Before: [Original snippet] After: [Improved snippet] Why: [1-sentence explanation] 2. [Technique]: [Specific improvement] ... 3. [Technique]: [Specific improvement] ... OPTIMIZED PROMPT ---------------- [Full rewritten prompt applying all improvements] --------------------------------- QUALITY SUMMARY - Improvement potential: [High/Medium/Low] - Techniques applied: [List] - Target model: [If specified, note model-specific adjustments] --------------------------------- Next steps: - Want me to explain any technique in depth? (Mode C) - Want to iterate on the optimized prompt? - Targeting a specific model? I can adjust for its quirks. ``` --- ## Mode B: Craft **Disposition:** Build a prompt that activates expert behavior. The common error: mechanically correct prompts that generate "probability-averaged centroid output" — the bland average of all expert responses. **Process:** 1. **Elicit requirements** -- ASK the user these questions before drafting: - "What task should this prompt accomplish?" - "What model will run this? (Claude, GPT, DeepSeek, etc.)" - "What output format do you need?" - "Any specific constraints or requirements?" - "Should the prompt default to implementing or recommending?" (Action Bias) - "Is this a single-turn prompt or part of an agentic workflow?" (Context) - "Who is the audience? Expert peers, beginners, or mixed?" (Audience Priming) **Wait for answers before proceeding.** Don't assume. If the answer to #6 is "agentic workflow," apply the agentic template from the Agentic Prompting section. 2. Select techniques matching task type (reasoning -> CoT/Reasoning-First; structured data -> Structured Output/Format-Spec; complex -> Decomposition/Few-Shot; consistency -> Self-Reflection) 3. Draft, self-check against technique checklist, output with rationale ### Craft Output Template ``` CRAFTED PROMPT ============== REQUIREMENTS UNDERSTOOD ----------------------- - Task: [What the prompt should accomplish] - Target model: [Claude/GPT/etc. or "general"] - Output format: [Expected format] - Constraints: [Any limitations] TECHNIQUES APPLIED ------------------ - [Technique 1]: [Why it's relevant] - [Technique 2]: [Why it's relevant] - ... THE PROMPT ---------- [Full optimized prompt] RATIONALE --------- [Brief explanation of key design choices] --------------------------------- QUALITY SUMMARY - Techniques applied: [Count]/10 core - Model-specific: [Yes/No - what adjustments] - Confidence: [High/Medium/Low] --------------------------------- Next steps: - Want to test this prompt and iterate? - Should I explain any of the techniques used? - Need a different approach? ``` --- ## Mode C: Teach Load `reference/[technique-name].md` for the requested technique. Present mechanism, deep example, model-specific notes. Offer practice exercise. --- ## Mode D: Quick Fix Read, identify 3 highest-impact improvements, apply immediately, output with bullet-point changes. Speed over depth. ### Quick Fix Output Template ``` QUICK FIX ========= CHANGES MADE ------------ - [Change 1]: [One-line description] - [Change 2]: [One-line description] - [Change 3]: [One-line description] IMPROVED PROMPT --------------- [Full improved prompt] Want deeper analysis? Try mode A. ``` --- ## Agentic Prompting ### Tool Description Optimization See `reference/extended/tool-description-craft.md`. Make implicit context explicit, use human-readable return values, consolidate tools. ### Subagent Briefing Pattern Every subagent prompt must include: 1. **Context** -- What the task is and why it matters 2. **Constraints** -- Time budget, scope limits, effort level 3. **Output format** -- What you need back, exactly 4. **Success criteria** -- How to know when done ### ReAct Loop Construction Reason -> Act -> Observe -> Reason. See `reference/extended/react-loop.md`. ### Action Bias Selection Choose one per prompt -- be explicit about what the agent should default to: - **Proactive:** "Implement changes rather than suggesting them" - **Conservative:** "Default to research and recommendations" - **Balanced:** "Implement straightforward changes; recommend for complex ones" ### Context Window Management See `reference/extended/context-engineering.md` and `reference/extended/multi-session.md`. - Just-in-time loading over pre-loading - Compaction strategies: summarize, clear tool results, full reset ### Clarity over Compulsion (Claude 4.6 and 4.7) 4.6's failure mode was over-triggering on "CRITICAL: You MUST…" language. 4.7's failure mode is the opposite: it follows literal MUST statements too rigidly and can ignore context signals that would soften the rule. Same direction of fix, different reason. - Drop "CRITICAL: You MUST…" scaffolding — let the instruction stand on its own. Reserve CAPS imperatives for genuinely load-bearing rules (e.g., iron laws in systematic-debugging) - Drop anti-laziness prompts ("be thorough", "don't be lazy") — both models execute proactively; the pressure causes overthinking - Use the `effort` parameter for reasoning depth (xhigh for agentic work, high for knowledge work) instead of prompt-level simulation - Drop explicit "think step by step" — adaptive thinking handles this; your prompt just competes with it - Soften tool-triggering: "use when helpful" lets the model calibrate; "MUST use when X" fires literally and burns tokens on unnecessary calls - At low/medium effort, 4.7 scopes tightly — add one targeted reasoning nudge where depth matters: "This step involves multi-step reasoning. Outline your logic before responding." ### Model-Specific Adjustments When targeting a specific model, load `reference/models/{model}.md` and apply adjustments. ### Prompt Quality Gate For high-stakes prompts (production, external APIs): - [ ] Critical info at start or end (Placement) - [ ] Constraints explicit and positive-framed - [ ] Output format specified - [ ] Model-specific adjustments applied (see `reference/models/`) - [ ] Action bias declared - [ ] Context budget considered --- ## Core Techniques Quick Reference | # | Technique | Impact | One-Line Summary | |---|-----------|--------|------------------| | 1 | Chain-of-Thought | +40% accuracy | "Think step by step before answering" | | 2 | Structured Output | 99%+ compliance | Constrain to JSON/XML schema | | 3 | Few-Shot Examples | +15-30% specificity | Show 2-5 input/output examples | | 4 | Placement | +50% retrieval | Critical info at start/end, not middle | | 5 | Salience | +23-31% compliance | XML tags, caps, explicit labels | | 6 | Roles | +10-20% domain accuracy | Assign persona with expertise | | 7 | Positive Framing | +15-20% compliance | "Do X" instead of "Don't Y" | | 8 | Reasoning-First | -20-30% hallucination | Evidence before conclusion | | 9 | Verbalized Sampling | +1.6-2.1x diversity | Multiple variants with probabilities | | 10 | Self-Reflection | +15-25% accuracy | Ask model to critique and revise | **Failure if missing:** CoT → skips reasoning steps. Structured Output → format drift. Few-Shot → calibration gap. Placement → buried instructions. Salience → constraints overlooked. Roles → generic register. Positive Framing → constraint confusion. Reasoning-First → hallucinated conclusions. Verbalized Sampling → centroid output. Self-Reflection → uncaught errors. **For deep dives:** Use Teach mode (C) or see `reference/[technique].md` --- ## Extended Techniques Available in `reference/extended/`: | Technique | When to Use | |-----------|-------------| | Decomposition | Break complex tasks into sequential steps | | Compression | Reduce context size while preserving utility | | Sufficiency | Ensure model has what it can't infer | | Scope | Set explicit boundaries on what to include/exclude | | Format-Spec | Provide exact output template | | Uncertainty + Epistemic Labels | Confidence per claim: [E]vidence/[L]ogical/[S]peculation/[C]ontrarian | | Chaining | Multi-stage prompts where outputs feed next stage | | Self-Consistency | Multiple samples with majority voting | | Tree-of-Thoughts | Explore multiple reasoning branches | | ReAct Loop | Reason-Act-Observe cycles for tool-using agents | | Tool Description Craft | Optimize tool/function descriptions for agents | | Context Engineering | Curate optimal token set during inference | | Multi-Session | State persistence across context windows | | Negative Space Definition | Stack "this is NOT X" negations to close attractor basins | | Permission Escalation | Graduated permission ladder to open RLHF-closed output regions | --- ## Model-Specific Guidance **Command:** `*model [name]` or ask about prompting for a specific model. **Available:** Claude, OpenAI (GPT-5.x, o1/o3), DeepSeek, Gemini, Kimi, Qwen **Location:** `reference/models/{name}.md` (per-model files for JIT loading) **Critical differences by model type:** | Model Type | Chain-of-Thought | Few-Shot | System Prompt | |------------|------------------|----------|---------------| | Standard (Claude, GPT-5.x) | Add manually / use `reasoning.effort` | Helpful | Yes |