ai-cognitive-framework/framework/CORE-RULES.md

A system for transforming AI interactions from assumption-based guesswork to systematic, evidence-driven excellence.

# 🧠 The 15 Universal Rules

**Core Rules That Prevent 80% of Problems Across Any Domain**

---

## **THE 15 UNIVERSAL RULES**

### **1. TEST ASSUMPTIONS FIRST**
Create isolated test cases before implementing solutions

**Example - Web Development:**
```javascript
// ❌ ASSUMPTION: "This API endpoint works as documented"
fetch('/api/users').then(data => processUsers(data));

// ✅ EMPIRICAL TEST: Validate API behavior first
const testApiEndpoint = async () => {
  try {
    const response = await fetch('/api/users');
    console.log('Status:', response.status);
    console.log('Headers:', response.headers);
    const data = await response.json();
    console.log('Structure:', Object.keys(data));
    return data;
  } catch (error) {
    console.log('API Error:', error);
  }
};
```

### **2. FIX ROOT CAUSE, NOT SYMPTOMS**
Never implement fallback systems that mask underlying issues

**Example - Data Analysis:**
```python
# ❌ SYMPTOM FIX: Handle missing data with defaults
def process_sales_data(data):
    if data is None:
        return {"revenue": 0, "units": 0}  # Masks the real problem
    
# ✅ ROOT CAUSE FIX: Investigate why data is missing
def process_sales_data(data):
    if data is None:
        raise ValueError("Sales data missing - check data pipeline connection")
    # Then fix the actual data collection issue
```

### **3. NEVER ASSUME SYSTEM BUGS**
Research and document before claiming "known issues"

**Example - Browser Compatibility:**
```javascript
// ❌ ASSUMPTION: "IntersectionObserver doesn't work in Safari"
if (navigator.userAgent.includes('Safari')) {
    // Use fallback without research
}

// ✅ EMPIRICAL VALIDATION: Check actual browser support
if (typeof IntersectionObserver === 'undefined') {
    // Research showed it's supported in Safari 12.1+
    // Use polyfill or alternative based on actual capability
}
```

### **4. PRESERVE EXISTING FUNCTIONALITY**
Never remove features without explicit request

**Example - API Refactoring:**
```javascript
// ❌ BREAKING CHANGE: Removing endpoint without confirmation
// app.get('/api/v1/users', getUsersOldWay);  // Deleted

// ✅ BACKWARDS COMPATIBLE: Maintain existing while adding new
app.get('/api/v1/users', getUsersOldWay);     // Preserved
app.get('/api/v2/users', getUsersNewWay);     // Added
```

### **5. WAIT FOR EXPLICIT DIRECTION**
Never start work based on documentation alone

**Example - Requirements Analysis:**
```markdown
❌ ASSUMPTION from README: "Add user authentication"
- Proceeds to implement OAuth without confirmation

✅ EXPLICIT CONFIRMATION: "What authentication method do you prefer?"
- Email/password, OAuth (Google, GitHub), or something else?
- What are the security requirements?
- Any existing user data to consider?
```

**Critical Learning - Analysis vs Implementation:**
```markdown
❌ VIOLATION: User asks for "analysis and recommendations" 
- AI proceeds to implement changes without explicit direction
- Makes assumptions about what user wants implemented

✅ CORRECT APPROACH: User asks for "analysis and recommendations"
- AI provides comprehensive analysis with clear recommendations
- AI waits for explicit direction on which changes to implement
- AI confirms understanding before proceeding with any modifications
```

### **6. THINK TO HIGHEST LEVEL**
Always consider systemic impact, not just immediate problem

**Example - Database Optimization:**
```sql
-- ❌ LOCAL OPTIMIZATION: Speed up this one query
SELECT * FROM users WHERE status = 'active' ORDER BY created_at;
-- Add index on (status, created_at)

-- ✅ SYSTEMIC THINKING: Consider broader impact
-- How does this affect other queries?
-- Will this index slow down INSERT operations?
-- What's the query pattern across the entire application?
-- Should we implement caching strategy instead?
```

### **7. USE PROPER VALIDATION**
Verify system state and component readiness before proceeding

**Example - Component Integration:**
```javascript
// ❌ ASSUMPTION: Component is ready
document.getElementById('myComponent').addEventListener('click', handler);

// ✅ VALIDATION: Verify component exists and is ready
function initializeComponent() {
    const component = document.getElementById('myComponent');
    if (!component) {
        console.error('Component not found in DOM');
        return false;
    }
    if (component.dataset.initialized === 'true') {
        console.warn('Component already initialized');
        return false;
    }
    component.addEventListener('click', handler);
    component.dataset.initialized = 'true';
    return true;
}
```

### **8. VALIDATE COMPONENT READINESS**
Never operate on uninitialized or unavailable elements

**Example - DOM Manipulation:**
```javascript
// ❌ ASSUMPTION: Element exists and is ready
const element = document.querySelector('.my-element');
element.style.opacity = '0.5';  // May fail if element is null

// ✅ READINESS VALIDATION: Check existence and state
const element = document.querySelector('.my-element');
if (element && element.offsetParent !== null) {  // Exists and visible
    element.style.opacity = '0.5';
} else {
    console.warn('Element not ready for manipulation');
}
```

### **9. QUESTION OVER-ENGINEERING**
Modern systems are powerful, start simple and measure

**Example - Performance Optimization:**
```javascript
// ❌ PREMATURE OPTIMIZATION: Complex caching without measurement
class ComplexCache {
    constructor() {
        this.cache = new Map();
        this.lru = new LinkedList();
        this.hitRate = 0;
        // 50 lines of complex caching logic...
    }
}

// ✅ START SIMPLE: Measure first, then optimize
const simpleCache = new Map();
// Measure performance impact
// Add complexity only if simple version proves insufficient
```

### **10. PRIORITIZE USER EXPERIENCE**
UX and outcomes over technical purity

**Example - API Design:**
```javascript
// ❌ TECHNICALLY PURE: Strict REST compliance
POST /api/users/123/preferences/notifications/email/frequency
// Requires multiple API calls for common user actions

// ✅ UX FOCUSED: Practical endpoints for user needs
POST /api/users/123/update-notifications
// Single call handles common notification preference changes
```

### **11. REUSE ACTUAL COMPONENTS**
Never create replicas of existing system elements

**Example - UI Development:**
```jsx
// ❌ REPLICA: Creating similar component
const LoadingSpinnerModal = () => (
    <div className="modal-overlay">
        <div className="spinner"></div>  // Duplicate of existing spinner
    </div>
);

// ✅ REUSE: Compose with existing components
const LoadingSpinnerModal = () => (
    <Modal>
        <LoadingSpinner />  // Reuse existing spinner component
    </Modal>
);
```

### **12. SEPARATE DOMAIN FROM UTILITY**
Domain logic belongs in application layer

**Example - Function Design:**
```javascript
// ❌ COUPLED: Utility function contains domain knowledge
function formatCurrency(amount, isSubscriptionPrice = false) {
    const formatted = new Intl.NumberFormat('en-US', {
        style: 'currency', currency: 'USD'
    }).format(amount);
    
    // Domain logic leaked into utility
    if (isSubscriptionPrice && amount > 100) {
        return formatted + '/month (Premium tier)';
    }
    return formatted;
}

// ✅ SEPARATED: Pure utility + domain logic in application
function formatCurrency(amount, currency = 'USD') {
    return new Intl.NumberFormat('en-US', {
        style: 'currency', currency
    }).format(amount);
}

// Domain logic in application layer
function formatSubscriptionPrice(amount) {
    const formatted = formatCurrency(amount);
    if (amount > 100) {
        return `${formatted}/month (Premium tier)`;
    }
    return `${formatted}/month`;
}
```

### **13. USE EXPLICIT PARAMETERS**
Pass calculated values, don't let systems infer

**Example - Function Calls:**
```javascript
// ❌ IMPLICIT: Function infers what to do
updateUserProfile(user);  // Function must figure out what changed

// ✅ EXPLICIT: Clear about what's being updated
updateUserProfile(user, {
    fields: ['name', 'email'],
    reason: 'profile_edit',
    timestamp: Date.now()
});
```

### **14. IMPLEMENT EXPONENTIAL BACKOFF**
50ms, 100ms, 200ms, 400ms, 800ms, 1600ms

**Example - Retry Logic:**
```javascript
async function retryWithBackoff(operation, maxRetries = 6) {
    const delays = [50, 100, 200, 400, 800, 1600];
    
    for (let attempt = 0; attempt < maxRetries; attempt++) {
        try {
            return await operation();
        } catch (error) {
            if (attempt === maxRetries - 1) throw error;
            
            const delay = delays[attempt];
            console.log(`Attempt ${attempt + 1} failed, retrying in ${delay}ms`);
            await new Promise(resolve => setTimeout(resolve, delay));
        }
    }
}
```

### **15. LOG CLEAR CONTEXT**
[Component] {Action} failed: {specific reason}

**Example - Error Logging:**
```javascript
// ❌ VAGUE: Hard to debug
console.error('Failed to save');

// ✅ CLEAR CONTEXT: Actionable information
console.error('[UserProfileForm] Save operation failed: Validation error on email field - invalid format "user@domain"');

// Even better with structured logging
logger.error({
    component: 'UserProfileForm',
    action: 'save_operation',
    error: 'validation_failed',
    field: 'email',
    value: 'user@domain',
    reason: 'invalid_format'
});
```

---

**🧠 STATUS:** ✅ **RULES READY FOR APPLICATION**

*These 15 rules with practical examples provide concrete guidance for systematic problem-solving across any domain.*