@bastani/atomic 0.9.10 → 0.9.11-alpha.10

package/dist/builtin/workflows/skills/prompt-engineer/references/advanced_patterns.md

@@ -1,271 +1,115 @@
 # Advanced Prompting Patterns
 
-This document covers sophisticated prompt engineering techniques for complex tasks requiring structured reasoning, long-form content, or multi-step processing.
+Use these patterns for agents, tools, long context, multi-stage work, or model-specific tuning. Keep the common prompt portable; add a model-specific branch only when behavior or API controls differ.
 
-## Chain of Thought (CoT) Prompting
+## Model-Family Guidance
 
-### What is Chain of Thought?
+### GPT-5.6
 
-Chain of thought prompting encourages the model to break down complex problems systematically. Giving the model space to think can dramatically improve its performance on research, analysis, and problem-solving tasks.
+- Prefer a lean, outcome-first contract with explicit success criteria, dependencies, tool routes, and stopping conditions. GPT-5-class models follow contracts closely, so remove contradictions and repeated rules.
+- Set `text.verbosity` (`low`, `medium`, or `high`) for the request's default detail, then specify task-specific length and structure in the prompt. GPT-5.6 is concise by default; broad brevity instructions can make it too terse.
+- Preserve the existing reasoning effort as a baseline. Compare that level and one lower on representative evals; use `high`, `xhigh`, or `max` only when measured quality justifies the cost.
+- Expose only relevant tools. Parallelize independent reads, keep dependent calls sequential, and synthesize retrieved results before acting.
+- Prefer the Responses API for reasoning with tools. In Chat Completions, function tools require effective reasoning `none`; do not silently trade away required tools or reasoning.
 
-### Key Benefits
+OpenAI measured leaner system prompts improving internal coding-agent scores by roughly 10–15% while reducing total tokens 41–66% and cost 33–67%. Treat these as directional and validate on your workload.
 
-- **Accuracy**: Stepping through problems reduces errors, especially in math, logic, analysis, or generally complex tasks
-- **Coherence**: Structured reasoning produces more organized responses
-- **Debugging**: Observing the model's thought process reveals unclear prompt areas
+### Claude Opus 5
 
-### When to Use CoT
+- Give the complete specification up front and allow the model to execute. Remove generic self-review instructions: Opus 5 already self-corrects and repeated rechecks add cost without quality gain.
+- Start at `high` effort, compare `low` and `medium` where quality holds, and use `xhigh` for demanding coding or agentic work. Effort controls reasoning volume, cost, and latency; it does **not** reliably shorten visible responses.
+- Constrain user-facing and written deliverable length explicitly, for example: “Lead with the outcome; use at most 300 words and three short sections.”
+- Set a sparse progress cadence because Opus 5 produces frequent agentic updates: one sentence before the first tool call, then updates only for material findings or plan changes.
+- Limit task expansion and delegation. It can perform large end-to-end tasks, but may add work or spawn subagents unless the prompt defines scope and a delegation decision rule.
+- Keep adaptive thinking enabled when practical. Disabling it can leak tool calls as text or internal XML; at `xhigh` and `max`, disabling thinking returns a 400 error.
 
-Apply CoT for tasks that a human would need to think through, like:
+### Claude Fable 5
 
-- Complex math or logic problems
-- Multi-step analysis
-- Writing complex documents
-- Decisions with many factors
-- Planning specs
+- Remove legacy prescriptive scaffolding. Fable 5 follows brief instructions strongly, sustains long autonomous runs, and can overplan or overbuild when higher effort meets an ambiguous task.
+- Start at `high`; use `xhigh` for the hardest capability-sensitive work and `medium` or `low` for routine or interactive work. Adaptive thinking is required; manual extended-thinking budgets and disabling thinking are unsupported.
+- Add grounded progress reporting for long runs: each completion claim should point to a tool result from the current session, with failed, skipped, or unverified work labeled accurately. Anthropic reports this nearly eliminated fabricated status reports in its tests.
+- Define action boundaries and a no-promise stop rule. If an autonomous turn ends with an unexecuted plan or a request for permission already granted, continue with tools; stop only when complete or blocked on user-only input.
+- Avoid surfacing context-token countdowns because they can prompt early wrap-up.
+- Requests to echo, narrate, or explain internal reasoning as response text can trigger the `reasoning_extraction` refusal category and force fallback. Request cited evidence, conclusions, observed outputs, and validation receipts instead. If an application needs available reasoning visibility, consume API-provided summarized adaptive-thinking blocks rather than asking the model to generate a reconstruction.
 
-**Trade-off**: Increased output length may impact latency, so avoid using CoT for straightforward tasks.
+## Agentic Prompt Structure
 
-### Three CoT Techniques (Least to Most Complex)
-
-**1. Basic Prompt**
-Include "Think step-by-step" in your request. Simple but lacks specific guidance.
-
-**2. Guided Prompt**
-Outline specific steps for the model's reasoning process. Provides direction without structuring the output format, making answer extraction more difficult.
-
-**3. Structured Prompt**
-Use XML tags like `<thinking>` and `<answer>` to separate reasoning from final answers. This enables easy parsing of both thought process and conclusions.
-
-Example:
+Use this compact structure for autonomous or tool-using prompts:
 
+```text
+Role: Maintain the customer account workflow.
+Goal: Resolve the reported issue end to end.
+Success criteria:
+- decide eligibility from policy and account evidence
+- complete every authorized action
+- return completed_actions, customer_message, and blockers
+Constraints: Keep changes in scope; confirm external, destructive, or costly actions.
+Tools: Retrieve policy before deciding; use the account tool only after identity and eligibility are established.
+Output: Lead with the outcome; return the three required fields in valid JSON.
+Stop rules: Answer when required evidence and actions are complete. If one required fact is missing, ask for that smallest field. Stop on a permission or policy block and name it.
 ```
-Please analyze this problem and provide your reasoning.
-
-Put your step-by-step thinking in <thinking> tags.
-Put your final answer in <answer> tags.
-```
-
-### Critical Implementation Note
-
-**"Always have the model output its thinking. Without outputting its thought process, no thinking occurs!"** Visible reasoning is essential for CoT effectiveness.
-
----
 
-## Multishot Prompting
+State the current work layer—research, design, implementation, review, or external coordination—when crossing layers would change authorization. For long work, request a short initial preamble and sparse outcome-based progress updates, not routine tool-call narration.
 
-### Core Concept
+## Tool Routing
 
-Multishot prompting (also called few-shot prompting) involves providing a few well-crafted examples in your prompt to improve the model's output quality. This technique is particularly effective for tasks requiring structured outputs or adherence to specific formats.
+Tool descriptions should say what the tool does, when it applies, important return fields, side effects, permissions, and error behavior. Omit tools the agent cannot call or the task cannot need.
 
-### Key Benefits
+Write decision rules rather than aggressive triggers:
 
-- **Accuracy**: Examples reduce misinterpretation of instructions
-- **Consistency**: Examples enforce uniform structure and style
-- **Performance**: Well-chosen examples boost the model's ability to handle complex tasks
-
-### Crafting Effective Examples
-
-Examples should be:
-
-1. **Relevant** — Mirror your actual use case
-2. **Diverse** — Cover edge cases and vary sufficiently to avoid unintended pattern recognition
-3. **Clear** — Wrapped in `<example>` tags (multiple examples nested in `<examples>` tags)
-
-### Optimal Quantity
-
-Include 3-5 diverse, relevant examples. More examples = better performance, especially for complex tasks.
-
-### Template Structure
-
-```xml
-<examples>
-  <example>
-    <input>Sample input 1</input>
-    <output>Expected output 1</output>
-  </example>
-
-  <example>
-    <input>Sample input 2</input>
-    <output>Expected output 2</output>
-  </example>
-
-  <example>
-    <input>Sample input 3</input>
-    <output>Expected output 3</output>
-  </example>
-</examples>
+```text
+Check the recent local cache first. Fetch only when the required artifact is absent or stale.
+Before an account mutation, retrieve the governing policy and current account state.
+If a search is empty or suspiciously narrow, try one or two materially different queries before reporting no result.
 ```
 
----
-
-## Prompt Chaining
-
-### Core Concept
-
-Prompt chaining breaks complex tasks into smaller, sequential subtasks, with each step receiving the model's focused attention. This approach improves accuracy, clarity, and traceability compared to handling everything in a single prompt.
-
-### Key Benefits
-
-1. **Accuracy**: Each subtask gets full attention, reducing errors
-2. **Clarity**: Simpler instructions produce clearer outputs
-3. **Traceability**: Issues can be pinpointed and fixed in specific steps
-
-### When to Use Chaining
-
-Apply this technique for multi-step tasks involving:
-
-- Research synthesis and document analysis
-- Iterative content creation
-- Multiple transformations or citations
-- Tasks where the model might miss or mishandle steps
-
-### Core Techniques
-
-**1. Identify Subtasks**
-Break work into distinct, sequential steps with single, clear objectives.
-
-**2. Structure with XML**
-Use XML tags to pass outputs between prompts for clear handoffs between steps.
-
-**3. Single-Task Goals**
-Each subtask should focus on one objective to maintain clarity.
-
-**4. Iterate & Refine**
-Adjust subtasks based on the model's performance.
-
-### Workflow Examples
-
-- **Content pipelines**: Research → Outline → Draft → Edit → Format
-- **Data processing**: Extract → Transform → Analyze → Visualize
-- **Decision-making**: Gather info → List options → Analyze → Recommend
-- **Verification loops**: Generate → Review → Refine → Re-review
-- **Writing Specs**: Research → Plan → Implement (see detailed example below)
-
-### Complex Example: Spec Workflow
+Independent reads can run in parallel; calls whose parameters depend on earlier output stay sequential. Do not guess tool arguments. Define retries, fallback, and a stop condition. Validate the final user-visible result as well as tool success.
 
-This workflow represents a research-driven, AI-augmented software development process that emphasizes thorough planning and human oversight before implementation. It's designed to maximize quality and alignment by incorporating both AI assistance and human feedback at critical decision points.
+Use programmatic tool calling only for bounded deterministic reduction such as filtering, joining, ranking, deduplication, batching, or aggregation of large structured results. Prefer direct calls when each result changes the next decision, approval is required, or citations and semantic judgment must remain visible.
 
-**Phase 1: Research & Requirements**
+## Delegation Damping
 
-1. **Deep Research** — Begin with comprehensive research into the problem space: understanding user needs, exploring existing solutions, reviewing relevant technologies, and identifying constraints. Build a solid foundation of knowledge before defining what to build.
+Both Opus 5 and Fable 5 can over-delegate. For an orchestrator, use one decision rule:
 
-2. **Product Requirements Document (PRD)** — Distill research findings into a formal PRD that articulates the _what_ and _why_. Define the problem statement, target users, success metrics, user stories, and business objectives. Remain technology-agnostic, focusing purely on outcomes rather than implementation details.
-
-**Phase 2: AI-Assisted Design**
-
-3. **Brainstorm with Coding Agent** — This is where the workflow diverges from traditional approaches. Engineers collaborate with an AI coding agent to explore technical possibilities. This brainstorming session generates multiple implementation approaches, identifies potential challenges, discusses trade-offs, and leverages AI's knowledge of patterns and best practices. It's an exploratory phase that surfaces ideas that might not emerge from human-only brainstorming.
-
-4. **Technical Design/Spec** — Formalize the brainstorming output into a technical specification describing the _how_: architecture decisions, API designs, data models, technology stack choices, system components and their interactions, scalability considerations, and security/performance requirements. This becomes the engineering blueprint for implementation.
-
-**Phase 3: Human Validation Loop**
-
-5. **Human Feedback** — A critical checkpoint where experienced engineers, architects, or technical leads review the spec. This human oversight ensures the AI-assisted design is sound, catches edge cases or concerns, validates assumptions, and aligns the technical approach with organizational standards and long-term architecture. This phase acknowledges that AI assistance needs human verification.
-
-6. **Refined Technical Design/Spec** — Incorporate feedback to improve the specification. This might involve adjusting the architecture, adding clarifications, addressing edge cases, or reconsidering technology choices. The refined spec represents the agreed-upon technical approach with human validation baked in.
-
-**Phase 4: Execution**
-
-7. **Implementation Plan Doc** — Break down the refined spec into an actionable plan. Include task decomposition, effort estimates, dependency mapping, milestone definitions, and sprint/timeline planning. This bridges the gap between "what we'll build" and "how we'll actually execute it."
-
-8. **Implementation** — Engineers build the solution according to the plan and spec. The detailed planning from previous phases helps implementation proceed smoothly, though real-world discoveries may still require spec updates.
-
-9. **Testing** — The final validation phase ensures the implementation meets requirements through unit tests, integration tests, QA validation, performance testing, and verification against both the PRD objectives and technical spec requirements.
-
-**Key Characteristics:**
-
-- **AI-Augmented but Human-Validated**: The workflow embraces AI assistance for exploration and design while maintaining human oversight at critical junctures. This balances the speed and breadth of AI with the judgment and experience of senior engineers.
-
-- **Separation of Concerns**: The workflow clearly distinguishes between product requirements (PRD), technical design (Spec), and execution planning (Plan Doc). This separation ensures each artifact serves its specific purpose without conflation.
-
-- **Feedback Integration**: Unlike linear waterfall processes, this workflow explicitly includes a feedback loop after the initial spec, acknowledging that first drafts benefit from review and iteration.
-
-- **Research-Driven**: Starting with deep research rather than jumping straight to requirements ensures decisions are grounded in solid understanding of the problem space.
-
-This workflow is particularly well-suited for complex projects where upfront investment in planning pays dividends, teams working with AI coding tools, and organizations that want to leverage AI capabilities while maintaining human control over critical technical decisions.
-
-### Advanced: Self-Correction Chains
-
-Chain prompts so the model reviews its own work, catching errors and refining outputs—especially valuable for high-stakes tasks.
-
-### Optimization Tip
-
-For independent subtasks (like analyzing multiple documents), create separate prompts and run them in parallel for speed.
-
----
-
-## Long Context Tips
-
-### Key Techniques
+```text
+Delegate only work that is genuinely independent and too large to finish in a handful of tool calls. Do not use subagents merely to recheck your own work. Prefer one subagent over several and cap concurrency.
+```
 
-**1. Document Placement**
-Place lengthy documents (100K+ tokens) at the beginning of prompts rather than at the end. Queries at the end can improve response quality by up to 30% in tests, especially with complex, multi-document inputs.
+Keep orchestration asynchronous when the harness supports it, synthesize all returned work, and prevent agents from editing the same surface concurrently.
 
-**2. Structural Organization**
-Implement XML tags to organize multiple documents clearly. The recommended approach wraps each item in `<document>` tags containing `<document_content>` and `<source>` subtags, enabling better information retrieval.
+## Long Context
 
-Example:
+Place long documents and data near the top, with the instruction or query at the end. Anthropic measured up to about 30% better response quality from query-last ordering, especially for complex multi-document inputs.
 
 ```xml
 <documents>
-  <document>
-    <source>Report A</source>
-    <document_content>
-      Content here...
-    </document_content>
+  <document index="1">
+    <source>report-a.pdf</source>
+    <document_content>...</document_content>
   </document>
-
-  <document>
-    <source>Report B</source>
-    <document_content>
-      Content here...
-    </document_content>
+  <document index="2">
+    <source>report-b.csv</source>
+    <document_content>...</document_content>
   </document>
 </documents>
 
-Now analyze these documents and answer: [Your question here]
+Using only these documents, compare the reported risks. Cite the source beside each claim and state material conflicts or missing evidence. Return at most 500 words.
 ```
 
-**3. Quote Grounding**
-Request that the model extract relevant quotes from source materials before completing the primary task. This method helps the model navigate through extraneous content and focus on pertinent information.
-
-### Practical Example
-
-For medical diagnostics, request quotes from patient records placed in `<quotes>` tags, followed by diagnostic analysis in `<info>` tags. This two-step approach ensures responses remain anchored to specific document passages.
-
-### Context Window Advantage
-
-Modern language models support large context windows (100K–1M+ tokens), enabling complex, data-rich analysis across multiple documents simultaneously—making these organizational techniques particularly valuable for sophisticated tasks.
-
----
-
-## Extended Thinking Tips
-
-### Core Prompting Techniques
-
-**General Over Prescriptive Instructions**
-Rather than providing step-by-step guidance, models often perform better with high-level directives. Ask the model to "think about this thoroughly and in great detail" and "consider multiple approaches" rather than numbering specific steps it must follow.
+Quote grounding can focus retrieval in noisy inputs. Require only quotes that support consequential claims; excessive extraction can waste context and obscure synthesis.
 
-**Multishot Prompting**
-When you provide examples using XML tags like `<thinking>` or `<scratchpad>`, the model generalizes these patterns to its formal extended thinking process. This helps the model follow similar reasoning trajectories for new problems.
+## Adaptive Thinking and Effort
 
-**Instruction Following Enhancement**
-Extended thinking significantly improves how well the model follows instructions by allowing it to reason about them internally before executing them in responses. For complex instructions, breaking them into numbered steps that the model can methodically work through yields better results.
+Current Claude models allocate reasoning adaptively. Set effort first, then add a targeted prompt only if measured triggering remains wrong. `effort` is soft guidance; `max_tokens` is the hard per-request cap shared by reasoning and response text. Leave enough room for both.
 
-### Advanced Strategies
+Do not use visible chain-of-thought instructions or private-deliberation tags as a prompting technique. They are obsolete and can trigger Fable 5 safeguards. Ask for an answer supported by evidence, calculations, test results, or a concise decision rationale that does not solicit private deliberation.
 
-**Debugging and Steering**
-You can examine the model's thinking output to understand its logic, though this method isn't perfectly reliable. Importantly, you should not pass the model's thinking back as user input, as this degrades performance.
+In instruction prose, prefer “evaluate,” “assess,” or “consider” over “think,” particularly when Claude reasoning is disabled. Keep thinking configuration and effort stable within cache-sensitive conversations; changing effort invalidates Claude prompt-cache breakpoints.
 
-**Long-Form Output Optimization**
-For extensive content generation, explicitly request detailed outputs and increase both thinking budget and maximum token limits. For very long pieces (20,000+ words), request detailed outlines with paragraph-level word counts.
+## Prompt Chaining and Examples
 
-**Verification and Error Reduction**
-Prompt the model to verify its work with test cases before completion. For coding tasks, ask it to run through test scenarios within extended thinking itself.
+Chain prompts when distinct stages need separate context, permissions, models, or output contracts—not merely because a task has several steps. Each stage gets one goal, a validated handoff schema, and its own stop rule. Useful pipelines include Research → Outline → Draft → Edit and Extract → Transform → Analyze → Present.
 
-### Technical Considerations
+Run independent stages in parallel when they do not share mutable state. Use fresh-context review for genuinely high-risk artifacts when independence adds value; avoid automatic generate-review-repeat loops that duplicate current models' native self-correction.
 
-- Thinking tokens require a minimum budget of 1,024 tokens
-- Extended thinking functions optimally in English
-- With large context windows, thinking budgets can scale significantly higher
-- Traditional chain-of-thought prompting with XML tags works for smaller thinking requirements
+Few-shot examples remain useful for unusual formats, classifications, and edge cases. Keep 3–5 only when evals show value, use `<examples>` and `<example>` tags for mixed prompts, and ensure every example obeys the written contract.

package/dist/builtin/workflows/skills/prompt-engineer/references/core_prompting.md

@@ -1,137 +1,98 @@
-# Core Prompting Techniques
+# Core Prompting Fundamentals
 
-This document covers fundamental prompt engineering techniques that form the foundation of effective language model interactions.
+Use these fundamentals for any model family. Add structure only where it changes behavior.
 
-## Be Clear and Direct
+## Start With the Contract
 
-### Core Principle
+A prompt should let a colleague with minimal context identify the requested outcome and completion bar. For a complex task, begin with:
 
-Think of the model as "a brilliant but very new employee (with amnesia) who needs explicit instructions." The better you explain what you want, the better the model performs.
-
-### The Golden Rule
-
-Show your prompt to a colleague with minimal context and ask them to follow the instructions. If they're confused, the model likely will be too.
-
-### Key Techniques
-
-**1. Provide Context**
-
-- Explain what the results will be used for
-- Identify the intended audience
-- Describe where the task fits in your workflow
-- Define what successful completion looks like
-
-**2. Be Specific About Output**
-Explicitly state formatting requirements (e.g., "output only code and nothing else")
-
-**3. Use Sequential Instructions**
-Structure requests with numbered lists or bullet points to ensure the model follows your exact process.
-
-### Practical Examples
-
-**Anonymizing Feedback**
-
-- ❌ Vague: "Remove personal information"
-- ✅ Specific: "Replace all names with [NAME], email addresses with [EMAIL], phone numbers with [PHONE], and locations with [LOCATION]"
-
-**Marketing Emails**
-
-- ❌ Unclear: "Write a marketing email"
-- ✅ Detailed: "Write a marketing email to enterprise customers about our new security features. Tone: professional but approachable. Highlight: SSO, audit logs, and compliance certifications. Include a CTA to schedule a demo."
-
-**Incident Reports**
-
-- ❌ Generic: "Summarize this incident"
-- ✅ Terse: "Extract: timestamp, severity, affected systems, root cause, resolution. Output as bullet points only."
-
-### Key Insight
-
-Precision prevents hallucination and ensures the model delivers exactly what you need.
+```text
+Role: [function, domain, and audience]
+Goal: [user-visible outcome]
+Success criteria: [observable conditions for completion]
+Constraints: [safety, business, evidence, permission, scope]
+Tools: [available tools and context-dependent routing]
+Output: [format, sections, length, tone, validation]
+Stop rules: [when to answer, retry, ask, abstain, or stop]
+```
 
----
+Not every prompt needs every section. Preserve the outcome, success criteria, applicable constraints, required output shape, and stopping conditions; remove empty ceremony.
 
-## System Prompts and Role Prompting
+### Be clear and direct
 
-### Core Technique
+- Define ambiguous terms and concrete replacements. “Replace names with `[NAME]` and email addresses with `[EMAIL]`” is more actionable than “remove personal information.”
+- Identify the audience, purpose, and workflow context. A brief reason helps current Claude models generalize better than a list of prohibitions.
+- State exact fields, language, tone, length, and accepted values when downstream behavior depends on them.
+- Use ordered steps only when order or completeness is behavior-bearing. Do not prescribe a routine process merely to make the prompt look thorough.
 
-Use the `system` parameter to assign the model a specific professional identity. This transforms it from a general assistant into a specialized expert in a particular domain.
+### Define success and stopping
 
-### Key Benefits
+Success criteria should be observable: required fields exist, cited evidence supports claims, a requested action completed, or a named validation passed. Stop rules should distinguish:
 
-- **Enhanced accuracy** in complex domains like legal analysis or financial modeling
-- **Tailored tone** adjusted to match the assigned role's communication style
-- **Improved focus** keeping the model aligned with task-specific requirements
+- enough evidence exists to answer;
+- a meaningful fallback or retry remains;
+- required information is missing and the smallest clarifying question is needed;
+- policy, permission, or scope blocks further action.
 
-### Best Practice
+For autonomous work, distinguish safe local actions from external, destructive, costly, or scope-expanding actions. Repeating approval language can cause unnecessary pauses, so state the boundary once.
 
-"Use the `system` parameter to set the model's role. Put everything else, like task-specific instructions, in the `user` turn instead."
+## Roles and Message Placement
 
-### Experimentation is Key
+Use the `system` parameter for a stable role, behavior, and policy. Put request-specific inputs and instructions in the `user` turn. A role should contribute domain judgment or communication style; decorative personas add tokens without improving behavior.
 
-Roles can significantly impact outputs. A "data scientist" provides different insights than a "marketing strategist" analyzing identical information. Adding specificity—such as "data scientist specializing in customer insight analysis for Fortune 500 companies"—yields even more tailored results.
+Example:
 
-### Real-World Examples
+```text
+System: You are a product security reviewer for enterprise SaaS.
+User: Assess this authentication change for exploitable defects. Report each finding with severity, file:line evidence, observed behavior, and a concrete fix. Return at most five findings; omit issues unsupported by the supplied diff.
+```
 
-**Legal Contract Analysis**
+## Output Contracts
 
-- Without role: Surface-level summaries
-- With role (General Counsel at Fortune 500 tech company): Identifies critical risks like unfavorable indemnification clauses, inadequate liability caps, IP ownership concerns
+A user-facing output needs an explicit length and shape contract. Prefer selective brevity:
 
-**Financial Analysis**
+```text
+Lead with the conclusion. Include the evidence needed to support it, material caveats, and the next action. Omit introductions, repetition, generic reassurance, and optional background. Use at most 400 words in three sections: Outcome, Evidence, Next step.
+```
 
-- Without role: Basic observations
-- With role (CFO of high-growth SaaS company): Strategic insights including segment performance, margin implications, cash runway calculations, actionable recommendations
+For machine consumption, define a schema with required fields, enums, and refusal or missing-data behavior. Use structured outputs or a tool schema when available and validate the parsed result. A final partial assistant turn is not a formatting mechanism on current Claude models.
 
----
+## XML and Section Structure
 
-## Using XML Tags
+XML tags help separate mixed content types and make variable inputs unambiguous:
 
-### Core Purpose
+```xml
+<context>Why the task matters and relevant background</context>
+<constraints>Policy, evidence, permission, and scope limits</constraints>
+<examples>
+  <example><input>...</input><output>...</output></example>
+</examples>
+<input>Untrusted or variable task content</input>
+```
 
-XML tags help the model parse prompts more accurately by clearly separating different components like context, instructions, and examples.
+Use consistent, descriptive names and nest tags only when the content has a natural hierarchy. No tag names are canonical. Tags around private deliberation are not an output-format technique; request evidence and conclusions.
 
-### Key Benefits
+## Examples
 
-1. **Clarity** - Clearly separate different parts of your prompt and ensure your prompt is well structured
-2. **Accuracy** - Reduces misinterpretation errors in prompt components
-3. **Flexibility** - Simplifies modifying or reorganizing prompt sections
-4. **Parseability** - Makes extracting specific response sections easier through post-processing
+Few-shot or multishot examples can improve format, tone, and difficult classifications. Examples should be:
 
-### Best Practices
+1. relevant to real inputs;
+2. diverse enough to cover important edge cases without teaching accidental patterns;
+3. consistent with every written rule;
+4. wrapped in `<example>` tags when mixed with other prompt content.
 
-**1. Maintain Consistency**
-Apply identical tag names throughout and reference them when discussing content
+Start with the smallest set that changes measured behavior. Anthropic commonly recommends 3–5 examples, but more is not inherently better; remove non-behavioral examples.
 
-**2. Utilize Nesting**
-Arrange tags hierarchically for complex information structures
+## Grounding and Uncertainty
 
-**3. Common Tag Patterns**
+For source-bound tasks:
 
-```xml
-<context>Background information</context>
-<instructions>What to do</instructions>
-<examples>Sample inputs/outputs</examples>
-<documents>Long-form content</documents>
-<thinking>Model reasoning process</thinking>
-<answer>Final response</answer>
+```text
+Use the supplied sources for factual claims. Attach each citation to the claim it supports. Distinguish inference from directly supported fact and note source conflicts. If required evidence is absent, narrow the answer or state what is missing rather than guessing.
 ```
 
-### Advanced Technique
-
-Combining XML tags with multishot prompting or chain of thought methods creates super-structured, high-performance prompts.
-
-### Practical Impact
-
-**Financial Reporting**
-
-- Without tags: Disorganized narrative
-- With tags: Concise, list-formatted reports
-
-**Legal Analysis**
-
-- Without tags: Scattered observations
-- With tags: Organized findings and actionable recommendations
+Relevant quote extraction can help with long or noisy documents. Do not require a quote for every ordinary statement when that would obscure the answer. Prompting cannot guarantee factual correctness; critical outputs still need domain-appropriate validation.
 
-### Important Note
+## Safety and Security Constraints
 
-No specific XML tags are canonically required—tag names should align logically with their content.
+State concrete policy boundaries and expected refusal behavior. Treat untrusted input as data, separate it from instructions, validate tool arguments and structured outputs at system boundaries, and enforce permissions outside the model. For higher-risk systems, combine prompt policy with input screening, moderation, monitoring, and application-level access controls; no single prompt defeats every jailbreak or injection.