♻️ Refactor all prompts for LLM-to-LLM communication best practices

[TechNickAI]

Summary

Comprehensive refactoring of all prompts (commands, agents, skills, workflow rules) to follow LLM-to-LLM communication best practices from @rules/prompt-engineering.mdc.

What Changed

Structural Improvements

• Semantic XML tags: Replaced numbered sections (### 1., ### 2.) with semantic XML tags (<objective>, <workflow>, <guidelines>, etc.)
• Goal-oriented: Converted prescriptive step-by-step instructions to goal-focused outcomes
• Trust the executing model: Removed micro-management, trusting smarter executing LLMs to figure out implementation details
• Front-loaded information: Critical information now appears first in all prompts

Content Optimization

• Removed excessive formatting: Eliminated bold, italics, decorative symbols that waste tokens
• Consolidated repetitive content: Merged redundant explanations while preserving functionality
• Removed anti-patterns: Eliminated "bad example" code blocks that LLMs might reproduce
• Clarity over brevity: Maintained unambiguous language while reducing verbosity

Impact

• 18 files refactored
• Net reduction: ~1,476 lines (~40% reduction)
• Improved LLM parseability with clear XML structure
• Reduced token usage while maintaining all functionality
• Better suited for LLM-to-LLM communication

Files Modified

Commands (9 files)

• autotask.md: 233 → 160 lines (31% reduction)
• setup-environment.md: 123 → 68 lines (45% reduction)
• create-prompt.md: 71 → 46 lines (35% reduction)
• troubleshoot.md: 256 → 111 lines (57% reduction)
• handoff-context.md: 124 → 49 lines (60% reduction)
• personality-change.md: 127 → 43 lines (66% reduction)
• ai-coding-config.md: 281 → 208 lines (26% reduction)
• product-intel.md: 238 → 185 lines (22% reduction)
• generate-AGENTS-file.md: 254 → 218 lines (14% reduction)

Agents (3 files)

• design-reviewer.md: 106 → 74 lines (30% reduction)
• seo-specialist.md: 101 → 60 lines (41% reduction)
• site-keeper.md: 492 → 152 lines (69% reduction)

Skills (5 files)

• brainstorming/SKILL.md: 176 → 87 lines (51% reduction)
• research/SKILL.md: 159 → 95 lines (40% reduction)
• skill-creator/SKILL.md: 228 → 148 lines (35% reduction)
• systematic-debugging/SKILL.md: 120 → 75 lines (38% reduction)
• youtube-transcript-analyzer/SKILL.md: 177 → 116 lines (34% reduction)

Rules (1 file)

• git-worktree-task.mdc: 209 → 93 lines (56% reduction)

Design Decisions

Preserved all functionality: Every refactored file maintains its original intent and capabilities. No features were removed, only presentation was improved.

Pattern-based examples: Kept good examples as patterns for LLMs to follow, removed "bad example" anti-patterns that LLMs might encode.

XML structure: Used semantic tag names that describe content purpose (e.g., <objective>, <workflow>, <critical-success-factors>) instead of numbered or generic tags.

Goal-focused language: Shifted from "do this, then do that" to "achieve this outcome" to trust the executing model's superior capabilities.

Testing

All refactored files have been reviewed to ensure:

• Original functionality preserved
• Clear semantic structure with XML tags
• Minimal formatting, maximum clarity
• Goal-oriented outcomes instead of prescriptive steps
• No anti-patterns or "bad examples"

🤖 Generated with Claude Code

---

Note

Refactors all AI prompt files (agents, commands, skills, rules) to a concise, XML-tagged, goal-oriented structure that reduces verbosity and removes anti-patterns while preserving functionality.

• Structural:
  • Replace numbered/verbose sections with semantic XML tags (e.g., objective, workflow, quality-standards).
  • Front-load critical info; shift to outcome/goal-focused guidance; reduce prescriptive steps.
• Content Optimization:
  • Remove decorative formatting and "bad example" anti-patterns; consolidate redundancies; trim token usage substantially.
• Scope:
  • Update multiple commands (e.g., autotask, setup-environment, troubleshoot, handoff-context, ai-coding-config, product-intel, generate-AGENTS-file, create-prompt, personality-change).
  • Revise agents (design-reviewer, seo-specialist, site-keeper) and skills (brainstorming, research, skill-creator, systematic-debugging, youtube-transcript-analyzer).
  • Simplify rules (.cursor/rules/git-worktree-task.mdc).
• Result:
  • Clearer LLM-to-LLM parseability, consistent structure, and notable line-count reductions without changing capabilities.

^{Written by Cursor Bugbot for commit 80ef61e. This will update automatically on new commits. Configure here.}

[claude]

Pull Request Review: LLM-to-LLM Communication Refactoring

Thank you for this comprehensive refactoring! This is excellent work that systematically applies prompt engineering best practices across the entire codebase. The transformation from verbose, prescriptive instructions to goal-focused, XML-structured prompts demonstrates deep understanding of how LLMs parse and execute instructions.

Overall Assessment

Verdict: Approved with minor suggestions

This PR delivers exactly what it promises: cleaner, more parseable prompts that trust the executing model's intelligence while reducing token usage by ~40%. The refactoring maintains all functionality while making prompts more effective for LLM-to-LLM communication.

Strengths

1. Consistent Application of Principles ✨

The refactoring consistently applies all key principles from prompt-engineering.mdc:

• XML structure with semantic tags: Replaced numbered sections with meaningful tags like <identity>, <objective>, <workflow>, <quality-standards>. This makes prompts machine-parseable and self-documenting.
• Goal-focused over prescriptive: Shifted from "Step 1, Step 2..." to "achieve this outcome" language, trusting the executing model to determine implementation details.
• Front-loaded critical information: Core objectives appear at the top of every refactored prompt.
• Removed anti-patterns: Eliminated "bad example" code blocks that LLMs might reproduce despite negative labels.
• Minimal formatting: Stripped excessive bold, italics, and decorative symbols that waste tokens without adding semantic value.

2. Semantic XML Tags Over Numbers

The transition from numbered sections to semantic tags is particularly well-executed:

Before (from site-keeper.md):

## Step 0: Discovery & Inventory (ALWAYS FIRST)
## What We Monitor (After Discovery)
## Communication Channels

After:

<objective>...</objective>
<service-detection>...</service-detection>
<error-intelligence>...</error-intelligence>
<communication>...</communication>

This makes prompts more maintainable - you can reorder sections without renumbering everything, and the tags clearly communicate intent.

3. Significant Token Reduction

The 40% reduction in total lines (892 additions, 2369 deletions) is impressive:

• site-keeper.md: 492 → 152 lines (69% reduction)
• personality-change.md: 127 → 43 lines (66% reduction)
• handoff-context.md: 124 → 49 lines (60% reduction)
• troubleshoot.md: 256 → 111 lines (57% reduction)

These reductions come from removing redundancy and verbose explanations, not from cutting functionality. Every prompt retains its original purpose.

4. Clear Structure Aids Comprehension

The XML structure creates clear boundaries that help LLMs parse complex prompts. For example, in autotask.md:

<task-preparation>...</task-preparation>
<worktree-setup>...</worktree-setup>
<autonomous-execution>...</autonomous-execution>
<obstacle-and-decision-handling>...</obstacle-and-decision-handling>
<validation-and-review>...</validation-and-review>
<create-pr>...</create-pr>
<bot-feedback-loop>...</bot-feedback-loop>

This makes it obvious which phase the LLM is in and what comes next.

5. Trust the Executing Model

The refactoring consistently applies the principle "trust the executing model's superior capabilities." For instance, in troubleshoot.md:

Before: Detailed step-by-step instructions for every scenario
After: "Trust the executing model's intelligence - you can determine the best approach for each situation."

This is the right approach - the model executing these prompts (Claude 3.5 Sonnet or newer) is sophisticated enough to figure out implementation details.

Areas for Improvement

1. Inconsistent XML Tag Naming (Minor)

While the refactoring uses semantic tags, there's some inconsistency in naming conventions:

• Some files use <objective>, others use <identity> for similar purposes
• <user-provides> and <command-delivers> (with hyphens) vs <taskpreparation> (no hyphens in some cases)

Suggestion: Establish consistent naming conventions:

• Use hyphens consistently in multi-word tags: <task-preparation> not <taskpreparation>
• Standardize on either <objective> or <identity> for the opening section (I'd suggest <objective> for commands and <identity> for agents)

2. Some Prompts Still Have Prescriptive Language (Minor)

A few prompts retain step-by-step language that could be more goal-focused:

Example from autotask.md:

<task-preparation>
Ensure task clarity before implementation. If the task description is unclear or ambiguous, use /create-prompt to ask clarifying questions and create a structured prompt. If the task is clear and unambiguous, proceed directly to implementation.
</task-preparation>

This is an if-then-else prescription. More goal-focused version:

<task-preparation>
Ensure complete understanding of requirements before implementation. Clarify ambiguous specifications to prevent wasted work.
</task-preparation>

The executing model knows how to clarify requirements - it doesn't need the conditional logic spelled out.

3. Documentation of Breaking Changes (Missing)

The PR description mentions this is a refactoring that preserves all functionality, but doesn't explicitly confirm:

• Are there any changes to command invocation patterns? (e.g., argument formats, expected inputs)
• Will existing automation that invokes these commands continue to work?
• Are there any agents or commands that now behave differently?

Suggestion: Add a "Compatibility" section to the PR description confirming:

• No changes to command/agent invocation patterns
• All functionality preserved
• Changes are purely presentational for LLM consumption

4. Pattern Consistency in Examples (Opportunity)

The prompt-engineering.mdc document emphasizes showing 5+ examples of correct patterns to reinforce learning. Some refactored prompts could benefit from more consistent examples.

Example: In files that demonstrate workflows, consider showing 2-3 similar examples of the pattern rather than one example. This helps the executing model recognize the pattern structure.

Security Considerations

No security concerns identified. The refactoring:

• Doesn't change any executable code
• Doesn't modify authentication or authorization logic
• Doesn't introduce new external dependencies
• Only affects prompt structure and formatting

Performance Considerations

Positive impact expected:

1. Token efficiency: 40% reduction in prompt length means:

   • Faster prompt processing
   • Lower API costs
   • More room in context windows for actual work

2. Clearer structure: XML tags make parsing more deterministic, potentially reducing the number of retries or clarifications needed.

3. Goal-focused prompts: By trusting the executing model, these prompts may lead to more efficient implementations since the model can choose optimal approaches.

Test Coverage

Note: This PR doesn't include automated tests for the refactored prompts. This is understandable - testing LLM prompt effectiveness is challenging. However, consider:

Suggestion for follow-up work:

• Create a manual testing checklist for critical commands (/autotask, /troubleshoot, /setup-environment)
• Test each refactored command with a simple task to verify behavior hasn't changed
• Document any unexpected differences in behavior

This could be a separate issue rather than blocking this PR.

Code Quality & Best Practices

Excellent adherence to prompt-engineering.mdc

The refactoring demonstrates thorough understanding and application of the documented principles:

• ✅ Minimal formatting (no excessive bold/italics)
• ✅ Semantic XML tags with meaningful names
• ✅ Goal-focused over prescriptive
• ✅ Front-loaded critical information
• ✅ Removed anti-patterns
• ✅ Clarity over brevity (removed redundancy but kept precision)
• ✅ Consistent terminology within each file

Well-documented changes

The commit message and PR description clearly explain:

• What changed (structure, format, approach)
• Why it changed (LLM-to-LLM communication best practices)
• Impact (40% reduction, improved parseability)
• Scope (18 files across commands, agents, skills, rules)

Specific File Reviews

.claude/agents/site-keeper.md (69% reduction)

Before: 492 lines of detailed step-by-step instructions with numbered sections
After: 152 lines of goal-focused guidance with clear XML structure

This is the most dramatic improvement in the PR. The original was extremely prescriptive ("Step 0: Discovery & Inventory (ALWAYS FIRST)"). The refactored version trusts the agent to know when to discover infrastructure vs use cached inventory:

<service-detection>
Identify available error monitoring tools. If multiple, ask user preference.
</service-detection>

Much clearer and more flexible.

.claude/commands/troubleshoot.md (57% reduction)

Before: Detailed procedural instructions
After: Clean objective-driven structure with operational modes

The refactored version makes it easier to understand what the command does at different modes. The <operational-modes> section clearly delineates behavior without prescribing every step.

.claude/skills/systematic-debugging/SKILL.md (38% reduction)

This refactoring is particularly well-done. The skill retains its teaching quality while becoming more concise:

<objective>
Find the root cause before writing fixes. Understanding why something breaks leads to correct fixes. Guessing wastes time and creates new problems.

Core principle: If you can't explain WHY it's broken, you're not ready to fix it.
</objective>

This front-loads the most important principle and sets expectations immediately.

Recommendations

Before Merging

1. Minor consistency pass: Quick review for consistent XML tag naming conventions (hyphens, terminology)
2. Compatibility confirmation: Add note to PR description confirming no breaking changes to command invocation

Follow-up Work (Separate Issues)

1. Manual testing: Test each critical command with a simple task to verify behavior
2. Pattern examples: Consider adding 2-3 examples where currently only one exists (following the "5+ examples" guidance from prompt-engineering.mdc)
3. Documentation update: Update any user-facing documentation that shows example command outputs (if command output formats changed)

Conclusion

This is excellent work that significantly improves the quality and maintainability of LLM-to-LLM prompts throughout the project. The systematic application of prompt engineering principles demonstrates careful attention to detail and deep understanding of how LLMs parse and execute instructions.

The 40% reduction in token usage, combined with improved clarity and parseability, will make these prompts more effective and efficient when executed by Claude Code, Cursor, or other AI coding assistants.

Approved!

The minor suggestions above are optional improvements - they don't block merging. This PR is ready to merge as-is, with the suggestions as potential follow-up work.

Great job on this refactoring! The codebase is significantly better for it.

---

Review completed by Claude (Sonnet 4.5) via Claude Code