documentation

---
name: prd-and-technical-documentation-generator
description: مهارة لإنشاء وثائق متطلبات المنتج (PRD) والتوثيق الفني الشامل للمشاريع.
---

# مولّد وثائق متطلبات المنتج والتوثيق الفني

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

## التعليمات

1. **تحديد المنتج أو الميزة**: وضّح المنتج أو الميزة التي سيتم إعداد التوثيق لها بشكل مباشر ومحدد.
2. **جمع المتطلبات**: حدّد وسجّل جميع المتطلبات اللازمة، بما يشمل المتطلبات الوظيفية وغير الوظيفية.
3. **هيكلة وثيقة متطلبات المنتج PRD**:
   - **المقدمة**: قدّم نبذة مختصرة عن المنتج أو الميزة.
   - **وصف المشكلة**: اشرح المشكلة التي يهدف المنتج أو الميزة إلى حلها.
   - **الأهداف**: وضّح الأهداف الرئيسية والنتائج المطلوبة.
   - **النطاق**: عرّف نطاق العمل، بما في ذلك ما يدخل ضمن النطاق وما يُستثنى منه.
   - **المتطلبات**: فصّل المتطلبات الوظيفية وغير الوظيفية.
   - **قصص المستخدمين**: أضف قصص مستخدم توضّح سيناريوهات الاستخدام المتوقعة.
4. **التوثيق الفني**:
   - **نظرة عامة على البنية التقنية**: قدّم مخططًا للبنية ووصفًا لطريقة عمل النظام.
   - **المواصفات الفنية**: فصّل المتطلبات والمواصفات التقنية اللازمة.
   - **واجهات برمجة التطبيقات والواجهات**: اذكر واجهات API والواجهات الأخرى، مع طريقة الاستخدام وأمثلة عملية.
   - **الأمن والامتثال**: وضّح إجراءات الأمن ومتطلبات الامتثال ذات العلاقة.

## أمثلة

- **مثال على الإدخال**: «أنشئ وثيقة متطلبات منتج لميزة دفع جديدة في منصة تجارة إلكترونية تستهدف السوق السعودي»
- **مثال على المخرجات**: مستند منظّم يحتوي على جميع الأقسام المطلوبة، مع معلومات مناسبة عن الميزة، والمتطلبات، وقصص المستخدمين، والتفاصيل الفنية.

## المتغيرات

- productFeature - الميزة أو المبادرة المحددة للمنتج.
- PRD - نوع المستند المطلوب إنشاؤه (PRD أو Technical).

استخدم هذه المهارة لإنتاج توثيق شامل بكفاءة، يدعم أهداف المشروع واحتياجات أصحاب المصلحة.

---
name: documentation-update-automation
description: مهارة لتحديث ملفات التوثيق المحلية التمهيدية بمحتوى الإنترنت الأحدث. استخدم هذه المهارة عندما يطلب المستخدم "تحديث التوثيق" أو "مزامنة التوثيق مع مصادر الإنترنت" أو "تجديد ملفات التوثيق المحلية".
version: 1.0.0
author: AI Assistant
tags:
  - documentation
  - web-scraping
  - content-sync
  - automation
---

# مهارة أتمتة تحديث التوثيق

## الشخصية
أنت تعمل كمهندس أتمتة توثيق، ومتخصص في مزامنة ملفات التوثيق المحلية مع نسخها الأحدث المنشورة على الإنترنت. أسلوبك منظّم، وتراعي حدود معدلات الطلب للواجهات والمواقع، وتوثّق التغييرات بدقة.

## متى تستخدم هذه المهارة

فعّل هذه المهارة عندما يكون المستخدم:
- يطلب تحديث التوثيق المحلي من مصادر على الإنترنت
- يريد مزامنة ملفات التوثيق التمهيدية مع المحتوى المباشر
- يحتاج إلى إنعاش ملفات توثيق قديمة
- لديه ملفات Markdown تحتوي على نمط الرابط: "Fetch live documentation:"

## الإجراءات الأساسية

### المرحلة 1: الاكتشاف والجرد

1. **تحديد مجلد التوثيق**
   ```bash
   # البحث عن كل ملفات Markdown التي تحتوي على روابط توثيق مباشرة
   grep -r "Fetch live documentation:" <directory> --include="*.md"
   ```

2. **استخراج كل الروابط من الملفات التمهيدية**
   ```python
   import re
   from pathlib import Path
   
   def extract_stub_url(file_path):
       with open(file_path, 'r', encoding='utf-8') as f:
           content = f.read()
           match = re.search(r'Fetch live documentation:\s*(https?://[^\s]+)', content)
           return match.group(1) if match else None
   ```

3. **إنشاء جرد للملفات المطلوب تحديثها**
   - احسب إجمالي عدد الملفات
   - اعرض كل الروابط الفريدة
   - حدّد بنية المجلدات

### المرحلة 2: المقارنة والتحليل

1. **التحقق مما إذا كان المحتوى قد تغيّر**
   ```python
   import hashlib
   import requests
   
   def get_content_hash(content):
       return hashlib.md5(content.encode()).hexdigest()
   
   def get_online_content_hash(url):
       response = requests.get(url, timeout=10)
       return get_content_hash(response.text)
   ```

2. **مقارنة بصمات المحتوى المحلي مع المحتوى المنشور على الإنترنت**
   - إذا كانت البصمات متطابقة: تجاوز الملف لأنه محدّث مسبقًا
   - إذا كانت البصمات مختلفة: علّم الملف للتحديث
   - إذا أعاد الرابط 404: علّم الملف على أنه غير متاح

### المرحلة 3: المعالجة على دفعات

1. **عالج الملفات على دفعات من 10 إلى 15 ملفًا** لتجنب انتهاء المهلة
2. **طبّق تحديد معدل الطلبات** بمعدل ثانية واحدة بين كل طلب
3. **تابع التقدّم** مع تسجيل تفصيلي للعمليات

### المرحلة 4: تنزيل المحتوى وتنسيقه

1. **تنزيل المحتوى من الرابط**
   ```python
   from bs4 import BeautifulSoup
   from urllib.parse import urlparse
   
   def download_content_from_url(url):
       response = requests.get(url, timeout=10)
       soup = BeautifulSoup(response.text, 'html.parser')
       
       # استخراج المحتوى الرئيسي
       main_content = soup.find('main') or soup.find('article')
       if main_content:
           content_text = main_content.get_text(separator='\n')
       
       # استخراج العنوان
       title_tag = soup.find('title')
       title = title_tag.get_text().split('|')[0].strip() if title_tag else urlparse(url).path.split('/')[-1]
       
       # تنسيق المحتوى بصيغة Markdown
       return f"# {title}\n\n{content_text}\n\n---\n\nFetch live documentation: {url}\n"
   ```

2. **تحديث الملف المحلي**
   ```python
   def update_file(file_path, content):
       with open(file_path, 'w', encoding='utf-8') as f:
           f.write(content)
   ```

### المرحلة 5: إعداد التقرير

1. **إنشاء إحصائيات مختصرة**
   - الملفات التي تم تحديثها
   - الملفات التي تم تجاوزها لأنها محدّثة مسبقًا
   - الأخطاء التي ظهرت

2. **إنشاء تقرير تفصيلي**
   - قائمة بكل الملفات المحدّثة
   - توضيح أي حالات فشل
   - تقديم توصيات مناسبة

## الحدود وقواعد السلامة

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

### لا تقم أبدًا بـ:
- تعديل ملفات خارج مجلد التوثيق المحدد
- حذف ملفات موجودة بدون موافقة صريحة من المستخدم
- الكتابة فوق ملفات لا تحتوي على نمط الملف التمهيدي المطلوب
- إرسال طلبات متتابعة بسرعة قد تؤدي إلى تفعيل حدود المعدل
- تحديث ملفات بدون التحقق أولًا مما إذا كان المحتوى قد تغيّر فعليًا

## التعامل مع الأخطاء

1. **الرابط غير متاح، مثل 404 أو انتهاء المهلة**
   - سجّل الخطأ
   - تجاوز الملف
   - أكمل معالجة بقية الملفات
   - اذكره في الملخص النهائي

2. **فشل تنزيل المحتوى**
   - أعد المحاولة مرة واحدة بعد ثانيتين
   - إذا استمر الفشل، سجّله كخطأ وتابع
   - لا توقف الدفعة كاملة بسبب ملف واحد

3. **فشل الكتابة على الملف**
   - تحقق من صلاحيات الملف
   - تحقق من توفر مساحة كافية على القرص
   - اعرض الخطأ المحدد للمستخدم

## مثال على الاستخدام

### المثال 1: تحديث كامل للتوثيق

**المستخدم**: "حدّث كل ملفات التوثيق في /Volumes/PARA/03_Resources/ai-docs/_kb/@platforms/anthropic/"

**رد الوكيل**:
```
سأحدّث ملفات التوثيق في هذا المجلد. سأبدأ أولًا بتحديد كل الملفات التمهيدية التي تحتوي على روابط مباشرة.

وجدت 96 ملف توثيق يحتوي على روابط من الإنترنت.

قبل أن أبدأ التحديث، هذه الخطة:
1. مقارنة كل ملف مع نسخته المنشورة على الإنترنت
2. تحديث الملفات التي تغيّر محتواها فقط
3. المعالجة على دفعات من 10 ملفات لتجنب انتهاء المهلة
4. تحديد معدل الطلبات إلى طلب واحد كل ثانية

من المتوقع أن تستغرق العملية تقريبًا 10 إلى 15 دقيقة. هل أبدأ؟
```

### المثال 2: تحديث محدد

**المستخدم**: "حدّث فقط توثيق الإعدادات داخل مجلد anthropic"

**رد الوكيل**:
```
سأحدّث ملفات توثيق الإعدادات فقط.

وجدت 5 ملفات داخل مجلد configuration/:
- configuration/settings.md
- configuration/model-config.md
- configuration/terminal-config.md
- configuration/memory.md
- configuration/statusline.md

سأبدأ التحديث الآن...
```

## تنسيق المخرجات

بعد اكتمال العملية، قدّم ملخصًا بهذا الشكل:

```
════════════════════════════════════════════════
ملخص تحديث التوثيق
════════════════════════════════════════════════
الملفات المحدّثة: 96
الملفات المتجاوزة لأنها محدّثة مسبقًا: 0
الأخطاء التي ظهرت: 0
إجمالي وقت المعالجة: حوالي 15 دقيقة

تمت مزامنة كل ملفات التوثيق مع مصادرها المنشورة على الإنترنت.
```

## ملفات ذات صلة

- `scripts/doc_update.py` - سكربت التحديث الرئيسي
- `references/url_patterns.md` - أنماط الروابط الشائعة لمواقع التوثيق
- `references/error_codes.md` - دليل التعامل مع رموز أخطاء HTTP