---
name: problem-solving-mindset
description: Guidelines and professional mindset for debugging, root cause analysis, and solving complex software issues effectively.
---

# 🧠 Problem Solving Mindset — عقلية حل المشاكل الاحترافية

> **هدف المهارة:** توجيه التفكير عند مواجهة أي مشكلة برمجية — من خطأ بسيط إلى عطل معماري معقد — بأسلوب منهجي ومحترف يتجنب الحلول الترقيعية ويصل لجذر المشكلة.

---

## المبدأ الأول: توقف قبل أن تكتب (Stop Before You Code)

**لا تلمس الكود فوراً.** عند ظهور مشكلة:

1. **اقرأ رسالة الخطأ بالكامل** — لا تقرأ السطر الأول فقط. الرسالة كاملةً تحتوي على معلومات حيوية (اسم الملف، رقم السطر، حالة النظام).
2. **أعد صياغة المشكلة بكلماتك** — "ماذا كنت أتوقع أن يحدث؟" و "ماذا حدث فعلاً؟" الفرق بين الإجابتين هو المشكلة الحقيقية.
3. **حدد نطاق المشكلة** — هل المشكلة في الـ Frontend أم Backend أم الاتصال بينهما؟ هل هي في الكود أم في البيئة (Environment)؟ هل تحدث دائماً أم أحياناً فقط؟

---

## المبدأ الثاني: ابحث عن السبب الجذري (Root Cause Analysis)

### القاعدة الذهبية: "لماذا?" خمس مرات (5 Whys)

عند كل إجابة، اسأل "لماذا؟" مرة أخرى حتى تصل للسبب الحقيقي:
```
المشكلة: الصفحة لا تظهر بعد الدفع.
- لماذا؟ → لأن Router يذهب للصفحة الرئيسية.
- لماذا؟ → لأن الرابط في المتصفح يتغير لـ "/".
- لماذا؟ → لأن هناك علمية تكتب فوق الرابط.
- لماذا؟ → لأن Splash Screen يُنشئ Navigator منفصل.
- لماذا؟ → لأنه يستخدم MaterialApp بدلاً من widget بسيط. ← الجذر!
```

### أنماط شائعة للأسباب الجذرية

| النمط | الوصف | مثال |
|-------|-------|------|
| **Side Effect مخفي** | كود يبدو بريئاً لكن له تأثير جانبي غير متوقع | Widget يغير حالة عامة (URL, Global State) دون قصد |
| **Race Condition** | عمليتان متزامنتان تتنافسان على نفس المورد | قراءة بيانات من التخزين تنتهي بعد عملية مسح |
| **Wrong Layer** | البحث عن المشكلة في الطبقة الخطأ | المشكلة في Bootstrap وأنت تبحث في Router |
| **Assumption Bug** | افتراض خاطئ عن سلوك مكتبة أو API | افتراض أن function معينة synchronous وهي async |
| **Environment Mismatch** | الكود يعمل في بيئة ولا يعمل في أخرى | يعمل في Debug ولا يعمل في Production بسبب optimizations |
| **State Leak** | حالة قديمة تبقى وتلوث الحالة الجديدة | Cache أو Local Storage يحتفظ ببيانات قديمة |
| **Order Dependency** | الكود يعتمد على ترتيب تنفيذ معين غير مضمون | تهيئة خدمة A قبل خدمة B مع وجود اعتماد بينهما |
| **Mixed Coordinate Systems** | عناصر صحيحة منفردة لكن الخلل يظهر عند جمعها ضمن مرجعين هندسيين مختلفين | نص هيدر مع VML page-anchored داخل نفس الفقرة |

---

## المبدأ الثالث: شجرة القرار للتشخيص (Diagnosis Decision Tree)

```
هل تستطيع إعادة إنتاج الخطأ؟
├── نعم → ممتاز، ابدأ بعزل المشكلة (Isolate)
│   ├── هل المشكلة في ملف/مكون واحد محدد؟
│   │   ├── نعم → اقرأ الكود سطراً سطراً، تتبع الـ flow
│   │   └── لا → المشكلة في التفاعل بين المكونات (Integration)
│   │       └── تتبع البيانات من المصدر إلى النهاية (Data Flow)
│   └── هل تحدث في بيئة معينة فقط؟
│       └── نعم → قارن الفروقات بين البيئتين (Config, Build Mode, Network)
└── لا (متقطعة) → غالباً Race Condition أو Memory أو Timing
    └── أضف Logging مكثف حول المنطقة المشبوهة
```

---

## المبدأ الرابع: قواعد تقييم الحلول (Solution Evaluation)

قبل تطبيق أي حل، اسأل هذه الأسئلة:

### ✅ أسئلة يجب أن تُجيب عنها بـ "نعم"
- [ ] **هل يعالج السبب الجذري؟** (وليس فقط الأعراض)
- [ ] **هل يحترم تجربة المستخدم؟** (لا يضر المستخدم لأجل راحة المبرمج)
- [ ] **هل هو أبسط حل ممكن؟** (KISS — Keep It Simple, Stupid)
- [ ] **هل يمكن اختباره والتحقق منه؟** (يمكن التأكد من نجاحه)

### ❌ علامات تحذيرية (Red Flags)
- استخدام `setTimeout` / `Future.delayed` / `sleep` لحل مشاكل توقيت ← يعني أنك تخفي Race Condition
- إضافة `try-catch` بدون معالجة حقيقية ← يعني أنك تخفي الخطأ بدل حله
- تكرار نفس الإصلاح في أكثر من مكان ← يعني أن المشكلة في مكان أعلى (Architecture)
- الحل يتطلب معرفة "سحرية" ليعمل ← يعني أنه هش وسينكسر لاحقاً
- فرضية أنيقة جداً ومعقولة نظرياً، لكن أول تطبيق لها خرّب السلوك الفعلي ← توقّف وارجع خطوة؛ قد تكون الفرضية جزئياً صحيحة لكنها غير آمنة كحل عام

### اختبار الفرضيات في مشاكل التخطيط الدقيقة
- لا يكفي أن تكون الفرضية "مقنعة"
- في مشاكل layout الدقيقة، افصل بين ثلاثة مستويات:
  - **مستوى الاختيار**: هل اخترت العنصر/القسم/الهيدر الصحيح؟
  - **مستوى البيانات**: هل القيم المقروءة من XML صحيحة؟
  - **مستوى العرض**: هل طريقة الرسم نفسها تترجم هذه القيم بشكل صحيح؟
- لا تنتقل إلى المستوى التالي قبل حسم السابق

### قاعدة مهمة: صحة الفكرة لا تعني صحة التعديل
- قد تصل إلى تفسير صحيح نظرياً للمشكلة، لكن التعديل المشتق منه يكون واسعاً أكثر من اللازم
- إذا طبقت تغييراً معمارياً وأفسد السلوك، فوثّق ما تعلمته من الفرضية ثم تراجع فوراً
- لا تحوّل "فهمًا جيدًا للمشكلة" إلى commit إلا إذا ثبت أن الأثر الجانبي مضبوط

---

## المبدأ الخامس: نظافة التجارب (Clean Experimentation)

### القاعدة: جرّب ← قيّم ← نظّف

عند تجربة حلول:
1. **حل واحد في كل مرة** — لا تغير 5 أشياء معاً ثم تتساءل أيها حلّ المشكلة.
2. **سجّل ما جربته** — حتى لو فشل، سجّل ماذا جربت ولماذا فشل.
3. **تراجع فوراً عن الفاشل** — إذا لم ينجح الحل، **احذفه بالكامل** قبل تجربة حل جديد. لا تبني حلاً جديداً فوق حل فاشل.
4. **لا تترك كود تجريبي في الإنتاج** — بعد إيجاد الحل الصحيح، نظّف كل آثار التجارب الفاشلة.
5. **إذا كشف التعديل الفاشل بنية أعمق للمشكلة، احتفظ بالمعرفة لا بالكود** — دوّن الدرس في المهارات/التوثيق، ثم ارجع إلى شجرة التشخيص.

---

## المبدأ السادس: أنماط التفكير الخاطئة (Cognitive Biases to Avoid)

| التحيز | الوصف | كيف تتجنبه |
|--------|-------|-------------|
| **Anchoring** (التثبيت) | التمسك بأول فرضية حتى لو ثبت خطؤها | كن مستعداً لتغيير فرضيتك إذا لم تتطابق مع الأدلة |
| **Confirmation Bias** (تأكيد الذات) | البحث عن أدلة تؤكد فرضيتك وتجاهل ما يناقضها | ابحث فعلياً عما يُثبت خطأ فرضيتك (Falsification) |
| **Sunk Cost** (تكلفة الغارقة) | الاستمرار في حل فاشل لأنك استثمرت وقتاً فيه | الوقت الذي أنفقته لا يجعل الحل الخطأ صحيحاً. تراجع بثقة |
| **Complexity Bias** (تحيز التعقيد) | الظن بأن المشكلة معقدة فتبني حلاً معقداً | المشكلة غالباً أبسط مما تعتقد. ابدأ بأبسط فرضية |
| **Recency Bias** (تحيز الحداثة) | الظن بأن آخر تعديل هو سبب المشكلة | المشكلة قد تكون موجودة من قبل، وآخر تعديل كشفها فقط |
| **Theory Lock-In** (الانحباس في التفسير) | لأن التفسير يبدو متماسكاً، تفترض أن التنفيذ المشتق منه يجب أن ينجح | افصل بين جودة التفسير وصحة التعديل العملي |

---

## المبدأ السابع: متى تطلب المساعدة (When to Escalate)

- ⏱️ إذا مضت **30 دقيقة** بدون تقدم ملموس → أعد تقييم مقاربتك بالكامل.
- ⏱️ إذا مضت **60 دقيقة** → اشرح المشكلة لشخص آخر (أو حتى لنفسك بصوت عال — Rubber Duck Debugging).
- 🔄 إذا جربت **3 حلول فاشلة** → توقف وارجع للمبدأ الثاني (Root Cause). أنت تعالج الأعراض.

---

## المبدأ الثامن: قائمة المراجعة قبل الحل النهائي (Pre-Commit Checklist)

قبل اعتماد أي حل (Commit / Deploy):
- [ ] هل السبب الجذري مفهوم ومُوثق؟
- [ ] هل تم التراجع عن كل التجارب الفاشلة؟
- [ ] هل الكود النهائي نظيف وخالٍ من `print` و `console.log` التشخيصية؟
- [ ] هل تم اختبار الحل في السيناريو الذي أنتج المشكلة؟
- [ ] هل تم اختبار أن الحل لم يكسر شيئاً آخر (Regression)؟
- [ ] هل الحل يعمل في جميع البيئات المطلوبة (Dev, Staging, Production)؟

---

## خلاصة: القواعد الذهبية السبعة

1. **افهم أولاً، ثم حل.** (Understand before you fix)
2. **عالج الجذر لا الأعراض.** (Fix the root, not the symptom)
3. **أبسط حل صحيح هو أفضل حل.** (Simplest correct fix wins)
4. **تجربة المستخدم فوق راحة المبرمج.** (UX over DX)
5. **نظّف بعد كل تجربة فاشلة.** (Clean up failed experiments)
6. **كن مستعداً للتراجع.** (Be ready to revert)
7. **المبرمج المحترف يتقبل الخطأ ويتعلم منه، لا يعاند.** (Embrace mistakes, learn fast)