claude.md

AI Intelligence Framework

🚨 MANDATORY PRE-EXECUTION CHECKLIST

BEFORE ANY CHANGES:

1. READ EXISTING CODE - Use Read tool, analyze patterns, check implementations
2. VERIFY CLAUDE.MD LOADED - Reference architectural patterns, follow conventions
3. UNDERSTAND ARCHITECTURE - Check dependencies, existing helpers/traits
4. FIGHT MESSY CODE - Reject hacks, use existing patterns

🧠 CRITICAL DEBUGGING APPROACH (Array-to-String Bugs)

MULTI-TOOL PARALLEL ATTACK:

# RUN IN PARALLEL
- mcp__github-ai__analyze_with_context7 (50+ lines)
- mcp__sequential-thinking__sequentialthinking (complex problems)
- Task tool + Bash tinker + Multiple Grep/Read

DEEP DATA INSPECTION:

$attributes = $record->getAttributes(); // Raw DB values
$casted = $record->toArray();          // Laravel casted values
foreach ($fields as $field => $value) {
    echo "{$field}: " . gettype($value) . (is_array($value) ? ' [ARRAY-DANGER!]' : '');
}

FILAMENT ARRAY BUG SOLUTIONS:

// ❌ NEVER: TextEntry::make('array_field')->formatStateUsing(...)
// ✅ ALWAYS: Computed fields with getStateUsing()
TextEntry::make('field_display')
    ->getStateUsing(function (Model $record): string {
        try {
            if (is_array($state)) {
                \Log::error('ARRAY DETECTED', ['field' => 'name', 'value' => $state]);
                return 'ERROR: Array - ' . json_encode($state);
            }
            return $state?->someMethod() ?? 'fallback';
        } catch (\Exception $e) {
            \Log::error('FIELD ERROR', ['error' => $e->getMessage()]);
            return 'Error: ' . $e->getMessage();
        }
    })

🎖️ SUPER INTELLIGENCE PRINCIPLES

1. MANDATORY CODE READING - Never change without reading existing first
2. CLAUDE.MD COMPLIANCE - Always verify loaded, follow patterns
3. PARALLEL TOOL EXECUTION - Multiple tools simultaneously
4. 100% ACCURACY DEMAND - Full context (200+ lines minimum)
5. SYSTEMATIC ELIMINATION - Remove components to isolate problems
6. DEEP DATA INSPECTION - Raw vs casted analysis on every bug
7. ERROR-FIRST THINKING - Assume arrays break string components
8. COMPREHENSIVE LOGGING - Debug every suspected component
9. ANTI-MESSY CODE - Reject hacks, demand clean solutions

🚨 FILAMENT CRITICAL PATTERNS

• Array Fields: NEVER direct access - Use computed fields with getStateUsing()
• Enum Fields: ALWAYS null coalescing ($state?->getLabel())
• Complex Data: Create virtual fields (field_display)
• Cache Issues: Clear cache after changes - Filament caches aggressively
• Multi-Tenant: All queries respect tenant scoping via policies

🏗️ ANTI-JUNIOR CODE FORTRESS

BANNED BEHAVIORS: ❌ Copy-paste coding ❌ Spaghetti flows ❌ Magic numbers ❌ God methods ❌ Tight coupling ❌ No error handling ❌ Unclear naming ❌ Long parameters ❌ Deep nesting ❌ Mixed responsibilities

SENIOR COMMANDMENTS:

1. Single Responsibility - One thing, done well
2. DRY Enforcement - Extract to methods/traits/helpers
3. Readable Code - Descriptive names, explain WHY not WHAT
4. Simple Flows - Linear paths, early returns, guard clauses
5. Composition - Traits, dependency injection, focused interfaces

CODE QUALITY GATES:

• Methods ≤20 lines | Classes ≤300 lines | Parameters ≤4 items
• Nesting ≤3 levels | Single purpose | Testable design

🚨 JUNIOR PSYCHO PREVENTION - ANTI-2000-LINE MADNESS

IF CODE >50 LINES - EMERGENCY INTERVENTION:

1. ❌ REJECT massive code immediately
2. 🔍 ANALYZE what it accomplishes
3. 🧠 BREAK DOWN into 3-5 components
4. 📋 CREATE proper architecture plan
5. ✅ IMPLEMENT incrementally

RED FLAGS - INTERVENE IMMEDIATELY: 🚨 God class >500 lines 🚨 Monolith method >30 lines 🚨 Copy-paste 3+ times 🚨 Nested hell >4 levels 🚨 Parameter chaos 6+ 🚨 Mixed responsibilities 🚨 No separation 🚨 Hardcoded nightmare

5-STEP INTERVENTION:

1. STOP & ANALYZE - WHAT/WHO/WHERE/WHEN/WHY
2. DECOMPOSE - Validation service, repository, DTOs, domain services, presenters
3. DESIGN ARCHITECTURE - Controller→Service→Repository→Model
4. IMPLEMENT INCREMENTALLY - Core→Business→API→UI→Testing
5. VALIDATE STANDARDS - SRP, <20 lines, <300 lines, testable, patterns

ANTI-PSYCHO TECHNIQUES:

// ✅ SENIOR: Extract services, form requests, DTOs, repositories
class OrderController {
    public function store(CreateOrderRequest $request) {
        $order = $this->orderService->create($request->validated());
        return new OrderResource($order);
    }
}

💪 ACTIVATION COMMANDS (USE EVERY SESSION)

1. "ACTIVATE PSYCHO-JUNIOR PREVENTION - NO 2000-line madness!"
2. "ENFORCE 50-LINE MAXIMUM - Break down massive code!"
3. "APPLY SENIOR ARCHITECT INTERVENTION - 5-step process!"
4. "IMPLEMENT ANTI-PSYCHO TECHNIQUES - Services, DTOs, repositories!"
5. "VALIDATE EMERGENCY STOPS - No god classes/monoliths!"
6. "FOLLOW INCREMENTAL IMPLEMENTATION - Small pieces!"
7. "MAINTAIN QUALITY GATES - Single responsibility, testable!"
8. "FIGHT JUNIOR MADNESS - Clean, focused code only!"

🏆 MASTER VALIDATION CHECKLIST

✅ Methods <20 lines? ✅ Classes <300 lines? ✅ Single responsibility?
✅ Self-documenting? ✅ Unit testable? ✅ Follows project patterns?
✅ Maintainable? ✅ Proper separation? ✅ No repeated code? ✅ Error handling?

IF ANY NO → REJECT & REDESIGN!

---

Critical Development Instructions

Error Prevention & Debugging

• Test Changes: Run lint/typecheck after changes
• Tinker Debug: Test data structures before UI implementation
• Multi-Tool: Parallel debugging for efficiency
• Deep Analysis: Raw vs casted data comparison

Code Quality Standards

• Follow Patterns: Examine similar implementations first
• Use Helpers: Check existing traits/services before creating
• Maintain Consistency: Follow naming/architectural conventions
• Senior Standards: Maintainable, reusable, clean architecture

Filament Guidelines

• Array Handling: Never TextEntry on arrays - use getStateUsing()
• Enum Display: Always null coalescing for labels
• Cache Updates: Clear Filament cache after changes
• Error Handling: Try-catch with logging for formatters

Laravel/Multi-Tenant

• Tenant Isolation: Respect team-based scoping
• Permissions: Use policies/middleware for access control
• Observers: Follow established patterns for lifecycle events
• Performance: Eager loading, efficient queries, prevent N+1

Never Skip

• Read First: Use Read tool before changes
• Verify Architecture: Ensure fits documented patterns
• Check Dependencies: Verify methods/classes exist via Grep/Read
• Test Incrementally: Isolate each change before next component

---

Important Instructions

• Do what's asked - nothing more, nothing less
• NEVER create files unless absolutely necessary
• ALWAYS prefer editing existing files
• NEVER create documentation files unless explicitly requested