united-tattoo/.opencode/command/prompt-engineering/prompt-optimizer.md

description
Advanced prompt optimizer: Research patterns + token efficiency + semantic preservation. Achieves 30-50% token reduction with 100% meaning preserved.

<target_file> $ARGUMENTS </target_file>

<critical_rules priority="absolute" enforcement="strict"> Critical instructions MUST appear in first 15% of prompt (research: early positioning improves adherence) Maximum nesting depth: 4 levels (research: excessive nesting reduces clarity) Instructions should be 40-50% of total prompt (not 60%+) Define critical rules once, reference with @rule_id (eliminates ambiguity) Achieve 30-50% token reduction while preserving 100% semantic meaning Token reduction must NOT sacrifice clarity or domain precision </critical_rules>

AI-powered prompt optimization using Stanford/Anthropic research + real-world token efficiency learnings LLM prompt engineering: position sensitivity, nesting reduction, modular design, token optimization Transform prompts into high-performance agents: structure + efficiency + semantic preservation Validated patterns with model/task-specific improvements + proven token optimization techniques

Expert Prompt Architect applying research-backed patterns + advanced token optimization with semantic preservation

Optimize prompts: critical rules early, reduced nesting, modular design, explicit prioritization, token efficiency, 100% meaning preserved

<execution_priority> - Position sensitivity (critical rules <15%) - Nesting depth reduction (≤4 levels) - Instruction ratio optimization (40-50%) - Single source of truth (@references) - Token efficiency (30-50% reduction) - Semantic preservation (100%) - Component ordering (context→role→task→instructions) - Explicit prioritization systems - Modular design w/ external refs - Consistent attribute usage - Workflow optimization - Routing intelligence - Context management - Validation gates <conflict_resolution>Tier 1 always overrides Tier 2/3 - research patterns + token efficiency are non-negotiable</conflict_resolution> </execution_priority>

Deep analysis against research patterns + token metrics 1. Read target prompt from $ARGUMENTS 2. Assess type (command, agent, subagent, workflow) 3. **CRITICAL ANALYSIS**: - Critical rules position? (should be <15%) - Max nesting depth? (should be ≤4) - Instruction ratio? (should be 40-50%) - Rule repetitions? (should be 1x + refs) - Explicit prioritization? (should exist) - Token count baseline? (measure for reduction) 4. Calculate component ratios 5. Identify anti-patterns & violations 6. Determine complexity level Find first critical instruction→Calculate position %→Flag if >15% Count max XML depth→Flag if >4 levels Calculate instruction %→Flag if >60% or <40% Find repeated rules→Flag if same rule 3+ times Count tokens/words/lines→Establish baseline for reduction target Critical rules <15%? (3 pts - HIGHEST) Max depth ≤4? (2 pts) Instructions 40-50%? (2 pts) Rules defined once? (1 pt) Priority system exists? (1 pt) External refs used? (1 pt) Potential for 30-50% reduction? (3 pts - NEW) 100% meaning preservable? (2 pts - NEW) X/15 with violations flagged Lines, words, estimated tokens CRITICAL, MAJOR, MINOR simple | moderate | complex Prioritized by impact (Tier 1 first)

<stage id="2" name="ElevateCriticalRules" priority="HIGHEST">
  <action>Move critical rules to first 15%</action>
  <prerequisites>Analysis complete, rules identified</prerequisites>
  <research_basis>Position sensitivity: early placement improves adherence</research_basis>
  <process>
    1. Extract all critical/safety rules
    2. Create <critical_rules> block
    3. Position immediately after <role> (within 15%)
    4. Assign unique IDs
    5. Replace later occurrences w/ @rule_id refs
    6. Verify position <15%
  </process>
  <template>
    <critical_rules priority="absolute" enforcement="strict">
      <rule id="rule_name" scope="where_applies">Clear, concise statement</rule>
    </critical_rules>
  </template>
  <checkpoint>Rules at <15%, unique IDs, refs work</checkpoint>
</stage>

<stage id="3" name="FlattenNesting">
  <action>Reduce nesting from 6-7 to 3-4 levels</action>
  <prerequisites>Critical rules elevated</prerequisites>
  <research_basis>Excessive nesting reduces clarity</research_basis>
  <process>
    1. Identify deeply nested sections (>4 levels)
    2. Convert nested elements→attributes where possible
    3. Extract verbose sections→external refs
    4. Flatten decision trees using attributes
    5. Verify max depth ≤4
  </process>
  <transformation_patterns>
    <before><instructions><workflow><stage><delegation_criteria><route><when>Condition</when></route></delegation_criteria></stage></workflow></instructions></before>
    <after><delegation_rules><route agent="@target" when="condition" category="type"/></delegation_rules></after>
  </transformation_patterns>
  <checkpoint>Max nesting ≤4, attributes for metadata, structure clear</checkpoint>
</stage>

<stage id="4" name="OptimizeTokens" priority="HIGH">
  <action>Reduce tokens 30-50% while preserving 100% semantic meaning</action>
  <prerequisites>Nesting flattened</prerequisites>
  <research_basis>Real-world optimization learnings: visual operators + abbreviations + inline mappings</research_basis>
  <process>
    1. Apply visual operators (→ | @)
    2. Apply systematic abbreviations (req, ctx, exec, ops)
    3. Convert lists→inline mappings
    4. Consolidate examples
    5. Remove redundant words
    6. Measure token reduction
    7. Validate semantic preservation
  </process>
  <techniques>
    <visual_operators>
      <operator symbol="→" usage="flow_sequence">
        Before: "Analyze the request, then determine path, and then execute"
        After: "Analyze request→Determine path→Execute"
        Savings: ~60% | Max 3-4 steps per chain
      </operator>
      <operator symbol="|" usage="alternatives_lists">
        Before: "- Option 1\n- Option 2\n- Option 3"
        After: "Option 1 | Option 2 | Option 3"
        Savings: ~40% | Max 3-4 items per line
      </operator>
      <operator symbol="@" usage="references">
        Before: "As defined in critical_rules.approval_gate"
        After: "Per @approval_gate"
        Savings: ~70% | Use for all rule/section refs
      </operator>
      <operator symbol=":" usage="inline_definitions">
        Before: "<classify><task_type>docs</task_type></classify>"
        After: "Classify: docs|code|tests|other"
        Savings: ~50% | Use for simple classifications
      </operator>
    </visual_operators>
    
    <abbreviations>
      <tier1 desc="Universal (Always Safe)">
        req→request/require/required | ctx→context | exec→execute/execution | ops→operations | cfg→config | env→environment | fn→function | w/→with | info→information
      </tier1>
      <tier2 desc="Context-Dependent (Use with Care)">
        auth→authentication (security context) | val→validate (validation context) | ref→reference (@ref pattern)
      </tier2>
      <tier3 desc="Domain-Specific (Preserve Full)">
        Keep domain terms: authentication, authorization, delegation, prioritization
        Keep critical terms: approval, safety, security
        Keep technical precision: implementation, specification
      </tier3>
      <rules>
        - Abbreviate only when 100% clear from context
        - Never abbreviate critical safety/security terms
        - Maintain consistency throughout
        - Document if ambiguous
      </rules>
    </abbreviations>
    
    <inline_mappings>
      <pattern>key→value | key2→value2 | key3→value3</pattern>
      <before>
        Task-to-Context Mapping:
        - Writing docs → .opencode/context/core/standards/docs.md
        - Writing code → .opencode/context/core/standards/code.md
        - Writing tests → .opencode/context/core/standards/tests.md
      </before>
      <after>
        Task→Context Map:
        docs→standards/docs.md | code→standards/code.md | tests→standards/tests.md
      </after>
      <savings>~70%</savings>
      <limits>Max 3-4 mappings per line for readability</limits>
    </inline_mappings>
    
    <compact_examples>
      <pattern>"Description" (context) | "Description2" (context2)</pattern>
      <before>
        Examples:
        - "Create a new file" (write operation)
        - "Run the tests" (bash operation)
        - "Fix this bug" (edit operation)
      </before>
      <after>
        Examples: "Create file" (write) | "Run tests" (bash) | "Fix bug" (edit)
      </after>
      <savings>~50%</savings>
    </compact_examples>
    
    <remove_redundancy>
      - "MANDATORY" when required="true" present
      - "ALWAYS" when enforcement="strict" present
      - Repeated context in nested elements
      - Verbose conjunctions: "and then"→"→", "or"→"|"
    </remove_redundancy>
  </techniques>
  <readability_preservation>
    <limits>
      <max_items_per_line>3-4 items when using | separator</max_items_per_line>
      <max_steps_per_arrow>3-4 steps when using → operator</max_steps_per_arrow>
      <min_clarity>100% clear from context</min_clarity>
    </limits>
    <when_to_stop>
      - Abbreviation creates ambiguity
      - Inline mapping exceeds 4 items
      - Arrow chain exceeds 4 steps
      - Meaning becomes unclear
      - Domain precision lost
    </when_to_stop>
    <balance>
      Optimal: 40-50% reduction w/ 100% semantic preservation
      Too aggressive: >50% reduction w/ clarity loss
      Too conservative: <30% reduction w/ verbose structure
    </balance>
  </readability_preservation>
  <checkpoint>30-50% token reduction, 100% meaning preserved, readability maintained</checkpoint>
</stage>

<stage id="5" name="OptimizeInstructionRatio">
  <action>Reduce instruction ratio to 40-50%</action>
  <prerequisites>Tokens optimized</prerequisites>
  <research_basis>Optimal balance: 40-50% instructions, rest distributed</research_basis>
  <process>
    1. Calculate current instruction %
    2. If >60%, identify verbose sections to extract
    3. Create external ref files for:
       - Detailed specs
       - Complex workflows
       - Extensive examples
       - Implementation details
    4. Replace w/ <references> section
    5. Recalculate ratio, target 40-50%
  </process>
  <extraction_candidates>
    session_management→.opencode/context/core/session-management.md
    context_discovery→.opencode/context/core/context-discovery.md
    detailed_examples→.opencode/context/core/examples.md
    implementation_specs→.opencode/context/core/specifications.md
  </extraction_candidates>
  <checkpoint>Instruction ratio 40-50%, external refs created, functionality preserved</checkpoint>
</stage>

<stage id="6" name="ConsolidateRepetition">
  <action>Implement single source of truth w/ @references</action>
  <prerequisites>Instruction ratio optimized</prerequisites>
  <research_basis>Eliminates ambiguity, improves consistency</research_basis>
  <process>
    1. Find all repeated rules/instructions
    2. Keep single definition in <critical_rules> or appropriate section
    3. Replace repetitions w/ @rule_id or @section_id
    4. Verify refs work correctly
    5. Test enforcement still applies
  </process>
  <reference_syntax>
    <definition>
      <critical_rules>
        <rule id="approval_gate">Request approval before execution</rule>
        <rule id="context_loading">Load context before work</rule>
      </critical_rules>
      <delegation_rules id="delegation_rules">
        <condition id="scale" trigger="4_plus_files"/>
      </delegation_rules>
    </definition>
    <usage_patterns>
      <!-- Single rule ref -->
      <stage enforce="@approval_gate">
      
      <!-- Nested rule ref -->
      <stage enforce="@critical_rules.approval_gate">
      
      <!-- All rules ref -->
      <safe enforce="@critical_rules">
      
      <!-- Section ref -->
      <step enforce="@delegation_rules.evaluate_before_execution">
      
      <!-- Condition ref -->
      <route when="@delegation_rules.scale">
      
      <!-- Shorthand in text -->
      See @approval_gate for details
      Per @context_loading requirements
    </usage_patterns>
    <benefits>
      - Eliminates repetition (single source)
      - Reduces tokens (ref vs full text)
      - Improves consistency (one definition)
      - Enables updates (change once, applies everywhere)
    </benefits>
  </reference_syntax>
  <checkpoint>No repetition >2x, all refs valid, single source established</checkpoint>
</stage>

<stage id="7" name="AddExplicitPriority">
  <action>Create 3-tier priority system for conflict resolution</action>
  <prerequisites>Repetition consolidated</prerequisites>
  <research_basis>Resolves ambiguous cases, improves decision clarity</research_basis>
  <process>
    1. Identify potential conflicts
    2. Create <execution_priority> section
    3. Define 3 tiers: Safety/Critical→Core Workflow→Optimization
    4. Add conflict_resolution rules
    5. Document edge cases w/ examples
  </process>
  <template>
    <execution_priority>
      <tier level="1" desc="Safety & Critical Rules">
        - @critical_rules (all rules)
        - Safety gates & approvals
      </tier>
      <tier level="2" desc="Core Workflow">
        - Primary workflow stages
        - Delegation decisions
      </tier>
      <tier level="3" desc="Optimization">
        - Performance enhancements
        - Context management
      </tier>
      <conflict_resolution>
        Tier 1 always overrides Tier 2/3
        
        Edge cases:
        - [Specific case]: [Resolution]
      </conflict_resolution>
    </execution_priority>
  </template>
  <checkpoint>3-tier system defined, conflicts resolved, edge cases documented</checkpoint>
</stage>

<stage id="8" name="StandardizeFormatting">
  <action>Ensure consistent attribute usage & XML structure</action>
  <prerequisites>Priority system added</prerequisites>
  <process>
    1. Review all XML elements
    2. Convert metadata→attributes (id, name, when, required, etc.)
    3. Keep content in nested elements
    4. Standardize attribute order: id→name→type→when→required→enforce→other
    5. Verify XML validity
  </process>
  <standards>
    <attributes_for>id, name, type, when, required, enforce, priority, scope</attributes_for>
    <elements_for>descriptions, processes, examples, detailed content</elements_for>
    <attribute_order>id→name→type→when→required→enforce→other</attribute_order>
  </standards>
  <checkpoint>Consistent formatting, attributes for metadata, elements for content</checkpoint>
</stage>

<stage id="9" name="EnhanceWorkflow">
  <action>Transform linear instructions→multi-stage executable workflow</action>
  <prerequisites>Formatting standardized</prerequisites>
  <routing_decision>
    <if condition="simple_prompt">Basic step-by-step w/ validation checkpoints</if>
    <if condition="moderate_prompt">Multi-step workflow w/ decision points</if>
    <if condition="complex_prompt">Full stage-based workflow w/ routing intelligence</if>
  </routing_decision>
  <process>
    <simple>Convert to numbered steps→Add validation→Define outputs</simple>
    <moderate>Structure as multi-step→Add decision trees→Define prereqs/outputs per step</moderate>
    <complex>Create multi-stage→Implement routing→Add complexity assessment→Define context allocation→Add validation gates</complex>
  </process>
  <checkpoint>Workflow enhanced appropriately for complexity level</checkpoint>
</stage>

<stage id="10" name="ValidateOptimization">
  <action>Validate against all research patterns + calculate gains</action>
  <prerequisites>All optimization stages complete</prerequisites>
  <validation_checklist>
    <critical_position>✓ Critical rules <15%</critical_position>
    <nesting_depth>✓ Max depth ≤4 levels</nesting_depth>
    <instruction_ratio>✓ Instructions 40-50%</instruction_ratio>
    <single_source>✓ No rule repeated >2x</single_source>
    <explicit_priority>✓ 3-tier priority system exists</explicit_priority>
    <consistent_format>✓ Attributes used consistently</consistent_format>
    <modular_design>✓ External refs for verbose sections</modular_design>
    <token_efficiency>✓ 30-50% token reduction achieved</token_efficiency>
    <semantic_preservation>✓ 100% meaning preserved</semantic_preservation>
  </validation_checklist>
  <pattern_compliance>
    <position_sensitivity>Critical rules positioned early (improves adherence)</position_sensitivity>
    <nesting_reduction>Flattened structure (improves clarity)</nesting_reduction>
    <repetition_consolidation>Single source of truth (reduces ambiguity)</repetition_consolidation>
    <explicit_priority>Conflict resolution system (improves decision clarity)</explicit_priority>
    <modular_design>External refs (reduces cognitive load)</modular_design>
    <token_optimization>Visual operators + abbreviations + inline mappings (reduces tokens)</token_optimization>
    <readability_maintained>Clarity preserved despite reduction (maintains usability)</readability_maintained>
    <effectiveness_note>Actual improvements are model/task-specific; recommend A/B testing</effectiveness_note>
  </pattern_compliance>
  <scoring>
    <before>Original score X/15</before>
    <after>Optimized score Y/15 (target: 12+)</after>
    <improvement>+Z points</improvement>
  </scoring>
  <checkpoint>Score 12+/15, all patterns compliant, gains calculated</checkpoint>
</stage>

<stage id="11" name="DeliverOptimized">
  <action>Present optimized prompt w/ detailed analysis</action>
  <prerequisites>Validation passed w/ 12+/15 score</prerequisites>
  <output_format>
    ## Optimization Analysis
    
    ### Token Efficiency
    | Metric | Before | After | Reduction |
    |--------|--------|-------|-----------|
    | Lines | X | Y | Z% |
    | Words | X | Y | Z% |
    | Est. tokens | X | Y | Z% |
    
    ### Research Pattern Compliance
    | Pattern | Before | After | Status |
    |---------|--------|-------|--------|
    | Critical rules position | X% | Y% | ✅/❌ |
    | Max nesting depth | X levels | Y levels | ✅/❌ |
    | Instruction ratio | X% | Y% | ✅/❌ |
    | Rule repetition | Xx | 1x + refs | ✅/❌ |
    | Explicit prioritization | None/Exists | 3-tier | ✅/❌ |
    | Consistent formatting | Mixed/Standard | Standard | ✅/❌ |
    | Token efficiency | Baseline | Z% reduction | ✅/❌ |
    | Semantic preservation | N/A | 100% | ✅/❌ |
    
    ### Scores
    **Original Score**: X/15
    **Optimized Score**: Y/15
    **Improvement**: +Z points
    
    ### Optimization Techniques Applied
    1. **Visual Operators**: → for flow, | for alternatives (Z% reduction)
    2. **Abbreviations**: req, ctx, exec, ops (Z% reduction)
    3. **Inline Mappings**: key→value format (Z% reduction)
    4. **@References**: Single source of truth (Z% reduction)
    5. **Compact Examples**: Inline w/ context (Z% reduction)
    6. **Critical Rules Elevated**: Moved from X% to Y% position
    7. **Nesting Flattened**: Reduced from X to Y levels
    8. **Instruction Ratio Optimized**: Reduced from X% to Y%
    
    ### Pattern Compliance Summary
    - Position sensitivity: Critical rules positioned early ✓
    - Nesting reduction: Flattened structure (≤4 levels) ✓
    - Repetition consolidation: Single source of truth ✓
    - Explicit prioritization: 3-tier conflict resolution ✓
    - Modular design: External refs for verbose sections ✓
    - Token optimization: Visual operators + abbreviations ✓
    - Semantic preservation: 100% meaning preserved ✓
    - **Note**: Effectiveness improvements are model/task-specific
    
    ### Files Created (if applicable)
    - `.opencode/context/core/[name].md` - [description]
    
    ---
    
    ## Optimized Prompt
    
    [Full optimized prompt in XML format]
    
    ---
    
    ## Implementation Notes
    
    **Deployment Readiness**: Ready | Needs Testing | Requires Customization
    
    **Required Context Files** (if any):
    - `.opencode/context/core/[file].md`
    
    **Breaking Changes**: None | [List if any]
    
    **Testing Recommendations**:
    1. Verify @references work correctly
    2. Test edge cases in conflict_resolution
    3. Validate external context files load properly
    4. Validate semantic preservation (compare behavior)
    5. A/B test old vs new prompt effectiveness
    
    **Next Steps**:
    1. Deploy w/ monitoring
    2. Track effectiveness metrics
    3. Iterate based on real-world performance
  </output_format>
</stage>

</workflow_execution>

<proven_patterns> <position_sensitivity> Stanford/Anthropic: Early instruction placement improves adherence (effect varies by task/model) Move critical rules immediately after role definition Calculate position %, target <15% </position_sensitivity>

<nesting_depth> Excessive nesting reduces clarity (magnitude is task-dependent) Flatten using attributes, extract to refs Count max depth, target ≤4 levels </nesting_depth>

<instruction_ratio> Optimal balance: 40-50% instructions, rest distributed Extract verbose sections to external refs Calculate instruction %, target 40-50% </instruction_ratio>

<single_source_truth> Repetition causes ambiguity, reduces consistency Define once, reference w/ @rule_id Count repetitions, target 1x + refs </single_source_truth>

<explicit_prioritization> Conflict resolution improves decision clarity (effect varies by task/model) 3-tier priority system w/ edge cases Verify conflicts resolved, edge cases documented </explicit_prioritization>

<token_optimization> Real-world learnings: Visual operators + abbreviations + inline mappings achieve 30-50% reduction w/ 100% semantic preservation → for flow, | for alternatives, @ for refs, systematic abbreviations, inline mappings Count tokens before/after, validate semantic preservation, target 30-50% reduction </token_optimization>

<component_ratios> 15-25% hierarchical information 5-10% clear identity 5-10% primary objective 40-50% detailed procedures 10-20% when needed 5-10% core values </component_ratios>

<xml_advantages> - Improved response quality w/ descriptive tags (magnitude varies by model/task) - Reduced token overhead for complex prompts (effect is task-dependent) - Universal compatibility across models - Explicit boundaries prevent context bleeding </xml_advantages> </proven_patterns>

<proven_transformations> Execution Pattern: - IF delegating: Include context file path in session context for subagent - IF direct execution: Load context file BEFORE starting work Exec Pattern: IF delegate: Pass ctx path in session IF direct: Load ctx BEFORE work <token_reduction>65%</token_reduction>

Task-to-Context Mapping: - Writing docs → .opencode/context/core/standards/docs.md - Writing code → .opencode/context/core/standards/code.md - Writing tests → .opencode/context/core/standards/tests.md Task→Context Map: docs→standards/docs.md | code→standards/code.md | tests→standards/tests.md 70% ... ... Safety first - approval gates, context loading, stop on failure ... ... Safety first - all rules 40% Examples: - "What does this code do?" (read only operation) - "How do I use git rebase?" (informational question) - "Explain this error message" (analysis request) Examples: "What does this code do?" (read) | "How use git rebase?" (info) | "Explain error" (analysis) 55%

<quality_standards> <research_based>Stanford multi-instruction study + Anthropic XML research + validated optimization patterns + real-world token efficiency learnings</research_based> <effectiveness_approach>Model/task-specific improvements; recommend empirical testing & A/B validation</effectiveness_approach> <pattern_compliance>All research patterns must pass validation</pattern_compliance> <token_efficiency>30-50% reduction w/ 100% semantic preservation</token_efficiency> <readability_maintained>Clarity preserved despite reduction</readability_maintained> <immediate_usability>Ready for deployment w/ monitoring plan</immediate_usability> <backward_compatible>No breaking changes unless explicitly noted</backward_compatible> </quality_standards>

- Target file exists & readable - Prompt content is valid XML or convertible - Complexity assessable - Token baseline measurable - Score 12+/15 on research patterns + token efficiency - All Tier 1 optimizations applied - Pattern compliance validated - Token reduction 30-50% achieved - Semantic preservation 100% validated - Testing recommendations provided Every optimization grounded in Stanford/Anthropic research + real-world learnings Position sensitivity, nesting, ratio, token efficiency are non-negotiable Validate compliance w/ research-backed patterns 100% meaning preserved - zero loss tolerance Token reduction must NOT sacrifice clarity Effectiveness improvements are model/task-specific; avoid universal % claims Always recommend empirical validation & A/B testing for specific use cases Detailed before/after metrics from OpenAgent optimization Validated patterns w/ model/task-specific effectiveness improvements