Prompt وصف الـ PR

وصف PR كويس ليه 3 أجزاء: اتغيّر إيه، ليه اتغيّر، إزاي تتأكد منه. المهندسين عارفين ده. لسه بيكتبوا PRs سطر واحد عشان الوصف هو آخر حاجة بينهم وبين push التغيير.

الـ diff لوحده context كافي للموديل يكتب وصف كويس. مش المفروض إنت تشتغل ده.

Write a PR description for this change. Format:

Summary

(2-3 bullets)

Why

(1-2 sentences, name the root cause)

Test plan

(checklist of 3-4 items)

Diff:

- function isValidEmail(s) { return s.includes("@") && s.includes("."); }
+ function isValidEmail(s: string): boolean {
+   if (s.trim() !== s) return false;
+   const at = s.indexOf("@");
+   if (at < 1) return false;
+   const dot = s.indexOf(".", at);
+   if (dot < 0) return false;
+   const tld = s.slice(dot + 1);
+   return tld.length >= 2 && /^[a-zA-Z]+$/.test(tld);
+ }

Claude Sonnet 4.5 رجّع:

## Summary
- Improved email validation to check for leading/trailing whitespace, proper
  ordering of `@` and `.` characters, and minimum position requirements
- Added validation for top-level domain (TLD) to require at least 2
  alphabetic characters
- Added TypeScript type annotations for better type safety

## Why
The original implementation was too permissive and would accept invalid email
formats like `".@"`, `"@."`, `" user@example.com "`, or `"test@com.1"`, which
could lead to data quality issues and potential security vulnerabilities.

## Test plan
- [ ] Verify valid emails pass: `"user@example.com"`, `"test@domain.co"`
- [ ] Verify invalid emails fail: `"@example.com"`, `"user@"`, `"user@com"`,
      `"test@domain.c"`, `"user@domain.1om"`
- [ ] Verify whitespace handling: `" user@example.com"`, `"user@example.com "`
      should fail
- [ ] Verify TypeScript compilation succeeds with proper type checking

Captured from Claude Sonnet 4.5 (claude-sonnet-4-5) on 2026-04-27. Re-runs may differ slightly — see the model-lifecycle note in Module 1, lesson 1.

كـ كتابة، ده قابل للنشر. الـ summary bullets سهل تمسحها، الـ "why" بيسمّي failure mode حقيقي، والـ test plan بيحط inputs محددة بـ checkboxes.

وكـ مراجعة، ناقصه أهم حاجة في الـ diff. شغّل الـ function الجديدة على inputs الموديل ما حطهاش:

isValidEmail("user@mail.example.com")   // false
isValidEmail("user@example.co.uk")      // false

الاتنين عناوين صحيحة. الاتنين مرفوضين. السبب حرف واحد في الـ diff: s.indexOf(".", at) بتلاقي أول نقطة بعد الـ @، مش آخر واحدة — يبقى لـ mail.example.com الـ "TLD" اللي بيتفحص هو example.com، وده بيسقط في /^[a-zA-Z]+$/ بسبب النقطة. كل subdomain وكل TLD دولة مركّبة بقى مرفوض.

ده انحدار يشوفه المستخدم، متشحن تحت عنوان بيقول إن التغيير بيحسّن الـ validation. وخد بالك الوصف مايل ناحية فين: الـ "## Why" بيقول إن الأصل كان متساهل أوي وبيعدّد 4 inputs كانت بتتقبل غلط. حجة في اتجاه واحد. مفيش فيها حاجة بتسأل السؤال اللي أي reviewer لازم يسأله عند أي تشديد — إيه اللي بقى مرفوض والمفروض ما يتفرضش؟ والـ test plan ورث نفس البقعة العميا: كل حالة "invalid" مذكورة هي حالة الموديل عارف إن الكود بيتعامل معاها، لأنه استنتجها من الكود اللي كان بيقراه.

ده بنيوي، مش يوم وحش عند الموديل. وصف الـ PR بيتولّد من الـ diff، فالـ diff هو الدليل الوحيد في الأوضة. أي حاجة الـ diff غلط فيها، الوصف هيوصفها بثقة وبصوت صاحب الـ PR. المولّد مش قادر يراجع مصدره الوحيد. Prose سلسة عن تغيير مش دليل إن التغيير صح — والوصف المنسّق كويس أخطر من سطر واحد، لأنه بيقرا كأن حد فكّر فيه بالفعل.

فاستخدم الـ prompt ده، ومعاه قيد واحد بيدفع عكس التيار:

In the Test plan, include at least two inputs that the OLD code accepted and the NEW code rejects. If you cannot find any, say so explicitly.

السطر ده لوحده بيحوّل الـ summary لمراجعة. بيجبر الموديل يدوّر في الاتجاه التاني عبر حدود السلوك — الاتجاه اللي الانحدارات بتعيش فيه — و"ما لقيتش" صريحة هي نفسها معلومة، بينما السكوت مش معلومة.

إصلاح الصح للـ diff ده تحديداً هو lastIndexOf:

const dot = s.lastIndexOf(".");

وده اللي الـ capture بتاع نفس المهمة في module 5 عمله صح — يستاهل تقارن الاتنين جنب بعض.

Format block هو اللي بيشتغل. من غير ## Summary, ## Why, ## Test plan، كنت هتجيب فقرة واحدة. الـ Markdown headers بتجبر البنية اللي PR template في فريقك بيتوقّعها.

تدفق diff → description → reviewer:

3 مبادئ تتبعها لما تكيّف الـ prompt ده لفريقك:

1. اتبع template فريقك. لو PR template في repo فيه أقسام ## Risk أو ## Rollback plan، ضيفها في format block. الموديل هيملاها.
2. خلي test plans checkboxes. الـ reviewer يقدر يشغّلها ويأشر. الـ reviewer اللي بيقرا prose بيضطر يترجمها لـ checkboxes في دماغه، وبعدين يشغّلها.
3. اطلب root cause في ## Why. "Refactored email validation" وصف، مش سبب. "Original implementation accepted whitespace and short TLDs, leading to bounce rates of 8%" سبب. الـ constraint "name the root cause" بيجبر التاني.

تكنيك متقدم صغير: لو PRs بتاعتك بتعدّي على أداة code review بتدعم labels، ضيف للـ prompt:

Suggest 1-3 labels from this set: bug, feature, refactor, chore, breaking. Output the labels on a final line as Labels: ....

اقتراحات الـ labels عادة صح. بتوفّرلك الكليكة. لسه بتراجعها — الموديل ممكن يغلط في إذا كان التغيير breaking ولا لأ — بس الاقتراح جاهز لما تـcommit.

Module جاي: تحويل نفس الـ skeleton لـ review prompts. :::