# سير عمل التوثيق لعملاء LLM

وكلاء LLM مصابون بالفقدان افتراضيًا: كل جلسة تبدأ من الصفر. الشيء الوحيد الذي يعبر حدود الجلسة هو ما خزّنته في نظام خارجي. التوثيق ليس بروتكراتية — إنه الطريقة التي تبقى بها *نفسك* عبر الجلسات.

## الطبقات الثلاث

| الطبقة | أين | ماذا | متى |
|---|---|---|---|
| Memory | `POST /memory` | حقائق دائمة، قرارات، أخطاء، بيانات اعتماد | لحظة تعلّمك لها |
| Worklog | `POST /worklog/:task_id` | تقدم المهمة، أخطاء، محطات | بعد كل خطوة ذات معنى |
| Changelog | `CHANGELOG.md` في المستودع + إيداع | تغييرات مرئية للمستخدم | مع كل تغيير في الكود |

## الطبقة 1: الذكريات

خزّن ذكرى **عندما تكون الحقيقة جديدة**، لا عند نهاية الجلسة. الجلسات تنهار؛ نوافذ السياق تفيض؛ «سأكتبها لاحقًا» حقيقة لم تحدث أبدًا.

اختر الفئة الصحيحة:

- `identity` — من أنت، دورك، أشقاؤك
- `project` — حالة المشروع وقراراته
- `mistake` — ما الذي سار خطأً والدروس (الفئة الأكثر قيمة)
- `skill` — كيف يُفعل شيء ما (قوائم خطوات، أوامر)
- `credentials` — رموز، نقاط نهاية، مسارات (لا في المحادثة أو الكود أبدًا)
- `context` — حالة جلسة تستحق الانتقال

استخدم `confidence` بصدق (1.0 = موثّق، 0.5 = افتراض) ووسّم باتساق — تُجد الذكريات بالوسم والمفتاح، لا بالنثر.

```
POST /memory
{ "content": "...", "category": "mistake", "key": "pg-params-42p18",
  "tags": ["postgres","dynamic-sql"], "priority": "high", "confidence": 1.0 }
```

## الطبقة 2: سجلات العمل

سجل العمل هو دفتر تقدم مهمة واحدة. يجيب عن «ما الذي حدث بالضبط أثناء الحل؟» لكل قارئ مستقبلي — بما في ذلك أنت في المستقبل.

```
POST /worklog/my-task-123 { "kind": "start",    "content": "أعدت إنتاج الخلل" }
POST /worklog/my-task-123 { "kind": "progress", "content": "الإصلاح في src/db.ts:142" }
POST /worklog/my-task-123 { "kind": "error",    "content": "42P18 — param type undetermined" }
POST /worklog/my-task-123 { "kind": "close",    "summary": "أُصلح، 24/24 اختبارات خضراء" }
```

قاعدة الإبهام: **إدخال واحد لكل قرار أو اكتشاف**، لا لكل ساعة. الأخطاء تدخل السجل فورًا — إنها الإدخالات الأكثر نفعًا لاحقًا.

## الطبقة 3: سجل التغيير والإيداعات

تغييرات الكود هي توثيق أيضًا:

- **رسالة الإيداع**: ما تغيّر و*لماذا*، مع مرجع المهمة/المستخدم بين قوسين. السطر الأول أقل من 72 حرفًا، بصيغة الأمر.
- **CHANGELOG.md**: إدخال واحد لكل تغيير مرئي للمستخدم، مجمّع كـ Added / Changed / Fixed / Removed، مع الإصدار والتاريخ.

الإصلاح بلا إدخال في سجل التغيير غير مرئي لكل من لم يقرأ الفرق.

## الأنماط المضادة

- **إفراغ الذاكرة في نهاية الجلسة.** السياق مفقود حينها — خزّن باستمرار.
- **ذكريات نثرية.** «ربما كانت مسألة قاعدة البيانات في مكان ما في الإعدادات» لا تُجد. استخدم مفاتيح دقيقة ووسومًا وبنية محتوى.
- **إعادة محاولة صامتة.** كل محاولة فاشلة تدخل سجل العمل؛ وإلا كررها الوكيل التالي.
- **المحادثة كمخزن.** سجل المحادثة ليس قاعدة معرفة — استخرج الحقائق الدائمة إلى ذكريات.

## حلقة كاملة

1. تعلّم شيئًا → `POST /memory` (الآن)
2. ابدأ مهمة → `POST /worklog/:id {kind:"start"}`
3. كل خطوة/خطأ → `POST /worklog/:id {kind:"progress"|"error"}`
4. غيّر الكود → إيداع + إدخال في CHANGELOG
5. أنهِ → `POST /worklog/:id {kind:"close", summary}`
6. علّم المهمة كمنجزة → `GET /mind/task/:id/complete`

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