forked from jsnbuchanan/crowd-funder-for-time-pwa
Merge branch 'master' into dialog-notification-z-index
This commit is contained in:
Jose Olarte III
336
doc/README-BUILD-GUARD.md
Normal file
336
doc/README-BUILD-GUARD.md
Normal file
@@ -0,0 +1,336 @@
|
||||
# Build Architecture Guard - Husky Implementation
|
||||
|
||||
## Overview
|
||||
|
||||
The Build Architecture Guard protects your build system by enforcing
|
||||
documentation requirements through **Git hooks**. When you modify
|
||||
build-critical files, the system automatically blocks commits/pushes
|
||||
until you update `BUILDING.md`.
|
||||
|
||||
## 🎯 **Why Husky-Only?**
|
||||
|
||||
**Advantages:**
|
||||
|
||||
- ✅ **Immediate feedback** - Hooks run before commit/push
|
||||
- ✅ **Works everywhere** - No server-side CI/CD required
|
||||
- ✅ **Simple setup** - One tool, one configuration
|
||||
- ✅ **Fast execution** - No network delays or server queues
|
||||
- ✅ **Offline support** - Works without internet connection
|
||||
|
||||
**Trade-offs:**
|
||||
|
||||
- ⚠️ **Can be bypassed** - `git commit --no-verify` or `git push --no-verify`
|
||||
- ⚠️ **Developer discipline** - Relies on team following the rules
|
||||
|
||||
## 🏗️ **Architecture**
|
||||
|
||||
```bash
|
||||
Developer Workflow:
|
||||
1. Modify build files (scripts/, vite.config.*, etc.)
|
||||
2. Try to commit → Husky pre-commit hook runs
|
||||
3. Guard script checks if BUILDING.md was updated
|
||||
4. ✅ Commit succeeds if docs updated
|
||||
5. ❌ Commit blocked if docs missing
|
||||
```
|
||||
|
||||
## 🚀 **Quick Start**
|
||||
|
||||
### 1. Install Dependencies
|
||||
|
||||
```bash
|
||||
npm install
|
||||
npm run prepare # Sets up Husky hooks
|
||||
```
|
||||
|
||||
### 2. Test the System
|
||||
|
||||
```bash
|
||||
# Modify a build file without updating BUILDING.md
|
||||
echo "# test" >> scripts/test.sh
|
||||
|
||||
# Try to commit (should be blocked)
|
||||
git add scripts/test.sh
|
||||
git commit -m "test: add build script"
|
||||
# ❌ Hook blocks commit with helpful message
|
||||
```
|
||||
|
||||
### 3. Fix and Retry
|
||||
|
||||
```bash
|
||||
# Update BUILDING.md with your changes
|
||||
echo "## New Build Script" >> BUILDING.md
|
||||
echo "Added test.sh for testing purposes" >> BUILDING.md
|
||||
|
||||
# Now commit should succeed
|
||||
git add BUILDING.md
|
||||
git commit -m "feat: add test build script with docs"
|
||||
# ✅ Commit succeeds
|
||||
```
|
||||
|
||||
## 🔧 **How It Works**
|
||||
|
||||
### Pre-commit Hook (`.husky/pre-commit`)
|
||||
|
||||
- **When**: Every `git commit`
|
||||
- **What**: Runs `./scripts/build-arch-guard.sh --staged`
|
||||
- **Result**: Blocks commit if build files changed without BUILDING.md update
|
||||
|
||||
### Pre-push Hook (`.husky/pre-push`)
|
||||
|
||||
- **When**: Every `git push`
|
||||
- **What**: Runs `./scripts/build-arch-guard.sh --range`
|
||||
- **Result**: Blocks push if commits contain undocumented build changes
|
||||
|
||||
### Guard Script (`scripts/build-arch-guard.sh`)
|
||||
|
||||
- **Detects**: Changes to build-sensitive file patterns
|
||||
- **Validates**: BUILDING.md was updated alongside changes
|
||||
- **Reports**: Clear error messages with guidance
|
||||
|
||||
## 📁 **Protected File Patterns**
|
||||
|
||||
The guard script monitors these paths for changes:
|
||||
|
||||
```text
|
||||
Build Configuration:
|
||||
├── vite.config.* # Vite configuration
|
||||
├── capacitor.config.ts # Capacitor configuration
|
||||
├── package.json # Package configuration
|
||||
├── package-lock.json # Lock files
|
||||
├── yarn.lock
|
||||
└── pnpm-lock.yaml
|
||||
|
||||
Build Scripts:
|
||||
├── scripts/** # All build and automation scripts
|
||||
├── electron/** # Electron build files
|
||||
├── android/** # Android build configuration
|
||||
├── ios/** # iOS build configuration
|
||||
├── sw_scripts/** # Service worker scripts
|
||||
└── sw_combine.js # Service worker combination
|
||||
|
||||
Deployment:
|
||||
├── Dockerfile # Docker configuration
|
||||
└── docker/** # Docker services
|
||||
```
|
||||
|
||||
## 🎭 **Usage Scenarios**
|
||||
|
||||
### Scenario 1: Adding a New Build Script
|
||||
|
||||
```bash
|
||||
# ❌ This will be blocked
|
||||
echo '#!/bin/bash' > scripts/new-build.sh
|
||||
git add scripts/new-build.sh
|
||||
git commit -m "feat: add new build script"
|
||||
# Hook blocks: "Build-sensitive files changed but BUILDING.md not updated"
|
||||
|
||||
# ✅ This will succeed
|
||||
echo '#!/bin/bash' > scripts/new-build.sh
|
||||
echo '## New Build Script' >> BUILDING.md
|
||||
echo 'Added new-build.sh for feature X' >> BUILDING.md
|
||||
git add scripts/new-build.sh BUILDING.md
|
||||
git commit -m "feat: add new build script with docs"
|
||||
# ✅ Commit succeeds
|
||||
```
|
||||
|
||||
### Scenario 2: Updating Vite Configuration
|
||||
|
||||
```bash
|
||||
# ❌ This will be blocked
|
||||
echo 'export default { newOption: true }' >> vite.config.ts
|
||||
git add vite.config.ts
|
||||
git commit -m "config: add new vite option"
|
||||
# Hook blocks: "Build-sensitive files changed but BUILDING.md not updated"
|
||||
|
||||
# ✅ This will succeed
|
||||
echo 'export default { newOption: true }' >> vite.config.ts
|
||||
echo '### New Vite Option' >> BUILDING.md
|
||||
echo 'Added newOption for improved performance' >> BUILDING.md
|
||||
git add vite.config.ts BUILDING.md
|
||||
git commit -m "config: add new vite option with docs"
|
||||
# ✅ Commit succeeds
|
||||
```
|
||||
|
||||
## 🚨 **Emergency Bypass**
|
||||
|
||||
**⚠️ Use sparingly and only for emergencies:**
|
||||
|
||||
```bash
|
||||
# Skip pre-commit hook
|
||||
git commit -m "emergency: critical fix" --no-verify
|
||||
|
||||
# Skip pre-push hook
|
||||
git push --no-verify
|
||||
|
||||
# Remember to update BUILDING.md later!
|
||||
```
|
||||
|
||||
## 🔍 **Troubleshooting**
|
||||
|
||||
### Hooks Not Running
|
||||
|
||||
```bash
|
||||
# Reinstall hooks
|
||||
npm run prepare
|
||||
|
||||
# Check hook files exist and are executable
|
||||
ls -la .husky/
|
||||
chmod +x .husky/*
|
||||
|
||||
# Verify Git hooks path
|
||||
git config core.hooksPath
|
||||
# Should show: .husky
|
||||
```
|
||||
|
||||
### Guard Script Issues
|
||||
|
||||
```bash
|
||||
# Test guard script manually
|
||||
./scripts/build-arch-guard.sh --help
|
||||
|
||||
# Check script permissions
|
||||
chmod +x scripts/build-arch-guard.sh
|
||||
|
||||
# Test with specific files
|
||||
./scripts/build-arch-guard.sh --staged
|
||||
```
|
||||
|
||||
### False Positives
|
||||
|
||||
```bash
|
||||
# If guard blocks legitimate changes, check:
|
||||
# 1. Are you modifying a protected file pattern?
|
||||
# 2. Did you update BUILDING.md?
|
||||
# 3. Is BUILDING.md staged for commit?
|
||||
|
||||
# View what the guard sees
|
||||
git diff --name-only --cached
|
||||
```
|
||||
|
||||
## 📋 **Best Practices**
|
||||
|
||||
### For Developers
|
||||
|
||||
1. **Update BUILDING.md first** - Document changes before implementing
|
||||
2. **Test locally** - Run `./scripts/build-arch-guard.sh --staged` before committing
|
||||
3. **Use descriptive commits** - Include context about build changes
|
||||
4. **Don't bypass lightly** - Only use `--no-verify` for true emergencies
|
||||
|
||||
### For Teams
|
||||
|
||||
1. **Document the system** - Ensure everyone understands the guard
|
||||
2. **Review BUILDING.md updates** - Verify documentation quality
|
||||
3. **Monitor bypass usage** - Track when hooks are skipped
|
||||
4. **Regular audits** - Check that BUILDING.md stays current
|
||||
|
||||
### For Maintainers
|
||||
|
||||
1. **Update protected patterns** - Modify `scripts/build-arch-guard.sh` as needed
|
||||
2. **Monitor effectiveness** - Track how often the guard catches issues
|
||||
3. **Team training** - Help developers understand the system
|
||||
4. **Continuous improvement** - Refine patterns and error messages
|
||||
|
||||
## 🚨 **Troubleshooting**
|
||||
|
||||
### Common Issues
|
||||
|
||||
#### mapfile Command Not Found
|
||||
|
||||
**Problem**: Pre-commit hook fails with `mapfile: command not found`
|
||||
|
||||
**Cause**: The `mapfile` command is bash-specific and not available in all shell environments
|
||||
|
||||
**Solution**: The script has been updated to use portable alternatives. If you encounter this issue:
|
||||
|
||||
```bash
|
||||
# Verify the script is executable
|
||||
chmod +x scripts/build-arch-guard.sh
|
||||
|
||||
# Test the script directly
|
||||
./scripts/build-arch-guard.sh --help
|
||||
|
||||
# Check your shell environment
|
||||
echo $SHELL
|
||||
bash --version
|
||||
```
|
||||
|
||||
**Prevention**: Ensure your development environment uses bash and the script has proper permissions
|
||||
|
||||
### False Positives
|
||||
|
||||
```bash
|
||||
# If guard blocks legitimate changes, check:
|
||||
# 1. Are you modifying a protected file pattern?
|
||||
# 2. Did you update BUILDING.md?
|
||||
# 3. Is BUILDING.md staged for commit?
|
||||
|
||||
# View what the guard sees
|
||||
git diff --name-only --cached
|
||||
```
|
||||
|
||||
## 🔄 **Customization**
|
||||
|
||||
### Adding New Protected Paths
|
||||
|
||||
Edit `scripts/build-arch-guard.sh`:
|
||||
|
||||
```bash
|
||||
SENSITIVE=(
|
||||
# ... existing patterns ...
|
||||
"new-pattern/**" # Add your new pattern
|
||||
"*.config.js" # Add file extensions
|
||||
)
|
||||
```
|
||||
|
||||
### Modifying Error Messages
|
||||
|
||||
Edit the guard script to customize:
|
||||
|
||||
- Error message content
|
||||
- File pattern matching
|
||||
- Documentation requirements
|
||||
- Bypass instructions
|
||||
|
||||
### Adding New Validation Rules
|
||||
|
||||
Extend the guard script to check for:
|
||||
|
||||
- Specific file content patterns
|
||||
- Required documentation sections
|
||||
- Commit message formats
|
||||
- Branch naming conventions
|
||||
|
||||
## 📚 **Integration with PR Template**
|
||||
|
||||
The `pull_request_template.md` works with this system by:
|
||||
|
||||
- **Guiding developers** through required documentation
|
||||
- **Ensuring consistency** across all build changes
|
||||
- **Providing checklist** for comprehensive updates
|
||||
- **Supporting L1/L2/L3** change classification
|
||||
|
||||
## 🎯 **Success Metrics**
|
||||
|
||||
Track the effectiveness of your Build Architecture Guard:
|
||||
|
||||
- **Hook execution rate** - How often hooks run successfully
|
||||
- **Bypass frequency** - How often `--no-verify` is used
|
||||
- **Documentation quality** - BUILDING.md stays current
|
||||
- **Build failures** - Fewer issues from undocumented changes
|
||||
- **Team adoption** - Developers follow the process
|
||||
|
||||
---
|
||||
|
||||
**Status**: Active protection system
|
||||
**Architecture**: Client-side Git hooks only
|
||||
**Dependencies**: Husky, Git, Bash
|
||||
**Maintainer**: Development team
|
||||
**Related**: `pull_request_template.md`, `scripts/build-arch-guard.sh`
|
||||
|
||||
## 📝 **Changelog**
|
||||
|
||||
### 2025-08-22 - Shell Compatibility Fix
|
||||
- **Fixed**: Replaced `mapfile` command with portable alternative for cross-shell compatibility
|
||||
- **Impact**: Resolves "mapfile: command not found" errors in pre-commit hooks
|
||||
- **Files**: `scripts/build-arch-guard.sh`
|
||||
- **Testing**: Script now works across different shell environments
|
||||
238
doc/android-asset-validation.md
Normal file
238
doc/android-asset-validation.md
Normal file
@@ -0,0 +1,238 @@
|
||||
# Android Asset Validation System
|
||||
|
||||
**Author**: Matthew Raymer
|
||||
**Date**: 2025-08-22
|
||||
**Status**: 🎯 **ACTIVE** - Production Ready
|
||||
|
||||
## Overview
|
||||
|
||||
The Android Asset Validation System automatically detects and fixes missing Android resources before building, preventing common build failures related to missing splash screens and app icons.
|
||||
|
||||
## Problem Solved
|
||||
|
||||
Previously, Android builds would fail with errors like:
|
||||
```
|
||||
error: resource drawable/splash (aka app.timesafari.app:drawable/splash) not found.
|
||||
error: resource mipmap/ic_launcher (aka app.timesafari.app:mipmap/ic_launcher) not found.
|
||||
```
|
||||
|
||||
This happened when:
|
||||
- Source assets existed but weren't generated into Android resources
|
||||
- Android resource directories were missing
|
||||
- Asset generation tools weren't run before building
|
||||
|
||||
## Solution
|
||||
|
||||
### Enhanced Build Script Validation
|
||||
|
||||
The `scripts/build-android.sh` script now includes comprehensive asset validation that:
|
||||
|
||||
1. **Checks Source Assets**: Validates that required source files exist in `resources/`
|
||||
2. **Checks Android Resources**: Verifies that generated Android resources exist
|
||||
3. **Auto-Regenerates**: Automatically regenerates missing resources when detected
|
||||
4. **Verifies Results**: Confirms that regeneration was successful
|
||||
|
||||
### Validation Process
|
||||
|
||||
```bash
|
||||
# Validates and regenerates if needed
|
||||
npm run assets:validate:android
|
||||
|
||||
# Full build with validation
|
||||
npm run build:android:studio
|
||||
```
|
||||
|
||||
### What Gets Validated
|
||||
|
||||
#### Source Assets (Required)
|
||||
- `resources/icon.png` - App icon source
|
||||
- `resources/splash.png` - Splash screen source
|
||||
- `resources/splash_dark.png` - Dark mode splash source
|
||||
|
||||
#### Android Resources (Generated)
|
||||
- `android/app/src/main/res/drawable/splash.png` - Splash screen drawable
|
||||
- `android/app/src/main/res/mipmap-*/ic_launcher.png` - App icons for all densities
|
||||
- `android/app/src/main/res/mipmap-*/ic_launcher_round.png` - Round app icons for all densities
|
||||
|
||||
### Density Levels Checked
|
||||
- `mipmap-mdpi` (1x)
|
||||
- `mipmap-hdpi` (1.5x)
|
||||
- `mipmap-xhdpi` (2x)
|
||||
- `mipmap-xxhdpi` (3x)
|
||||
- `mipmap-xxxhdpi` (4x)
|
||||
|
||||
## Usage
|
||||
|
||||
### Automatic Validation (Recommended)
|
||||
The validation runs automatically during all Android builds:
|
||||
|
||||
```bash
|
||||
# Development build with validation
|
||||
npm run build:android:studio
|
||||
|
||||
# Production build with validation
|
||||
npm run build:android:prod
|
||||
|
||||
# Debug build with validation
|
||||
npm run build:android:debug
|
||||
```
|
||||
|
||||
### Manual Validation
|
||||
Run validation only to check/fix assets:
|
||||
|
||||
```bash
|
||||
# Validate and regenerate if needed
|
||||
npm run assets:validate:android
|
||||
|
||||
# Alternative command
|
||||
./scripts/build-android.sh --assets-only
|
||||
```
|
||||
|
||||
### Validation Only (No Regeneration)
|
||||
Check configuration without fixing:
|
||||
|
||||
```bash
|
||||
npm run assets:validate
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Missing Source Assets
|
||||
If source assets are missing, the build fails with clear error messages:
|
||||
|
||||
```
|
||||
[ERROR] Missing source assets:
|
||||
[ERROR] - resources/icon.png
|
||||
[ERROR] - resources/splash.png
|
||||
[ERROR] Please ensure all required assets are present in the resources/ directory.
|
||||
```
|
||||
|
||||
### Missing Generated Resources
|
||||
If generated resources are missing, they're automatically regenerated:
|
||||
|
||||
```
|
||||
[WARN] Missing Android resources detected:
|
||||
[WARN] - drawable/splash.png
|
||||
[WARN] - mipmap-mdpi/ic_launcher.png
|
||||
[INFO] Regenerating Android assets...
|
||||
[SUCCESS] Android assets regenerated successfully
|
||||
```
|
||||
|
||||
### Generation Failure
|
||||
If regeneration fails, helpful guidance is provided:
|
||||
|
||||
```
|
||||
[ERROR] Failed to generate Android assets
|
||||
[INFO] You may need to manually create the missing resources:
|
||||
[INFO] - android/app/src/main/res/drawable/splash.png
|
||||
[INFO] - android/app/src/main/res/mipmap-mdpi/ic_launcher.png
|
||||
```
|
||||
|
||||
## Integration Points
|
||||
|
||||
### Build Script Integration
|
||||
The validation is integrated into the main build process:
|
||||
|
||||
```bash
|
||||
# In scripts/build-android.sh
|
||||
validate_dependencies
|
||||
validate_android_assets || {
|
||||
log_error "Android asset validation failed. Please fix the issues above and try again."
|
||||
exit 9
|
||||
}
|
||||
```
|
||||
|
||||
### NPM Scripts
|
||||
New npm scripts for asset management:
|
||||
|
||||
```json
|
||||
{
|
||||
"assets:validate": "npx tsx scripts/assets-validator.ts",
|
||||
"assets:validate:android": "./scripts/build-android.sh --assets-only",
|
||||
"assets:clean": "rimraf android/app/src/main/res/mipmap-* ios/App/App/Assets.xcassets/**/AppIcon*.png ios/App/App/Assets.xcassets/**/Splash*.png || true"
|
||||
}
|
||||
```
|
||||
|
||||
## Benefits
|
||||
|
||||
### For Developers
|
||||
- **No More Build Failures**: Automatic detection and fixing of missing resources
|
||||
- **Faster Development**: No need to manually run asset generation tools
|
||||
- **Clear Error Messages**: Helpful guidance when issues occur
|
||||
- **Consistent Results**: Same validation on all development machines
|
||||
|
||||
### For CI/CD
|
||||
- **Reliable Builds**: Consistent asset validation across environments
|
||||
- **Early Detection**: Catches issues before they reach production
|
||||
- **Automated Fixes**: Self-healing builds when possible
|
||||
|
||||
### For Project Maintenance
|
||||
- **Reduced Support**: Fewer "build doesn't work" issues
|
||||
- **Documentation**: Clear requirements for required assets
|
||||
- **Standardization**: Consistent asset structure across the project
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
#### "No assets found in the asset path"
|
||||
This occurs when the `assets/` directory is empty. The validation system automatically copies source assets and regenerates them.
|
||||
|
||||
#### "Failed to generate Android assets"
|
||||
Check that:
|
||||
- Source assets exist in `resources/`
|
||||
- `@capacitor/assets` is installed
|
||||
- You have write permissions to the Android directories
|
||||
|
||||
#### "Asset generation completed but some resources are still missing"
|
||||
This indicates a problem with the asset generation tool. Try:
|
||||
1. Running `npm install` to ensure dependencies are up to date
|
||||
2. Manually running `npx @capacitor/assets generate`
|
||||
3. Checking the asset generation logs for specific errors
|
||||
|
||||
### Manual Recovery
|
||||
If automatic regeneration fails, you can manually create the missing resources:
|
||||
|
||||
```bash
|
||||
# Create missing directories
|
||||
mkdir -p android/app/src/main/res/drawable
|
||||
mkdir -p android/app/src/main/res/mipmap-{mdpi,hdpi,xhdpi,xxhdpi,xxxhdpi}
|
||||
|
||||
# Copy source assets to assets directory
|
||||
cp resources/icon.png assets/
|
||||
cp resources/splash.png assets/
|
||||
cp resources/splash_dark.png assets/
|
||||
|
||||
# Generate assets manually
|
||||
npx @capacitor/assets generate
|
||||
|
||||
# Clean up
|
||||
rm assets/icon.png assets/splash.png assets/splash_dark.png
|
||||
```
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
### Planned Improvements
|
||||
- **iOS Asset Validation**: Extend validation to iOS assets
|
||||
- **Asset Quality Checks**: Validate image dimensions and formats
|
||||
- **Performance Optimization**: Cache validation results
|
||||
- **CI/CD Integration**: Add validation to GitHub Actions
|
||||
|
||||
### Configuration Options
|
||||
- **Custom Asset Paths**: Support for different asset directory structures
|
||||
- **Validation Rules**: Configurable validation requirements
|
||||
- **Skip Options**: Ability to skip validation for specific scenarios
|
||||
|
||||
## References
|
||||
|
||||
- [Capacitor Assets Documentation](https://github.com/ionic-team/capacitor-assets)
|
||||
- [Android Resource System](https://developer.android.com/guide/topics/resources/providing-resources)
|
||||
- [Build Script Documentation](./build-android.sh)
|
||||
- [Asset Configuration](./capacitor-assets.config.json)
|
||||
|
||||
---
|
||||
|
||||
**Status**: Active validation system
|
||||
**Priority**: High
|
||||
**Maintainer**: Development team
|
||||
**Next Review**: 2025-09-22
|
||||
272
doc/meta_rule_usage_guide.md
Normal file
272
doc/meta_rule_usage_guide.md
Normal file
@@ -0,0 +1,272 @@
|
||||
# Meta-Rule Usage Guide: How to Use Meta-Rules in Practice
|
||||
|
||||
**Author**: Matthew Raymer
|
||||
**Date**: 2025-08-21
|
||||
**Status**: 🎯 **ACTIVE** - Comprehensive meta-rule usage guide
|
||||
|
||||
## Overview
|
||||
|
||||
This guide explains how to use the TimeSafari meta-rule system in practice.
|
||||
Meta-rules are high-level rule bundles that provide workflow-specific guidance
|
||||
for different types of tasks.
|
||||
|
||||
**Educational Goal**: Help developers understand when and how to apply
|
||||
meta-rules to maximize their effectiveness and avoid common mistakes.
|
||||
|
||||
## Why Meta-Rules Matter
|
||||
|
||||
**Meta-rules solve the problem of rule overload** by bundling related rules
|
||||
into logical workflows. Instead of manually selecting 10+ individual rules,
|
||||
you apply 1-3 meta-rules that automatically include everything you need.
|
||||
|
||||
### **Benefits of Using Meta-Rules**
|
||||
|
||||
- **Faster Setup**: No need to manually select individual rules
|
||||
- **Better Coverage**: Ensures you don't miss important rules
|
||||
- **Workflow Consistency**: Standardized approaches across the team
|
||||
- **Learning Efficiency**: Learn workflows, not individual rules
|
||||
- **Quality Assurance**: Built-in validation and feedback mechanisms
|
||||
|
||||
## Meta-Rule Selection Strategy
|
||||
|
||||
### **Step 1: Always Start with Core Always-On**
|
||||
|
||||
**Every single interaction** starts with:
|
||||
```
|
||||
meta_core_always_on.mdc
|
||||
```
|
||||
|
||||
This provides the foundation: human competence principles, time standards,
|
||||
version control, and application context.
|
||||
|
||||
### **Step 2: Identify Your Primary Task Type**
|
||||
|
||||
Choose the meta-rule that matches your main objective:
|
||||
|
||||
| **Task Type** | **Primary Meta-Rule** | **When to Use** |
|
||||
|---------------|------------------------|------------------|
|
||||
| **Research/Investigation** | `meta_research.mdc` | Bug diagnosis, feasibility research, code analysis |
|
||||
| **Feature Planning** | `meta_feature_planning.mdc` | New feature design, requirements analysis |
|
||||
| **Feature Implementation** | `meta_feature_implementation.mdc` | Building features, coding, testing |
|
||||
| **Bug Diagnosis** | `meta_bug_diagnosis.mdc` | Investigating issues, root cause analysis |
|
||||
| **Bug Fixing** | `meta_bug_fixing.mdc` | Implementing fixes, validation |
|
||||
| **Documentation** | `meta_documentation.mdc` | Writing docs, creating guides, tutorials |
|
||||
|
||||
### **Step 3: Add Context-Specific Meta-Rules (Optional)**
|
||||
|
||||
For complex tasks, you might combine multiple meta-rules:
|
||||
|
||||
```
|
||||
meta_core_always_on + meta_research + meta_bug_diagnosis
|
||||
```
|
||||
|
||||
## Practical Usage Examples
|
||||
|
||||
### **Example 1: Bug Investigation**
|
||||
|
||||
**Scenario**: User reports that the contact list isn't loading properly
|
||||
|
||||
**Meta-Rule Selection**:
|
||||
```
|
||||
meta_core_always_on + meta_research + meta_bug_diagnosis
|
||||
```
|
||||
|
||||
**What This Gives You**:
|
||||
- **Core Always-On**: Human competence focus, time standards, context
|
||||
- **Research**: Systematic investigation methodology, evidence collection
|
||||
- **Bug Diagnosis**: Defect analysis framework, root cause identification
|
||||
|
||||
**Workflow**:
|
||||
1. Apply core always-on for foundation
|
||||
2. Use research meta-rule for systematic investigation
|
||||
3. Apply bug diagnosis for defect analysis
|
||||
4. Follow the bundled workflow automatically
|
||||
|
||||
### **Example 2: Feature Development**
|
||||
|
||||
**Scenario**: Building a new contact search feature
|
||||
|
||||
**Meta-Rule Selection**:
|
||||
```
|
||||
meta_core_always_on + meta_feature_planning + meta_feature_implementation
|
||||
```
|
||||
|
||||
**What This Gives You**:
|
||||
- **Core Always-On**: Foundation principles and context
|
||||
- **Feature Planning**: Requirements analysis, architecture planning
|
||||
- **Feature Implementation**: Development workflow, testing strategy
|
||||
|
||||
**Workflow**:
|
||||
1. Start with core always-on
|
||||
2. Use feature planning for design and requirements
|
||||
3. Switch to feature implementation for coding and testing
|
||||
|
||||
### **Example 3: Documentation Creation**
|
||||
|
||||
**Scenario**: Writing a migration guide for the new database system
|
||||
|
||||
**Meta-Rule Selection**:
|
||||
```
|
||||
meta_core_always_on + meta_documentation
|
||||
```
|
||||
|
||||
**What This Gives You**:
|
||||
- **Core Always-On**: Foundation and context
|
||||
- **Documentation**: Educational focus, templates, quality standards
|
||||
|
||||
**Workflow**:
|
||||
1. Apply core always-on for foundation
|
||||
2. Use documentation meta-rule for educational content creation
|
||||
3. Follow educational templates and quality standards
|
||||
|
||||
## Meta-Rule Application Process
|
||||
|
||||
### **1. Load the Meta-Rule**
|
||||
|
||||
When you start a task, explicitly state which meta-rules you're applying:
|
||||
|
||||
```
|
||||
"I'm applying meta_core_always_on + meta_research for this bug investigation."
|
||||
```
|
||||
|
||||
### **2. Follow the Bundled Workflow**
|
||||
|
||||
Each meta-rule provides a complete workflow. Follow it step-by-step:
|
||||
|
||||
- **Research Meta-Rule**: Investigation → Evidence → Analysis → Conclusion
|
||||
- **Feature Planning**: Requirements → Architecture → Strategy → Validation
|
||||
- **Bug Diagnosis**: Problem → Evidence → Root Cause → Solution
|
||||
|
||||
### **3. Use the Bundled Rules**
|
||||
|
||||
Meta-rules automatically include all necessary sub-rules. You don't need to
|
||||
manually select individual rules - they're already bundled.
|
||||
|
||||
### **4. Validate Against Success Criteria**
|
||||
|
||||
Each meta-rule includes success criteria. Use these to validate your work:
|
||||
|
||||
- [ ] **Educational Quality**: Content increases human competence
|
||||
- [ ] **Technical Quality**: All technical details are accurate
|
||||
- [ ] **Workflow Completion**: All required steps completed
|
||||
- [ ] **Quality Standards**: Meets defined quality criteria
|
||||
|
||||
## Common Meta-Rule Combinations
|
||||
|
||||
### **Research + Diagnosis**
|
||||
```
|
||||
meta_core_always_on + meta_research + meta_bug_diagnosis
|
||||
```
|
||||
**Use for**: Complex bug investigations requiring systematic analysis
|
||||
|
||||
### **Planning + Implementation**
|
||||
```
|
||||
meta_core_always_on + meta_feature_planning + meta_feature_implementation
|
||||
```
|
||||
**Use for**: End-to-end feature development from concept to deployment
|
||||
|
||||
### **Research + Planning**
|
||||
```
|
||||
meta_core_always_on + meta_research + meta_feature_planning
|
||||
```
|
||||
**Use for**: Feasibility research and solution design
|
||||
|
||||
### **Documentation + Context**
|
||||
```
|
||||
meta_core_always_on + meta_documentation + [context-specific]
|
||||
```
|
||||
**Use for**: Creating comprehensive, educational documentation
|
||||
|
||||
## Best Practices
|
||||
|
||||
### **✅ Do These Things**
|
||||
|
||||
- **Always start with core always-on** - it's the foundation
|
||||
- **Choose the primary meta-rule** that matches your main task
|
||||
- **Follow the bundled workflow** step-by-step
|
||||
- **Use success criteria** to validate your work
|
||||
- **Collect feedback** on meta-rule effectiveness
|
||||
|
||||
### **❌ Avoid These Mistakes**
|
||||
|
||||
- **Don't skip core always-on** - you'll lose the foundation
|
||||
- **Don't apply too many meta-rules** - stick to 2-3 maximum
|
||||
- **Don't ignore the bundled workflow** - follow it systematically
|
||||
- **Don't forget validation** - use the success criteria
|
||||
- **Don't skip feedback collection** - it improves the system
|
||||
|
||||
## Troubleshooting Common Issues
|
||||
|
||||
### **Problem**: Meta-rules seem to conflict
|
||||
|
||||
**Solution**: Meta-rules are designed to work together. If you see conflicts,
|
||||
you're probably applying too many. Stick to 2-3 meta-rules maximum.
|
||||
|
||||
### **Problem**: I don't know which meta-rule to use
|
||||
|
||||
**Solution**: Start with your primary task type. If you're investigating a bug,
|
||||
use research + bug diagnosis. If you're building a feature, use feature
|
||||
planning + implementation.
|
||||
|
||||
### **Problem**: The meta-rule workflow seems too complex
|
||||
|
||||
**Solution**: Meta-rules bundle complexity into manageable workflows. Follow
|
||||
the steps one at a time. The complexity is already organized for you.
|
||||
|
||||
### **Problem**: I'm not seeing the expected behavior
|
||||
|
||||
**Solution**: Ensure you're following the meta-rule workflow step-by-step.
|
||||
Meta-rules provide guidance, but you still need to execute the workflow.
|
||||
|
||||
## Feedback and Improvement
|
||||
|
||||
### **Rate Your Experience**
|
||||
|
||||
After using a meta-rule, provide feedback:
|
||||
|
||||
- **Effectiveness**: How well did the meta-rule work? (1-5 scale)
|
||||
- **Time Saved**: How much time did it save you?
|
||||
- **Quality Improvement**: Did it improve your work quality?
|
||||
- **Recommendation**: Would you recommend it to others?
|
||||
|
||||
### **Continuous Improvement**
|
||||
|
||||
Meta-rules evolve based on feedback:
|
||||
|
||||
- **Usage patterns** - How teams use the rules
|
||||
- **Effectiveness ratings** - What works and what doesn't
|
||||
- **Integration feedback** - How well rules work together
|
||||
- **Quality metrics** - Impact on work quality
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### **Meta-Rule Selection Matrix**
|
||||
|
||||
| **Task** | **Primary** | **Secondary** | **Tertiary** |
|
||||
|----------|-------------|---------------|---------------|
|
||||
| **Bug Investigation** | `meta_research` | `meta_bug_diagnosis` | - |
|
||||
| **Feature Development** | `meta_feature_planning` | `meta_feature_implementation` | - |
|
||||
| **Documentation** | `meta_documentation` | - | - |
|
||||
| **Complex Research** | `meta_research` | `meta_bug_diagnosis` | `meta_feature_planning` |
|
||||
|
||||
### **Always Remember**
|
||||
|
||||
1. **Start with core always-on** - foundation for everything
|
||||
2. **Choose your primary meta-rule** - matches your main task
|
||||
3. **Follow the bundled workflow** - step-by-step execution
|
||||
4. **Validate against success criteria** - ensure quality
|
||||
5. **Provide feedback** - help improve the system
|
||||
|
||||
---
|
||||
|
||||
**See also**:
|
||||
|
||||
- `.cursor/rules/meta_rule_architecture.md` for meta-rule structure overview
|
||||
- `.cursor/rules/meta_core_always_on.mdc` for foundation rules
|
||||
- `.cursor/rules/README.md` for complete rule organization
|
||||
|
||||
**Status**: Active usage guide
|
||||
**Priority**: High
|
||||
**Estimated Effort**: Ongoing reference
|
||||
**Dependencies**: All meta-rules
|
||||
**Stakeholders**: Development team, Documentation team
|
||||
Reference in New Issue
Block a user