بازبینی و اعتبارسنجی

از lore:doc-reviewer برای اعتبارسنجی مستندات در برابر تعریف انجام‌شدن استفاده کنید، چه پیش از تحویل و چه برای ممیزی فایل‌های موجود.

lore:doc-reviewer <file-or-folder>

چه چیزی را بررسی می‌کند

بازبین، تعریف انجام‌شدن را ناحیه‌به‌ناحیه پیش می‌برد و نکات فنی را به‌جای چشمی، به‌صورت عینی بررسی می‌کند:

• منابع: حقایق به منابع تأییدشده برمی‌گردند؛ چیزی ساختگی نیست.
• ساختار: frontmatter معتبر؛ همه‌ی بخش‌های لازم حاضرند.
• سناریوها: هر کدام شماره‌دارند (سناریو ۱، سناریو ۲، …) و هدف، پیش‌شرط‌ها، جریان و پس‌شرط‌ها دارند، با تصاویر درون‌متنی در گام درست؛ هر جا سند از اسکرین‌شات ریسپانسیو استفاده کند، بخش نمای موبایل و تبلت وجود دارد. سناریویی که هیچ extension (شاخه‌های خطا و مرزی‌اش) ندارد به‌عنوان هشدار علامت می‌خورد، و پوشش extensionها در برابر تاکسونومی حالت‌های مرزی قالب مستندسازی سنجیده می‌شود.
• دقت: اصطلاحات سازگار؛ برچسب‌های رابط کاربری با منبع می‌خوانند؛ قواعد صریح‌اند.
• اعتبار فنی: لینک‌های داخلی کار می‌کنند؛ مسیرهای ارجاع و ذخیره‌ی تصاویر درست‌اند؛ تصویری جای اشتباه نیست؛ و سایت بدون خطا build می‌شود.
• زبان و سبک، و یک گزارش نهایی کامل.

حکم

هر بازبینی با یکی از سه نتیجه پایان می‌یابد:

حکم	معنی
✅ تأیید برای تحویل	هیچ خطای بازدارنده‌ای نیست.
⚠️ تأیید با هشدار	خطای بازدارنده نیست؛ مسائل غیربازدارنده یادداشت شده‌اند.
❌ مسدود، تحویل نده	خطاهای بازدارنده، هر کدام با یک اصلاح مشخص فهرست شده‌اند.

خوداعتبارسنجی خودکار

شما به‌ندرت این را برای خروجی تازه دستی اجرا می‌کنید: هر اسکیل تولیدکننده (figma، brief، site) در پایان ساب‌اجنت فقط-خواندنی lore:doc-validator را فرامی‌خواند. اعتبارسنج همان روش را اعمال می‌کند، بررسی‌های فنی عینی را اجرا می‌کند، و گزارش ساختارمند را برمی‌گرداند، پس کیفیت پیش از تحویل هر چیزی تضمین می‌شود. این بازبینی اول روال عادی است و بدون پرسش انجام می‌شود. lore:doc-reviewer را خودتان اجرا کنید تا اسناد قدیمی‌تر یا یک پوشه‌ی کامل را ممیزی کنید.

این کار باید چند دور طول بکشد

یک بازبینی، بعد اصلاح‌ها، و حداکثر یکی دیگر. اگر می‌بینید بازبینی پشت بازبینی می‌آید، ایراد از فرآیند است نه از سند؛ و Lore ساخته شده تا جلوی همین را بگیرد، نه اینکه تا آخر همراهی‌اش کند.

سه قاعده این کار را می‌کنند:

• حکم سبز، پایان همان تحویل است. هر چیزی که بعد از آن ویرایش شود، کار تازه و بازبینی‌نشده است، هر اندازه هم کوچک باشد. نوبت متوقف می‌شود و از شما پرسیده می‌شود چه می‌خواهید، با شرح ریسک: بازبینی دوباره‌ی فقط همان فایل‌های تغییرکرده، یا تأیید تحویل به همین شکل. آنچه تأیید می‌کنید به همان محتوای دقیق گره می‌خورد، پس ویرایش بعدی بی‌سروصدا تأیید را بازنشسته می‌کند.
• اصلاح‌ها یکجا اعمال می‌شوند، و فایلی وسط بازبینی ویرایش نمی‌شود. درهم‌آمیختن اصلاح‌ها با دورها همان چیزی است که یک تحویل را هفت‌تا می‌کند. در اجرایی که این قواعد از آن بیرون آمد، چهار دور از هفت دور ایرادی یافتند که دور قبل وجود نداشت، و تنها دو دوری که پاک برگشتند، همان دو دوری بودند که اصلاح‌ها یکجا رفتند و چیزی زیر دست بازبین تکان نخورد.
• دو دور پیاپی که ایرادشان از اصلاح‌های دور قبل آمده، یعنی توقف. به‌جای تلاش سوم، موضوع با شمار دورها به شما گزارش می‌شود. هر یافته برچسب می‌خورد که از قبل وجود داشته یا پس از آخرین بازبینی سبز وارد شده، پس «اعتبارسنج مدام گیر می‌دهد» به‌روشنی از «اصلاح‌های ما مدام چیزی را خراب می‌کنند» جدا می‌شود.

خود بازبین هیچ‌چیز را ویرایش نمی‌کند؛ فقط-خواندنی است و همیشه بوده. اصلاح‌کردن پیش‌تر بر عهده‌ی ایجنت اصلی بود و حلقه دقیقاً از همان‌جا می‌آمد: عاملی که یک ادعا را تولید کرده، بدترین گزینه برای تصمیم‌گیری درباره‌ی اینکه کدام بخشش عوض شود. پس حالا دسته به lore:doc-reviser می‌رود، که فقط چیزی را ویرایش می‌کند که یافته‌ها نامش برده‌اند و نمی‌تواند واکشی کند یا فایل بسازد؛ و تا وقتی حکم بازدارنده است، یک هوک هر ویرایشی را که از راه دیگری انجام شود رد می‌کند. یافته‌هایی که اصلاح متن نیستند اصلاً به او نمی‌رسند: رسید جامانده به جمع‌آوری منابع برمی‌گردد و تصمیم محصولی به شما.

دو چیز که صادقانه باید گفت از عهده‌اش برنمی‌آید: بازبینی نمونه‌برداری است نه اثبات (فهرست چیزهایی که می‌شود بررسی کرد بی‌پایان است)، و بعضی بررسی‌ها تا وقتی بررسی‌های پیش‌تر تثبیت نشده‌اند اصلاً ممکن نیستند. پس دور دوم گاهی بجاست. دور چهارم یک هشدار است.