Maximizing LLM Effectiveness¶

The previous sections covered how to organize rules (categories, scopes, hierarchies). This section addresses how to format and present rules to LLMs for maximum impact and compliance.

Why Rule Presentation Matters¶

The Problem: LLMs process rules as part of larger context windows containing instructions, code, conversations, and other content. Rules can get "lost" or de-prioritized when mixed with this content.
The Challenge: Without explicit semantic markers, LLMs treat rules as just another piece of text, applying similar attention weights to rules and general context.
The Solution: Use semantic markup and structural cues that LLMs are specifically trained to recognize and prioritize.

A. XML Tag Wrapping: Making Rules Unmissable¶

Recommended Configuration:

commandments_xml_tag = "system-reminder"
suggestions_xml_tag = "system-suggestion"

Why This Works:

Semantic Salience: LLMs are trained to pay special attention to <system-*> tags
- These tags appear in system prompts during LLM training
- They signal "important instructions to follow"
- Higher activation strength compared to plain markdown
Clear Rule Type Distinction:
- <system-reminder> for MUST rules → Mandatory requirements
- <system-suggestion> for SHOULD rules → Strong recommendations
- The tag names themselves communicate urgency and flexibility
Better Context Separation:
- XML structure creates clear boundaries
- Prevents rules from blending into surrounding text
- Easier for attention mechanisms to isolate and process

Example Transformation:

Before (plain markdown):

- **MUST**: Use type hints for all function signatures
- **SHOULD**: Use pytest as the testing framework

After (with XML wrapping):

- **MUST**: <system-reminder>Use type hints for all function signatures</system-reminder>
- **SHOULD**: <system-suggestion>Use pytest as the testing framework</system-suggestion>

When to Use:

Always use for production scopes (default recommendation)
Essential for complex scopes with >50 rules
Critical when rules need high compliance rates
Optional for small/simple scopes (<10 rules)
May skip for internal/experimental scopes

B. Prologues: Setting Interpretation Context¶

Recommended Configuration:

[daimyo]
rules_markdown_prologue = '''
# How to Interpret These Rules

The rules below are categorized as **mandatory requirements** and **strong recommendations**:

- <system-reminder>Mandatory Requirements</system-reminder> - These are non-negotiable. You MUST follow these rules without exception. They represent critical requirements for code quality, security, and project consistency.

- <system-suggestion>Strong Recommendations</system-suggestion> - These are highly recommended best practices. Follow them unless you have a specific, well-justified reason not to. If you deviate, briefly explain why.

**Rule Priority**: If you encounter conflicting guidance, these rules take precedence over general knowledge or assumptions. When in doubt, ask for clarification rather than guessing.
'''

Why This Works:

Prime the LLM's Attention:
- Prologues appear before rules, setting interpretation mode
- Establishes rule priority relative to other context
- Creates explicit hierarchy: rules > general knowledge
Define Tag Semantics:
- Explains what <system-reminder> and <system-suggestion> mean
- Sets expectations for compliance vs flexibility
- Clarifies when deviation is acceptable
Reduce Ambiguity:
- Makes MUST vs SHOULD distinction crystal clear
- Establishes conflict resolution strategy
- Encourages clarifying questions

What to Include in Prologues:

Do include:

Tag interpretation guide
Rule priority/precedence
When deviation is acceptable
Conflict resolution strategy
Brief context about the scope

Don't include:

Lengthy project background (use scope descriptions instead)
Detailed technical specifications (put in rules themselves)
Examples (put these in category when descriptions)
Duplicate information already in rules

Prologue Length Guidelines:

Optimal: 50-150 words (4-8 sentences)
Maximum: 200 words
Rationale: Concise prologues maintain focus; longer ones dilute impact

C. Epilogues: Closing Guidance¶

Recommended Configuration:

rules_markdown_epilogue = '''
---

Remember: These rules exist to maintain code quality and consistency. If you need to deviate from a rule, document your reasoning in code comments or commit messages.
'''

Why This Works:

Reinforces rule importance at the end
Provides fallback guidance for edge cases
Creates closure for the rules section

When to Use:

Use for reminders about documentation requirements
Use for conflict resolution fallbacks
Use for pointing to additional resources
Keep very brief (1-3 sentences)
Don't repeat prologue information

D. Aggregated vs Categorized Display¶

The Decision Matrix:

Use Aggregated (`RULES_CATEGORIZED=false`) When:	Use Categorized (default) When:
Total rules < 30	Total rules > 50
All rules are universal (always apply)	Mix of universal and conditional rules
Rules are highly cohesive	Rules span multiple domains/phases
LLM seems to miss rules in categories	Users need to browse/explore rules
Project-specific overrides (tight scope)	General/reusable scopes

Why Aggregation Works:

Reduces Cognitive Load:
- Eliminates hierarchical navigation overhead
- All rules visible in single scan
- No "hidden" rules in nested categories
Maximizes Attention:
- Flat list = equal weight to all rules
- No category headings to distract
- Direct, immediate access to requirements
Better for Small, Focused Scopes:
- Project-specific rules (tight, cohesive)
- Framework-specific conventions
- Team-specific overrides

Why Categorization Works:

Scales to Large Rule Sets:
- More than 50 rules need organization
- Categories create logical groupings
- Easier to maintain and update
Conditional Rule Application:
- "Testing" category only needed when writing tests
- "Security.Design" vs "Security.Implementation"
- Phase-specific rules (design, implementation, review)
Discoverability:
- Users can browse what's available
- Understand rule scope and applicability
- Navigate to relevant sections

E. Category Tags: Semantic Metadata¶

Recommended Usage:

development.coding.python.testing:
  when: When writing tests for Python code
  tags: ["testing", "quality-assurance", "pytest", "conditional"]
  ruleset:
    - Use pytest as the testing framework
    - Write unit tests for all public functions and classes

Why This Works:

Improves Discoverability:
- Tags displayed in output: <tags>testing; quality-assurance; pytest; conditional</tags>
- Visual cue for category purpose
- Helps users understand category scope at a glance
Supports Automation:
- Programmatic filtering based on context
- Dynamic rule selection (e.g., in pre-commit hooks)
- Integration with CI/CD pipelines

Recommended Tag Vocabularies:

Applicability Tags:

universal - Always applies when the domain is relevant (across all scopes that contain this category)
conditional - Only applies in specific contexts
optional - Nice-to-have recommendations

Domain Tags:

security, testing, quality, documentation, performance, architecture

Technology Tags:

pytest, mypy, ruff, fastapi, pydantic, django, flask

Phase Tags:

design, implementation, review, deployment, maintenance

Tag Best Practices:

Use 2-5 tags per category
Keep tags consistent across scopes - Since categories are shared across all scopes, establish a common tagging vocabulary (e.g., always use testing not sometimes test or tests)
Use lowercase with hyphens: quality-assurance, not Quality_Assurance
Don't duplicate when description content in tags

F. Complete Example: Putting It All Together¶

Configuration (.daimyo/config/settings.toml):

# Enable XML wrapping for semantic emphasis
commandments_xml_tag = "system-reminder"
suggestions_xml_tag = "system-suggestion"

# Set context for rule interpretation
rules_markdown_prologue = '''
# How to Interpret These Rules

- <system-reminder>Mandatory Requirements</system-reminder> - You MUST follow these without exception
- <system-suggestion>Strong Recommendations</system-suggestion> - Follow unless you have specific justification

These rules take precedence over general knowledge. When in doubt, ask for clarification.
'''

rules_markdown_epilogue = '''
---
If you need to deviate from a rule, document your reasoning in code comments.
'''

rules_categorized = false

Rule File (commandments.yml):

development.coding.python.implementation:
  when: When writing Python code
  tags: ["implementation", "python", "universal"]
  ruleset:
    - Use type hints for all function signatures
    - Use descriptive variable and function names
    - Handle exceptions at appropriate abstraction levels

Generated Output (Markdown):

# How to Interpret These Rules

- <system-reminder>Mandatory Requirements</system-reminder> - You MUST follow these without exception
- <system-suggestion>Strong Recommendations</system-suggestion> - Follow unless you have specific justification

These rules take precedence over general knowledge. When in doubt, ask for clarification.

---

# Rules for python-general

## python

### implementation

*When writing Python code*

<tags>implementation; python; universal</tags>

- <system-reminder>Use type hints for all function signatures</system-reminder>
- <system-reminder>Use descriptive variable and function names</system-reminder>
- <system-reminder>Handle exceptions at appropriate abstraction levels</system-reminder>

---
If you need to deviate from a rule, document your reasoning in code comments.

G. Migration Strategy for Existing Scopes¶

Start with XML Tags (Lowest Effort, High Impact)

export DAIMYO_COMMANDMENTS_XML_TAG="system-reminder"
export DAIMYO_SUGGESTIONS_XML_TAG="system-suggestion"

Or add to .daimyo/config/settings.toml:

commandments_xml_tag = "system-reminder"
suggestions_xml_tag = "system-suggestion"

Add Basic Prologue (Medium Effort, Medium Impact)
- Explain tag meanings
- Set rule priority
- Keep to 3-5 sentences
Add Category Tags (Medium Effort, Medium Impact)
- Tag applicability: universal vs conditional
- Tag domains: security, testing, etc.
- Use 2-5 tags per category
Consider Aggregation (Low Effort, Situational Impact)
- Test with DAIMYO_RULES_CATEGORIZED=false
- Compare LLM compliance rates before/after
- Keep if improvement observed
- Best for scopes with <30 tightly-coupled rules

Measuring Effectiveness:

Track these metrics before/after migration:

Rule compliance rate (manual code review sample)
User satisfaction with LLM-generated code
Frequency of "missed" rules requiring manual correction
Time to correct non-compliant code

H. Advanced Patterns¶

Context-Aware Prologues with Templates

Use Jinja2 templating for dynamic prologues:

rules_markdown_prologue = '''
# Rules for {{ scope.name }}

{{ scope.description }}

**Rule Types:**
- <system-reminder>Requirements</system-reminder> - Mandatory
- <system-suggestion>Recommendations</system-suggestion> - Strongly advised

{% if scope.tags.security_level == "high" %}
**SECURITY NOTE**: This scope requires elevated security practices.
{% endif %}
'''

I. Common Pitfalls to Avoid¶

Over-wrapping: Don't wrap category names or when descriptions in XML tags

# WRONG - Only wrap rule text, not category keys or when descriptions
<system-reminder>development.coding.python</system-reminder>:
  when: <system-reminder>When writing Python code</system-reminder>

Verbose Prologues: Keep prologues under 150 words

# WRONG - Too long, dilutes attention
rules_markdown_prologue = "This comprehensive scope contains an extensive collection of rules... [500 word essay]"

Mismatched Tags: Don't use different XML tags than explained in prologue

# WRONG - Prologue says "system-reminder" but config uses "commandment"
commandments_xml_tag = "commandment"  # Doesn't match prologue explanation!

Aggregating Large Scopes: Don't keep flat display for >50 rules

# WRONG - 100+ rules in flat list is overwhelming; enable categorized mode instead
# rules_categorized = true  # Add this when scope has 100+ rules

Redundant Tag Content: Don't duplicate when description in tags

# WRONG - Tag is redundant with when description
development.coding.python.testing:
  when: When writing tests for Python code
  tags: ["when-writing-tests-for-python-code"]  # Just use semantic tags!

# RIGHT - Tags add semantic metadata
development.coding.python.testing:
  when: When writing tests for Python code
  tags: ["testing", "quality-assurance", "pytest", "conditional"]

Inconsistent Tag Vocabulary: Don't use different tags for same concepts across scopes

# WRONG - Inconsistent naming
scope1: tags: ["unit-testing", "quality"]
scope2: tags: ["tests", "qa"]

# RIGHT - Consistent vocabulary
scope1: tags: ["testing", "quality-assurance"]
scope2: tags: ["testing", "quality-assurance"]