Global LLM Rules for WordPress Development

AI Assistant Communication Style

🤝 Planning & Requirements Gathering

When gathering requirements for complex features:

✅ DO:

• Ask questions one at a time - Makes decisions easier to process
• Order questions by significance - Foundational decisions first
• Provide overall recommendation per question - Help guide decisions
• Show how answers affect subsequent decisions - Context matters
• Summarize all decisions before implementation - Confirm understanding
• Present clear options with pros/cons - Informed decision-making

❌ DON'T:

• Present all questions simultaneously - Overwhelming
• Ask in random order - Dependencies matter
• Skip recommendations - Provide expertise
• Proceed without clear answers - Assumptions cause problems
• Make decisions without user input - Collaboration is key

Question Flow Pattern:

1. Ask most impactful question first
2. Wait for answer
3. Adjust subsequent questions based on answer
4. Continue until all information gathered
5. Present complete summary
6. Confirm before implementation

Example:

Q1: What is the source of truth? (Affects all automation)
  → Answer determines Q2 approach
Q2: How should docs be organized? (Affects navigation)
  → Answer determines Q3 scope
Q3: What level of automation? (Affects workflow)
  → Continue...

💬 Emoji Usage Guidelines

Use emojis strategically for visual categorization and quick comprehension:

Section Headers:

• 🎯 Goals/Objectives
• 📦 Components/Packages
• 🛠️ Tools/Scripts
• 📁 File Structure
• 🚀 Deployment/Release
• 📝 Documentation
• ✅ Success/Completed
• ⚠️ Warnings/Important
• 🔄 Updates/Changes
• 💡 Tips/Suggestions
• 🐛 Bugs/Issues
• ⚡ Performance
• 🎨 Styling/UI
• 🔒 Security
• ♿ Accessibility

Status Indicators:

• ✅ Complete/Working
• ⏳ In Progress
• ❌ Failed/Error
• 🟡 Warning/Caution
• 🔵 Information

Best Practices:

• Use emojis to help users quickly scan responses
• Categorize different types of information
• Make documentation more engaging
• Provide visual hierarchy
• Keep it professional (one emoji per section/category)
• Avoid emoji chains (❌ Don't do: ✅🎯🚀)

WordPress Theme Development Standards

🎨 PHP Coding Standards

• Follow WordPress Coding Standards
• Use WordPress functions over native PHP when available
• Always sanitize input and escape output
• Use wp_enqueue_script() and wp_enqueue_style() for assets
• Prefix all custom functions with theme identifier
• Use WordPress hooks and filters appropriately

📝 JavaScript Standards

• Use modern ES6+ syntax
• Implement debug logging system for development
• Minimize console output in production
• Handle errors gracefully
• Comment complex logic

📂 General File Organization Principles

• Organize by feature/functionality
• Keep related files together
• Use clear, descriptive naming conventions
• Separate concerns (templates, styles, scripts)
• Follow WordPress theme structure conventions

🔄 Template Hierarchy Best Practices

• Follow WordPress template hierarchy
• Use get_template_part() for reusable components
• Keep templates focused and modular
• Document template usage

Documentation Standards

📋 CHANGELOG.md Updates

• ALWAYS update CHANGELOG.md for significant changes
• Use Keep a Changelog format
• Credit changes with author and date
• Categories: Added, Changed, Fixed, Deprecated, Removed, Security

Format Example:

## [Version] - YYYY-MM-DD

### Added
- New feature description (@author)

### Changed
- Modified behavior description (@author)

### Fixed
- Bug fix description (@author)

📊 Executive Summary Updates

• ALWAYS update executiveSummary.md alongside CHANGELOG.md
• Use simple, non-technical language suitable for executive reporting
• Focus on business impact and user benefits, not technical implementation
• Each entry should answer: "What was improved and why does it matter?"
• Keep summaries concise (2-3 sentences maximum per change)
• Group related changes together for clarity

Format Example:

## Recent Improvements

******Feature Name****** (YYYY-MM-DD)
Business-focused description of what changed and why it matters to users or the business.

💬 Inline Comments

• Document complex logic with clear comments
• Explain "why" not just "what"
• Use PHP DocBlocks for functions
• Keep comments up-to-date with code changes

📖 Memory Bank Updates

• Update project memory bank for architectural decisions
• Document integration patterns
• Record problem-solving approaches
• Maintain project context

📝 Commit Messages

• Use clear, descriptive commit messages
• Reference issue numbers when applicable
• Follow conventional commits format when possible
• Keep commits atomic and focused

Code Quality Requirements

✅ Error Handling

• Always include error handling in PHP functions
• Use try-catch blocks for external API calls
• Provide fallback content for failed operations
• Log errors appropriately (avoid exposing in production)

🔒 Security

• Sanitize all user inputs
• Escape all outputs
• Use nonces for forms
• Check user capabilities before privileged operations
• Never trust client-side data
• Follow WordPress security best practices

⚡ Performance

• Optimize font loading (preconnect, font-display: swap)
• Minimize HTTP requests
• Use caching where appropriate
• Lazy load images when possible
• Minimize JavaScript execution time
• Optimize database queries
• Use transients for expensive operations

♿ Accessibility

• Use semantic HTML
• Include ARIA labels where needed
• Ensure keyboard navigation works
• Maintain color contrast ratios (WCAG AA minimum)
• Test with screen readers
• Provide alt text for images
• Ensure forms are properly labeled

📱 Responsive Design

• Mobile-first approach
• Test on various screen sizes
• Use appropriate breakpoints
• Ensure touch targets are adequate size (44x44px minimum)
• Test on real devices when possible

Testing Requirements

✅ Before Committing

• Test functionality in local environment
• Check browser console for errors
• Verify mobile responsiveness
• Test cross-browser compatibility
• Confirm no PHP errors in debug log
• Run any available automated tests

🧪 Regression Testing

• Verify related functionality still works
• Test common user flows
• Check integration points
• Validate form submissions
• Test with different user roles/permissions

🔍 Code Review Checklist

• Code follows WordPress coding standards
• Security best practices implemented
• Performance considerations addressed
• Accessibility requirements met
• Documentation is complete and accurate
• Tests pass successfully

Deployment Standards

🚀 Pre-Deployment Checklist

• All changes documented in CHANGELOG.md
• Executive summary updated
• Local testing completed successfully
• No console errors in production mode
• Debug logging disabled by default
• Code reviewed and approved
• Git commit with clear message
• Dependencies updated if needed

⚠️ Post-Deployment Verification

• Check live site loads correctly
• Verify all functionality works as expected
• Monitor error logs
• Check performance metrics
• Test critical user flows
• Verify third-party integrations

🔄 Rollback Plan

• Have a rollback strategy ready
• Keep previous version accessible
• Document rollback procedures
• Test rollback process periodically

---

Notes for Implementation

After moving this content to your Gist:

1. Test that the fetch mechanism works in a new Cline conversation
2. If fetch fails, you'll be prompted to paste the Gist content
3. Project-specific rules in .clinerules will supplement these global rules
4. Update the Gist URL in .clinerules if you change the Gist location