مراجعة التغيير

الوعد الكامل لـ OpenSpec هو أنت وذكاءك الاصطناعي تتفقان على ما سيتم بناؤه قبل كتابة أي تعليمات برمجية. هذا الاتفاق لا يعني شيئًا ما لم تقرأ بالفعل ما صاغه الذكاء الاصطناعي. هذه الصفحة تتعلق بالدقيقتين اللتين تقوم فيهما بذلك — ما تفتحه، وبأي ترتيب، وما تبحث عنه.

الرهان بسيط: اكتشاف انحراف خاطئ في خطة مكونة من فقرة واحدة يكاد يكون مجانيًا. اكتشاف نفس الانحراف الخاطئ في 300 سطر من التعليمات البرمجية ليس كذلك. المراجعة هي المكان الذي تحقق فيه ربح هذا الرهان.

اللحظتان اللتان تقوم فيهما بالمراجعة

هناك لحظتان بالضبط:

/opsx:propose ──► مراجعة الخطة ──► /opsx:apply ──► مراجعة التعليمات البرمجية ──► /opsx:archive
                  (قبل أي تعليمات برمجية)                    (/opsx:verify)

1. بعد /opsx:propose (أو /opsx:ff)، قبل /opsx:apply — اقرأ الخطة وهي لا تزال مجرد كلمات.
2. بعد البناء، باستخدام /opsx:verify — تحقق من أن التعليمات البرمجية فعلت بالفعل ما ذكرته الخطة.

المراجعة الأولى هي التي توفر عليك أكبر قدر من الوقت والجهد، وهي التي يتجاهلها معظم الأشخاص. وتقضي هذه الصفحة معظم وقتها في مناقشتها.

اقرأ بهذا الترتيب

التغيير هو مجلد يحتوي على ملفات Markdown عادية في openspec/changes/<name>/. اقرأ الملفات بالترتيب الذي يسمح لك بالإنهاء في أقرب وقت إذا كان هناك خطأ ما:

openspec/changes/add-dark-mode/
├── proposal.md      1. النية والنطاق   ← إذا كان هذا خاطئًا، توقف هنا
├── specs/…/spec.md  2. المتطلبات       ← جوهر المراجعة
├── design.md        (فقط للتغييرات الأكبر) — النهج التقني
└── tasks.md         3. خطة العمل

لا تحتاج إلى قراءة كل سطر. تحتاج إلى الإجابة على ثلاثة أسئلة، سؤال واحد لكل ملف.

المقترح: هل هذه هي المشكلة الصحيحة؟

افتح ملف proposal.md أولاً. فهو يلتقط "السبب" و"ماذا" — النية، النطاق، النهج في فقرة أو اثنتين.

ما يبدو عليه الجيد: نية واحدة واضحة، نطاق تعرفه، وسبب يبرر القيام به الآن.

علامات الخطر:

• يحل مشكلة مختلفة قليلاً عن المشكلة التي طلبتها.
• لقد توسع النطاق — لقد طلبت مفتاح تبديل للمظهر، ويقترح المقترح أيضًا التعامل مع المصادقة (auth) "بينما نحن هنا".
• إنه غامض. "تحسين صفحة الإعدادات" ليس نطاقًا؛ "إضافة مفتاح تبديل للوضع الداكن يحترم تفضيل نظام التشغيل (OS)" هو النطاق الصحيح.

السؤال الذي يجب الإجابة عليه: هل يطابق هذا ما طلبته بالفعل، وهناك أي شيء يتسلل إلى النطاق؟ إذا كانت الإجابة لا، توقف — لا تقرأ المزيد، قم بإصلاح المقترح (راجع الاعتراض على المقترح رخيص).

تعديلات المواصفات: هل تم تعريف "الانتهاء" بشكل صحيح؟

هذا هو جوهر المراجعة. تعديلات المواصفات الموجودة تحت specs/ تحدد ما سيكون صحيحًا عند إصدار التغيير — كمتطلبات وسيناريوهات تثبتها:

## ADDED Requirements

### Requirement: Dark Mode Toggle
The system SHALL let a user switch between light and dark themes.

#### Scenario: Respects the OS preference on first load
- GIVEN a user who has never set a theme
- WHEN they open the app on a device set to dark mode
- THEN the app renders in dark mode

ما يبدو عليه المتطلب الجيد: تعبير SHALL/MUST واحد واضح يمكنك تسليمه لمختبر، وسيناريو واحد على الأقل تكون جمل GIVEN/WHEN/THEN فيه تمارس هذا التعبير بالفعل.

علامات الخطر:

• متطلب غامض. لا يمكن بناء أو اختبار العبارة "The system SHALL be fast". ما هي السرعة المقصودة هنا؟
• متطلب لا يحتوي على سيناريو، أو سيناريو لا يختبر المتطلب الذي يوجد تحته.
• أكثر فائدة على الإطلاق: ما هو المفقود. يكتب الذكاء الاصطناعي بكل دقة ما قلته أنت. مهمتك هي ملاحظة ما نسيت قوله. إذا كنت تهتم أكثر بحالة تفضيل نظام التشغيل (OS) ولا يذكرها أي سيناريو، فهذه هي المراجعة التي تدفع ثمنها بنفسها.

اقرأ التعديلات وتساءل هل سأكون راضٍ إذا قام النظام بفعل هذا بالضبط — ولا شيء سواه؟ لا شيء هنا يتعلق بالتعليمات البرمجية بعد، لذا يبقى تغييره رخيصًا.

المهام: هل خطة العمل معقولة؟

افتح ملف tasks.md أخيرًا. فهو قائمة التحقق من التنفيذ التي سيعمل من خلالها الذكاء الاصطناعي.

ما يبدو عليه الجيد: خطوات مرتبة، كل منها قابل للتتبع إلى متطلب، ولا شيء غامض.

علامات الخطر:

• مهمة لا تحتوي على متطلب مطابق (من أين أتت هذه؟).
• مهمة واحدة ضخمة "تنفيذ الميزة" تخفي جميع القرارات الحقيقية.
• مهمة تتعامل مع شيء خارج النطاق الذي وافقته للتو.

أنت هنا لا تقدر الوقت أو تدير التفاصيل الدقيقة — أنت تتحقق من أن الخطة تطابق المتطلبات التي قبلتها بالفعل.

الاعتراض على المقترح رخيص

إذا كانت إجابة أي من الأسئلة الثلاثة خاطئة، قل ذلك. لا توجد مراحل ولا شيء مقفل — تقوم بإصلاحه ثم تنتقل إلى الخطوة التالية. طريقتان، تمامًا كما هو مذكور في تحرير التغيير:

• قم بتحرير الملف بنفسك. إنه ملف Markdown عادي؛ قم بتغيير سطر النطاق، تشديد متطلب، حذف مهمة.
• أخبر الذكاء الاصطناعي بما هو خاطئ واتركه يعيد الصياغة: "أزل تغييرات المصادقة (auth) — خارج النطاق،" "أضف سيناريو لحالة اختيار المستخدم للمظهر مسبقًا،" "قسم المهمة 3 إلى مخطط البيانات (schema) وواجهة المستخدم (UI)."

ثم أعد قراءة الجزء الذي قمت بتغييره. أعد صياغته حتى تكون خطة يمكنك التوقيع عليها. هذا التبادل هو العمل على المنتج نفسه.

بعد التعليمات البرمجية: التحقق

بمجرد اكتمال العمل، يعتبر /opsx:verify مراجعتك الثانية. فهو يعيد قراءة المخرجات والتعليمات البرمجية ويبلغ عن عدم التطابق عبر ثلاثة أبعاد:

البعد	ما يتحقق منه
الاكتمال	إنجاز كل مهمة، تنفيذ كل متطلب، تغطية جميع السيناريوهات
الصحة	تطابق التنفيذ لقصد المواصفة، معالجة الحالات الحدية
التماسك	تظهر قرارات التصميم بالفعل في التعليمات البرمجية

You: /opsx:verify

AI:  Verifying add-dark-mode...

     COMPLETENESS
     ✓ All 8 tasks in tasks.md are checked
     ✓ All requirements in specs have corresponding code
     ⚠ Scenario "Respects the OS preference on first load" has no test coverage

يصنف المشاكل على أنها CRITICAL أو WARNING أو SUGGESTION، وهو لا يمنع الأرشفة — فهو يظهر الفجوات ويترك القرار لك. هذا هو الفرق بين "هل كتب الذكاء الاصطناعي تعليمات برمجية" و"هل بنى ما اتفقنا عليه".

يوجد الأمر /opsx:verify في الملف الشخصي الموسع. إذا لم يكن لديك، قم بتشغيله باستخدام openspec config profile (ثم openspec update)، أو ببساطة أعد قراءة التغيير والفرق (diff) بنفسك.

قم بتكييف حجم المراجعة

لا يستحق كل تغيير المراجعة الكاملة. إصلاح خطأ إملائي في ملف واحد يستحق تصفحًا سريعًا لمدة عشرين ثانية. التغيير الذي يتعامل مع المصادقة (auth) أو المدفوعات (payments) أو البيانات التي لا يمكنك استردادها يستحق الإجابة على جميع الأسئلة المذكورة أعلاه. الهدف لم يكن أبدًا الطقوس الرسمية — بل إنفاق انتباهك حيث يكون الخطأ مكلفًا، والتصفح السريع حيث لا يكون كذلك.

قائمة التحقق من دقيقتين

• [ ] نية المقترح تطابق ما طلبته.
• [ ] لم يتسلل أي شيء إضافي إلى النطاق.
• [ ] كل متطلب محدد بدرجة كافية للاختبار.
• [ ] كل متطلب يحتوي على سيناريو يمارسه بالفعل.
• [ ] الحالة التي أهتم بها أكثرها مغطاة.
• [ ] المهام مرتبطة بالمتطلبات؛ لا شيء غامض أو خارج النطاق.
• [ ] سأكون مرتاحًا إذا بنى الذكاء الاصطناعي هذا بالضبط ولا شيء أكثر.

إذا اجتازت جميع النقاط السبع، قم بتنفيذ /opsx:apply بثقة. إذا فشلت أي منها، فهذا ليس نكسة — بل هي الدقيقتان تقومان بوظيفتهما.

إلى أين تذهب بعد ذلك

• كتابة مواصفات جيدة — الجانب الآخر: كيف تصيغ متطلبات وسيناريوهات تستحق الموافقة.
• تحرير والتكرار على التغيير — آلية تغيير الخطة بعد بدء العمل.
• سير العمل — مكان المراجعة في الحلقة الأكبر لسير العمل.