@bastani/atomic 0.5.11 → 0.5.12-1

package/.agents/skills/prompt-engineer/SKILL.md

@@ -0,0 +1,263 @@
+---
+name: prompt-engineer
+description: Create, improve, or optimize prompts using best practices
+---
+
+# Prompt Engineering Skill
+
+This skill provides comprehensive guidance for creating effective prompts for language models using proven best practices. Use this skill whenever working on prompt design, optimization, or troubleshooting.
+
+## Overview
+
+Apply proven prompt engineering techniques to create high-quality, reliable prompts that produce consistent, accurate outputs while minimizing hallucinations and implementing appropriate security measures.
+
+## When to Use This Skill
+
+Trigger this skill when users request:
+
+- Help writing a prompt for a specific task
+- Improving an existing prompt that isn't performing well
+- Making outputs more consistent, accurate, or secure
+- Creating system prompts for specialized roles
+- Implementing specific techniques (chain-of-thought, multishot, XML tags)
+- Reducing hallucinations or errors in outputs
+- Debugging prompt performance issues
+
+## Workflow
+
+### Step 1: Understand Requirements
+
+Ask clarifying questions to understand:
+
+- **Task goal**: What should the prompt accomplish?
+- **Use case**: One-time use, API integration, or production system?
+- **Constraints**: Output format, length, style, tone requirements
+- **Quality needs**: Consistency, accuracy, security priorities
+- **Complexity**: Simple task or multi-step workflow?
+
+### Step 2: Identify Applicable Techniques
+
+Based on requirements, determine which techniques to apply:
+
+**Core techniques (for all prompts):**
+
+- Be clear and direct
+- Use XML tags for structure
+
+**Specialized techniques:**
+
+- **Role-specific expertise** → System prompts
+- **Complex reasoning** → Chain of thought
+- **Format consistency** → Multishot prompting
+- **Multi-step tasks** → Prompt chaining
+- **Long documents** → Long context tips
+- **Deep analysis** → Extended thinking
+- **Factual accuracy** → Hallucination reduction
+- **Output consistency** → Consistency techniques
+- **Security concerns** → Jailbreak mitigation
+
+### Step 3: Load Relevant References
+
+Read the appropriate reference file(s) based on techniques needed:
+
+**For basic prompt improvement:**
+
+```
+Read references/core_prompting.md
+```
+
+Covers: clarity, system prompts, XML tags
+
+**For complex tasks:**
+
+```
+Read references/advanced_patterns.md
+```
+
+Covers: chain of thought, multishot, chaining, long context, extended thinking
+
+**For specific quality issues:**
+
+```
+Read references/quality_improvement.md
+```
+
+Covers: hallucinations, consistency, security
+
+### Step 4: Design the Prompt
+
+Apply techniques from references to create the prompt structure:
+
+**Basic Template:**
+
+```
+[System prompt - optional, for role assignment]
+
+<context>
+Relevant background information
+</context>
+
+<instructions>
+Clear, specific task instructions
+Use numbered steps for multi-step tasks
+</instructions>
+
+<examples>
+  <example>
+    <input>Sample input</input>
+    <output>Expected output</output>
+  </example>
+  [2-4 more examples if using multishot]
+</examples>
+
+<output_format>
+Specify exact format (JSON, XML, markdown, etc.)
+</output_format>
+
+[Actual task/question]
+```
+
+**Key Design Principles:**
+
+1. **Clarity**: Be explicit and specific
+2. **Structure**: Use XML tags to organize
+3. **Examples**: Provide 3-5 concrete examples for complex formats
+4. **Context**: Give relevant background
+5. **Constraints**: Specify output requirements clearly
+
+### Step 5: Add Quality Controls
+
+Based on quality needs, add appropriate safeguards:
+
+**For factual accuracy:**
+
+- Grant permission to say "I don't know"
+- Request quote extraction before analysis
+- Require citations for claims
+- Limit to provided information sources
+
+**For consistency:**
+
+- Provide explicit format specifications
+- Use response prefilling
+- Include diverse examples
+- Consider prompt chaining
+
+**For security:**
+
+- Add harmlessness screening
+- Establish clear ethical boundaries
+- Implement input validation
+- Use layered protection
+
+### Step 6: Optimize and Test
+
+**Optimization checklist:**
+
+- [ ] Could someone with minimal context follow the instructions?
+- [ ] Are all terms and requirements clearly defined?
+- [ ] Is the desired output format explicitly specified?
+- [ ] Are examples diverse and relevant?
+- [ ] Are XML tags used consistently?
+- [ ] Is the prompt as concise as possible while remaining clear?
+
+**Testing approach:**
+
+- Run prompt multiple times with varied inputs
+- Check consistency across runs
+- Verify outputs match expected format
+- Test edge cases
+- Validate quality controls work
+
+### Step 7: Iterate Based on Results
+
+**Debugging process:**
+
+1. Identify failure points
+2. Review relevant reference material
+3. Apply appropriate techniques
+4. Test and measure improvement
+5. Repeat until satisfactory
+
+**Common Issues and Solutions:**
+
+| Issue                   | Solution                                    | Reference              |
+| ----------------------- | ------------------------------------------- | ---------------------- |
+| Inconsistent format     | Add examples, use prefilling                | quality_improvement.md |
+| Hallucinations          | Add uncertainty permission, quote grounding | quality_improvement.md |
+| Missing steps           | Break into subtasks, use chaining           | advanced_patterns.md   |
+| Wrong tone              | Add role to system prompt                   | core_prompting.md      |
+| Misunderstands task     | Add clarity, provide context                | core_prompting.md      |
+| Complex reasoning fails | Add chain of thought                        | advanced_patterns.md   |
+
+## Important Principles
+
+**Progressive Disclosure**
+Start with core techniques and add advanced patterns only when needed. Don't over-engineer simple prompts.
+
+**Documentation**
+When delivering prompts, explain which techniques were used and why. This helps users understand and maintain them.
+
+**Validation**
+Always validate critical outputs, especially for high-stakes applications. No prompting technique eliminates all errors.
+
+**Experimentation**
+Prompt engineering is iterative. Small changes can have significant impacts. Test variations and measure results.
+
+## Quick Reference Guide
+
+### Technique Selection Matrix
+
+| User Need                     | Primary Technique       | Reference File         |
+| ----------------------------- | ----------------------- | ---------------------- |
+| Better clarity                | Be clear and direct     | core_prompting.md      |
+| Domain expertise              | System prompts          | core_prompting.md      |
+| Organized structure           | XML tags                | core_prompting.md      |
+| Complex reasoning             | Chain of thought        | advanced_patterns.md   |
+| Format consistency            | Multishot prompting     | advanced_patterns.md   |
+| Multi-step process            | Prompt chaining         | advanced_patterns.md   |
+| Long documents (100K+ tokens) | Long context tips       | advanced_patterns.md   |
+| Deep analysis                 | Extended thinking       | advanced_patterns.md   |
+| Reduce false information      | Hallucination reduction | quality_improvement.md |
+| Consistent outputs            | Consistency techniques  | quality_improvement.md |
+| Security/safety               | Jailbreak mitigation    | quality_improvement.md |
+
+### When to Combine Techniques
+
+- **Structured analysis**: XML tags + Chain of thought
+- **Consistent formatting**: Multishot + Response prefilling
+- **Complex workflows**: Prompt chaining + XML tags
+- **Factual reports**: Quote grounding + Citation verification
+- **Production systems**: System prompts + Input validation + Consistency techniques
+
+## Resources
+
+This skill includes three comprehensive reference files:
+
+### references/core_prompting.md
+
+Essential techniques for all prompts:
+
+- Being clear and direct
+- System prompts and role assignment
+- Using XML tags effectively
+
+### references/advanced_patterns.md
+
+Sophisticated techniques for complex tasks:
+
+- Chain of thought prompting
+- Multishot prompting
+- Prompt chaining
+- Long context handling
+- Extended thinking
+
+### references/quality_improvement.md
+
+Techniques for specific quality issues:
+
+- Reducing hallucinations
+- Increasing consistency
+- Mitigating jailbreaks and prompt injections
+
+Load these files as needed based on the workflow steps above.

package/.agents/skills/prompt-engineer/references/advanced_patterns.md

@@ -0,0 +1,271 @@
+# Advanced Prompting Patterns
+
+This document covers sophisticated prompt engineering techniques for complex tasks requiring structured reasoning, long-form content, or multi-step processing.
+
+## Chain of Thought (CoT) Prompting
+
+### What is Chain of Thought?
+
+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.
+
+### Key Benefits
+
+- **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
+
+### When to Use CoT
+
+Apply CoT for tasks that a human would need to think through, like:
+
+- Complex math or logic problems
+- Multi-step analysis
+- Writing complex documents
+- Decisions with many factors
+- Planning specs
+
+**Trade-off**: Increased output length may impact latency, so avoid using CoT for straightforward tasks.
+
+### 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:
+
+```
+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
+
+### Core Concept
+
+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.
+
+### Key Benefits
+
+- **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>
+```
+
+---
+
+## 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
+
+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.
+
+**Phase 1: Research & Requirements**
+
+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.
+
+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
+
+**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.
+
+**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.
+
+Example:
+
+```xml
+<documents>
+  <document>
+    <source>Report A</source>
+    <document_content>
+      Content here...
+    </document_content>
+  </document>
+
+  <document>
+    <source>Report B</source>
+    <document_content>
+      Content here...
+    </document_content>
+  </document>
+</documents>
+
+Now analyze these documents and answer: [Your question here]
+```
+
+**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.
+
+**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.
+
+**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.
+
+### Advanced Strategies
+
+**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.
+
+**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.
+
+**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.
+
+### Technical Considerations
+
+- 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

package/.agents/skills/prompt-engineer/references/core_prompting.md

@@ -0,0 +1,137 @@
+# Core Prompting Techniques
+
+This document covers fundamental prompt engineering techniques that form the foundation of effective language model interactions.
+
+## Be Clear and Direct
+
+### Core Principle
+
+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.
+
+---
+
+## System Prompts and Role Prompting
+
+### Core Technique
+
+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.
+
+### Key Benefits
+
+- **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
+
+### Best Practice
+
+"Use the `system` parameter to set the model's role. Put everything else, like task-specific instructions, in the `user` turn instead."
+
+### Experimentation is Key
+
+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.
+
+### Real-World Examples
+
+**Legal Contract Analysis**
+
+- 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
+
+**Financial Analysis**
+
+- Without role: Basic observations
+- With role (CFO of high-growth SaaS company): Strategic insights including segment performance, margin implications, cash runway calculations, actionable recommendations
+
+---
+
+## Using XML Tags
+
+### Core Purpose
+
+XML tags help the model parse prompts more accurately by clearly separating different components like context, instructions, and examples.
+
+### Key Benefits
+
+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
+
+### Best Practices
+
+**1. Maintain Consistency**
+Apply identical tag names throughout and reference them when discussing content
+
+**2. Utilize Nesting**
+Arrange tags hierarchically for complex information structures
+
+**3. Common Tag Patterns**
+
+```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>
+```
+
+### 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
+
+### Important Note
+
+No specific XML tags are canonically required—tag names should align logically with their content.