# ⚠️ CRITICAL DEVELOPMENT GUIDELINES - READ FIRST

**⚠️ IMPORTANT: Read this document BEFORE making any changes to the codebase.**

This is a **production project** with multiple modules and shared components. All developers and AI assistants must follow these rules strictly to prevent breaking changes.

---

## 🚨 CORE RULE: NEVER BREAK OR MODIFY CODE OUTSIDE YOUR WORK SCOPE

### Primary Principles

1. **Only update the specific file/function/component the user mentions.**
   - Do NOT modify, remove, or overwrite code belonging to any other module, feature, component, or file unless explicitly instructed.

2. **Keep changes LIMITED to only the file, function, or component you're currently working on.**
   - Any change must be isolated to the exact scope requested.

3. **NEVER change global CSS, shared components, common utilities, config files, or reusable functions unless specifically asked.**
   - This includes:
     - Global stylesheets
     - Shared Blade components
     - Common helper functions
     - Configuration files
     - Service providers
     - Middleware
     - Any code used by multiple modules

4. **NO SIDE EFFECTS.**
   - Ensure updates do NOT break:
     - Existing design
     - Layout or UI of other pages
     - Functionality of any other module
     - Shared APIs or shared logic

5. **Before making any change, ALWAYS check:**
   - ✅ Does this affect other modules?
   - ✅ Does this change break alignment, styles, or shared classes?
   - ✅ Does this update modify logic used in multiple places?
   
   **If YES → STOP and provide a safer alternative or ask for confirmation.**

6. **ALWAYS keep backward compatibility.**
   - All existing flows must continue to work exactly as before.
   - Do not change function signatures, API contracts, or data structures used elsewhere.

7. **If you need to adjust something shared, first WARN the user and ask for confirmation before touching it.**
   - Never assume it's safe to modify shared code.

8. **Only refactor code that the user selects or mentions.**
   - DO NOT refactor neighboring code automatically.
   - DO NOT optimize unrelated code.

9. **Every time you generate code:**
   - Keep the existing behaviour untouched.
   - Keep the existing design intact.
   - Keep code changes minimal and isolated.
   - Avoid unnecessary restructuring or optimization.

10. **Your responsibility: NEVER break any other page, feature, or UI.**
    - Always produce SAFE, NON-BREAKING, MODULE-ISOLATED code.

---

## 📋 Pre-Change Checklist

Before making ANY code change, verify:

- [ ] I am only modifying the specific file/component mentioned by the user
- [ ] I am not touching any global CSS, shared components, or utilities
- [ ] I am not modifying config files or common logic
- [ ] My changes will not affect other modules or pages
- [ ] I have checked for side effects on design, layout, or functionality
- [ ] I am maintaining backward compatibility
- [ ] I have warned the user if I need to touch shared code
- [ ] My changes are minimal and isolated

**If you cannot check all boxes, STOP and ask for guidance.**

---

## 🎯 Safe Development Practices

### ✅ DO:
- Make isolated changes to only the requested file/component
- Use scoped CSS classes (avoid global selectors)
- Create new functions/components when needed instead of modifying shared ones
- Test your changes in isolation
- Ask for clarification if scope is unclear

### ❌ DON'T:
- Modify files not mentioned by the user
- Change global styles or shared components
- Refactor code outside the requested scope
- Optimize or "improve" unrelated code
- Assume it's safe to modify shared utilities
- Break existing functionality "for the greater good"

---

## 🔍 How to Identify Shared Code

**Shared code includes:**
- Files in `app/Helpers/`, `app/Services/` (unless specific to your module)
- Global CSS files in `resources/css/` or `public/css/`
- Blade components in `resources/views/components/`
- Configuration files in `config/`
- Service providers in `app/Providers/`
- Middleware in `app/Http/Middleware/`
- Any file imported/used by multiple modules

**When in doubt, ask before modifying.**

---

## 📝 Example Scenarios

### ✅ CORRECT Approach:
**User:** "Update the Business Units card styling"
- ✅ Modify only `resources/views/filament/pages/system-admin.blade.php`
- ✅ Use scoped CSS classes within that file
- ✅ Keep changes isolated to the Business Units module

### ❌ WRONG Approach:
**User:** "Update the Business Units card styling"
- ❌ Modify global CSS files
- ❌ Change shared card components used elsewhere
- ❌ Refactor unrelated code in the same file
- ❌ Update utility functions used by other modules

---

## 🚨 Emergency: If You Accidentally Break Something

1. **STOP immediately**
2. **Revert your changes**
3. **Inform the user**
4. **Review these guidelines**
5. **Propose a safer approach**

---

## 📞 Questions?

If you're unsure whether a change is safe:
1. **STOP**
2. **Ask the user for clarification**
3. **Propose alternatives**
4. **Wait for explicit confirmation**

---

**Remember: It's better to ask than to break production code.**

---

*Last Updated: [Current Date]*
*This document must be reviewed by all developers and AI assistants before making any changes.*