# ✅ AGENT RULES - UPDATED FOR FILE EXPLORATION

## 🎯 The Problem You Identified

Agents start coding too quickly without reading related files, then get lost because:
- ❌ They edit one file in isolation
- ❌ They break imports in 3 other files
- ❌ They create runtime errors
- ❌ They need to redo everything

## ✅ The Solution

**NEW MANDATORY RULE:** Open 5-10 related files BEFORE editing anything.

---

## 📂 Updated Files

### 1. **NEW: `.github/instructions/READ_FILES_FIRST.md`**
   - Comprehensive guide on reading related files first
   - Examples of WRONG (isolated editing) vs RIGHT (files first)
   - Real time comparisons: 75 min broken vs 31 min working
   - Training examples
   - **2,800+ words of strict guidance**

### 2. **UPDATED: `.github/instructions/FOCUS.instructions.md`**
   - Added: "STEP 1: FIND & OPEN RELATED FILES FIRST" (at top)
   - Added: "DO NOT CODE YET" section
   - Expanded: Grep commands for components, endpoints, services, stores, types
   - Expanded: How to open files systematically
   - Added: Example of PlanCard.vue full flow

### 3. **UPDATED: `.github/instructions/copilot-instructions.md`**
   - Added: Mandatory reference to READ_FILES_FIRST.md at top
   - Expanded: Session start includes "OPEN 5-10 FILES FIRST"
   - Added: Examples of related files (component, endpoint, type)

---

## 📊 Impact

| Aspect | Change |
|--------|--------|
| **Files to read** | FOCUS → READ_FILES_FIRST → copilot |
| **Mandatory workflow** | Now: Grep → Open 5-10 → Read → THEN code |
| **Isolation risk** | Eliminated (explicit warnings) |
| **Examples** | Now includes component, endpoint, type examples |
| **Time to prevent bugs** | 15 min reading → saves 45 min debugging |

---

## �� New Protocol (Non-Negotiable)

**Every single time an agent edits ANY file:**

1. ✅ Grep for all imports of that file
2. ✅ Grep for all exports from that file
3. ✅ Open 5-10 related files AT ONCE
4. ✅ Read each file top-to-bottom
5. ✅ Trace the data flow mentally
6. ✅ Understand what breaks if I change this
7. ✅ THEN edit

**If ANY step is skipped: Their code breaks other files.**

---

## 🎯 Examples Now Provided

### Component (PlanCard.vue)
```
Open:
1. PlanCard.vue (target)
2. PlanList.vue (parent)
3. DashboardPage.vue (parent)
4. plannerService.ts (data)
5. plannerStore.ts (state)
6. Plan type
```

### Endpoint (POST /api/plans)
```
Open:
1. Controller (handles request)
2. Service (logic)
3. Repository (DB)
4. Frontend service (calls it)
5. Store (uses result)
6. Component (triggers)
```

### Type (Plan interface)
```
Open:
1. Type definition
2. All components using it
3. All services using it
4. All stores using it
5. API responses using it
6. All DTOs
```

---

## ✅ Checklist Added

Before editing ANY file:
- [ ] Identified target file
- [ ] Ran grep for imports
- [ ] Ran grep for exports
- [ ] Opened 5-10 related files
- [ ] Read each top-to-bottom
- [ ] Traced full flow
- [ ] Identified impact zones
- [ ] THEN started coding

---

## 🚫 Strict Warnings

❌ Never open just one file and code
❌ Never skip the grep step
❌ Never skip reading related files
❌ Never edit in isolation

---

## 📝 File Breakdown

```
.github/instructions/
  ├── READ_FILES_FIRST.md           ← NEW (Mandatory first read)
  │   2,800+ words
  │   Examples: Right vs Wrong
  │   Time comparisons
  │   Training scenarios
  │
  ├── FOCUS.instructions.md          ← UPDATED
  │   New "STEP 1: FIND & OPEN" section
  │   New "DO NOT CODE YET" section
  │   Expanded grep examples
  │
  └── copilot-instructions.md        ← UPDATED
      Points to READ_FILES_FIRST.md first
      Expanded Session Start
```

---

## 🎓 How Agents Use This Now

1. Start coding task
2. Read: `.github/instructions/READ_FILES_FIRST.md` (10 min)
3. Understand: WHY reading files first is critical
4. Grep: All related files (1 min)
5. Open: 5-10 files in editor (1 min)
6. Read: Each file (5-10 min)
7. Plan: Changes (5 min)
8. Code: All affected files (15 min)
9. Build: Passes first time ✅

**Total: ~40 minutes. Code works.** 

vs

**Old: 75+ minutes. Code broken.**

---

## ✅ Status

- [x] New strict guide (READ_FILES_FIRST.md)
- [x] Mandatory enforcement in FOCUS
- [x] Mandatory enforcement in copilot-instructions
- [x] Examples for components, endpoints, types
- [x] Real time comparisons (wrong vs right)
- [x] Training scenarios
- [x] Zero ambiguity: MUST read related files first

---

## 🏆 Result

**Agents can no longer edit files in isolation.**
**They MUST read 5-10 related files first.**
**This eliminates the "edit in isolation, break other files" problem.**

Tu as forcé les agents à explorer avant de coder. 🚀
