---
name: prompt-writer
description: تولید فایل پرامپت .md برای یک قابلیت یا باگ‌فیکس در پروژه ClinicPro. استفاده کن وقتی کاربر می‌گوید «یک پرامپت بنویس»، «پرامپت بساز»، «write a prompt»، «برام پرامپت بنویس برای X». این skill پروژه را تحلیل می‌کند، سپس یک فایل .md کامل در .claude/prompt/ می‌سازد و دستور اجرا را نمایش می‌دهد.
---

> **قبل از شروع، فایل `.claude/guidelines.md` را بخوان و همهٔ بخش‌های آن را اعمال کن — از جمله `§۰ Grill` که قبل از هر تغییر اجباری است** (اگر روت جلسه workspace است: `clinicpro/.claude/guidelines.md`). آن فایل «چگونه کار کردن» (درک مسئله، معیار پذیرش، تست، مستندات، SOLID، رفتار تحلیل‌گر) را تعیین می‌کند؛ این skill فقط قواعد stack و مسیرها و قالب خروجی را دارد. در تناقض، guidelines برنده است.

## نحوه دریافت ورودی

کاربر موضوع یا مشکل را توضیح می‌دهد. **ابهام = توقف**: اگر توضیح کافی نبود، همان اول یک سوال کوتاه بپرس و ادامه نده — نه وسط تحلیل.

---

## مراحل اجرا

### مرحله ۱ — درک موضوع

قبل از نوشتن پرامپت:

1. **موضوع را تحلیل کن**: باگ‌فیکس است یا قابلیت جدید؟
2. **فایل‌های مرتبط را شناسایی کن**:
   - Backend: `src/` — Controllers، Services، Entities، Repositories
   - Frontend: `assets/admin/pages/`، `assets/admin/components/`
   - مستندات: `docs/api/`
3. **APIهای موجود را بررسی کن**: `ddev exec php bin/console debug:router | grep api` — API جدید فقط وقتی هیچ اندپوینت موجودی، حتی با توسعه، کافی نباشد؛ دلیلش را در پرامپت بنویس
4. **کد مرتبط را بخوان**: فقط فایل‌هایی که مستقیم به موضوع مربوطند — کد واقعی، نه حافظه

بعد از خواندن، **مسئله را با کلمات خودت بازگو کن** و به کاربر نشان بده:
«مشکل این است که X؛ رفتار درست Y است؛ محدودهٔ تغییر فایل‌های Z». اگر این سه جمله را نمی‌توانی بنویسی، هنوز مسئله را نفهمیده‌ای — سوال بپرس.

**نقش تحلیل‌گر (guidelines §۶):** اگر راه‌حلی که کاربر خواسته اشتباه، ناقص یا پرریسک است، همین‌جا صریح و با دلیل بگو و منتظر تعیین تکلیف بمان — پرامپتِ یک راه‌حل غلط را ننویس. اگر چند راه‌حل جدی وجود دارد، کوتاه مقایسه کن (مزایا/معایب/ریسک) و دلیل انتخاب را در پرامپت ثبت کن.

### مرحله ۲ — نام‌گذاری فایل

نام فایل: `kebab-case`، توصیفی، کوتاه.

مثال‌ها:
- `fix-invitation-accept.md`
- `doctor-dashboard-stats.md`
- `clinic-gallery-upload.md`
- `appointment-sms-notification.md`

### مرحله ۳ — ساخت فایل پرامپت

فایل را در `.claude/prompt/<name>.md` بساز با این ساختار:

---

```markdown
# <عنوان واضح>

## زمینه

<یک پاراگراف: چرا این تغییر لازم است؟ وضعیت فعلی چیست؟>

## مشکل / هدف

<توضیح دقیق مشکل یا قابلیت مورد نیاز>

## معیار پذیرش

<چه چیزی باید درست کار کند تا «تمام» حساب شود — قابل تست، نه کلی>

- ✅ موفق: <رفتار درست در مسیر عادی — مثلاً «POST /api/v1/... با توکن ادمین → 200 و رکورد ذخیره می‌شود»>
- ❌ خطا: <رفتار درست در مسیر خطا — مثلاً «بدون permission → 403 با envelope خطا و کد از ErrorCodes»>
- ⚠️ مرزی: <حداقل یک حالت مرزی — لیست خالی، صفحه آخر pagination، تاریخ مرزی شمسی، …>

## فایل‌های مرتبط

| فایل | نقش |
|------|-----|
| `src/...` | ... |
| `assets/admin/...` | ... |

## وضعیت فعلی

<کد یا رفتار فعلی — کپی از کد واقعی پروژه، نه بازنویسی از حافظه؛ فقط بخش مرتبط>

```php / tsx
// کد فعلی مشکل‌دار یا ناقص
```

## وظایف

### ۱. <اولین وظیفه>

<توضیح دقیق + راه‌حل پیشنهادی>

```php / tsx
// نمونه کد یا pseudocode
```

**نحوه تست:** <دقیقاً چطور این وظیفه تست می‌شود — دستور، curl با داده واقعی، سناریوی UI — تا run-prompt مجبور نباشد تست را اختراع کند>

### ۲. <دومین وظیفه>

...

## نکات مهم

- <نکته معماری یا محدودیت مهم>
- <edge case که باید پوشش داده شود>
- <الگوی پروژه که باید رعایت شود؛ اگر راه‌حل از الگویی (Strategy، Factory، Event، …) استفاده می‌کند: نام الگو + دلیل انتخابش>
```

---

### قوانین محتوای پرامپت

**باید داشته باشد:**
- مسیر دقیق فایل‌هایی که باید تغییر کنند
- بخش «معیار پذیرش» با هر سه سناریو (موفق/خطا/مرزی) — **پرامپت بدون معیار پذیرش ناقص است**
- وضعیت فعلی کد (کپی از کد واقعی، نه توصیف کلی) — خود فایل پرامپت سند است
- راه‌حل پیشنهادی با نمونه کد؛ اگر الگو دارد، نام + دلیل
- «نحوه تست» برای هر وظیفه‌ای که منطق دارد
- edge caseها و الگوهای پروژه که باید رعایت شوند (BaseController، TanStack Query، Zod، ...)

**نباید داشته باشد:**
- توضیحات کلی و بدیهی
- کدی که از پروژه واقعی کپی نشده
- وظایف نامشخص مثل «بررسی کن» بدون مشخص کردن چه چیزی
- abstraction «برای آینده» — الگو فقط وقتی الان نیازش هست (guidelines §۵)

**قوانین خاص پروژه که باید در پرامپت منعکس شود:**
- Backend: همه controllerها از `BaseController` ارث می‌برند؛ پاسخ‌ها با `$this->success()` / `$this->paginated()` / `$this->error()`
- Controller نازک: منطق در Service، کوئری در Repository؛ وابستگی‌ها با constructor injection (نه `new`)
- خطاها با `AppException(ErrorCodes::ERR_XXX)` و پیام فارسی در `src/Shared/Constant/ErrorCodes.php`
- Frontend paginated: items از `data?.data`، total از `data?.meta?.totalRecords`
- Frontend single: از `data?.data` (ممکن است double-nested باشد)
- Category API: triple-nested → `data?.data?.data ?? []`
- تاریخ‌ها: Unix timestamp صحیح؛ نمایش با `formatDate()` شمسی
- اگر Entity تغییر کرد: migration لازم است
- مستندات: بعد از هر تغییر API، فایل مربوطه در `docs/api/` باید به‌روز شود
- اگر endpoint توسط سایت عمومی (`nobat724_front`) هم مصرف می‌شود، در پرامپت ذکر کن — تغییر قرارداد در build کلاینت خطا نمی‌دهد

### مرحله ۴ — خروجی نهایی

بعد از ساخت فایل، فقط این سه مورد را نمایش بده:

```
توضیح: <یک جمله توصیف پرامپت>
فایل پرامپت: .claude/prompt/<name>.md
دستور اجرا:

/run-prompt .claude/prompt/<name>.md
```

---

## مثال

```
کاربر: برام یک پرامپت بنویس — وقتی دکتر دعوت کلینیک را قبول می‌کند به لیست پزشکان اضافه نمی‌شود

→ بررسی می‌کنم...
  - src/ClinicInvitation/Service/ClinicInvitationService.php خوانده شد
  - متد accept() فقط status تغییر می‌دهد، clinic->getDoctors()->add() صدا نمی‌زند
  - Clinic entity دارای ManyToMany $doctors است

→ بازگویی: مشکل — accept() رابطه clinic_doctors را نمی‌سازد؛ رفتار درست — پزشک بعد از accept در لیست پزشکان کلینیک باشد؛ محدوده — ClinicInvitationService.php

→ فایل .claude/prompt/fix-invitation-accept.md ساخته شد
   (شامل معیار پذیرش: ✅ accept → پزشک در لیست / ❌ دعوت منقضی → خطا / ⚠️ accept تکراری → بدون رکورد تکراری)

توضیح: رفع باگ پذیرش دعوت — پزشک باید پس از accept به clinic_doctors اضافه شود.
فایل پرامپت: .claude/prompt/fix-invitation-accept.md
دستور اجرا:

/run-prompt .claude/prompt/fix-invitation-accept.md
```