بازگشت به مهندسی مدرن و کار با هوش مصنوعی · فصل ۱ — از خواسته‌ی مبهم تا قرارداد قابل اجرا · 11

یک تعریف اجرایی کامل بساز

اجزای مسئله، scope، done و plan را جداگانه می‌شناسد اما هنوز آن‌ها را به یک spec اجرایی متصل نکرده است. Implementation-Ready Spec تولید می‌کند که قبل از coding قابل review است.

Build a complete implementation-ready specification — en-US

خلاصهٔ درس

اجزای مسئله، scope، done و plan را جداگانه می‌شناسد اما هنوز آن‌ها را به یک spec اجرایی متصل نکرده است.

Implementation-Ready Spec تولید می‌کند که قبل از coding قابل review است.

خروجی این درس

Implementation-Ready Spec تولید می‌کند که قبل از coding قابل review است.

پیش‌نیازها

تصمیم‌های پراکنده را به یک قرارداد قابل اجرا تبدیل کنید

یک stakeholder می‌گوید: «در فهرست کارها، فقط taskهای ناتمام را هم بتوانم ببینم.» تا اینجا شما مسئله را روشن کرده‌اید، مرز scope را جدا کرده‌اید، معیارهای Done را نوشته‌اید و plan پیشنهادی را پیش از edit نقد کرده‌اید. با این حال اگر این چهار خروجی در فایل‌ها یا گفتگوهای جدا بمانند، اجراکننده هنوز باید بین آن‌ها ارتباط بسازد و ممکن است یک تصمیم مهم را حدس بزند.

در این درس Implementation-Ready Spec v1 می‌سازید: یک specification واحد و قابل review که Problem Brief، Scope Box، constraints، Done/acceptance evidence و plan تأییدشده با assumptionهای آشکار را کنار هم قرار می‌دهد. هر criterion باید از یک need/problem/scope/constraint منبع قابل اشاره آغاز شود و تا plan step/evidence قابل دنبال‌کردن باشد؛ هر contradiction یا blocking unknown باید پیش از وضعیت READY بسته شود؛ و اگر executable example مفید بود، فقط به‌عنوان یک تکنیک داخل spec استفاده می‌شود، نه تعریف کل spec.

این درس هنوز taskها یا vertical sliceهای اجرا را تولید نمی‌کند. FND-002 همین spec کامل را می‌گیرد و آن را برای تحویل خرد می‌کند؛ این درس آن مسئولیت را جذب نمی‌کند.

زمان فعال تقریبی: ۵۵ دقیقه.

این درس برای شماست اگر: Problem Brief، Scope Box، Done Matrix و Plan Review دارید اما هنوز آن‌ها را به یک artifact واحد، traceable و قابل داوری تبدیل نکرده‌اید.

این درس برای این کارها نیست: نوشتن یک prompt بلند به‌جای spec، تبدیل اجباری همه requirementها به Gherkin، شروع task decomposition، حدس‌زدن unknownهای blocking، یا پیاده‌سازی کد.

پیش‌نیاز سخت — FND-001-P04: باید بتوانید یک plan مشخص را پیش از edit نقد کنید و تصمیم انسانی ACCEPT/MODIFY/REJECT را با evidence ثبت کنید.

پروب کوتاه پیش‌نیاز

هویت packet این پروب از قبل بسته است: spec_version=PREREQ-SPEC-v3 و plan_version=PREREQ-PLAN-v2. همین packet محدود را بررسی کنید و fact اجراییِ گمشده اختراع نکنید.

Packet منبع:

  • SCOPE-P04-01: به فهرست موجود taskها انتخاب All / Unfinished اضافه شود؛ persistence جدید مجاز نیست.
  • AC-P04-01: در حالت Unfinished، taskهای completed پنهان و taskهای unfinished قابل مشاهده بمانند.
  • AC-P04-02: بازگشت به All مجموعهٔ عادیِ قابل مشاهده را برگرداند.
  • CONSTRAINT-P04-01: schema/storage مربوط به task تغییر نکند.

Plan سه‌مرحله‌ایِ بررسی‌شده:

  1. PRE-PLAN-01 — selector نما را به state فعلی list وصل کند. Trace اصلی: SCOPE-P04-01. unknown تصمیم‌ساز: U-P04-01 = integration point این selector هنوز inspect نشده است. verification لازم پیش از edit: V-P04-01 owner/integration point فعلی view-state را بررسی کند.
  2. PRE-PLAN-02 — نمای Unfinished را از status موجود task بسازد. Trace اصلی: AC-P04-01. fact بررسی‌شده: VF-P04-01 = contract فعلی list معنی completed/unfinished را در اختیار می‌گذارد. verification لازم: V-P04-02 این معنا را روی نمونهٔ mixed-status تأیید کند.
  3. PRE-PLAN-03 — رفتار برگشت Unfinished → All و عدم تغییر storage/schema را verify کند. Trace اصلی: AC-P04-02؛ constraint check ثانویه: CONSTRAINT-P04-01. fact بررسی‌شده: VF-P04-02 = هیچ تغییر schema/storage مجاز نیست. verification لازم: V-P04-03 تست برگشت به All و inspection عدم تغییر contract را انجام دهد.

برای PRE-PLAN-01..03 سه خط review بنویسید: Trace، assumption/unknown تصمیم‌ساز یا verification fact داده‌شده، و verification. سپس یک تصمیم انسانی ACCEPT/MODIFY/REJECT بدهید و دلیل را صریحاً به هر دو نسخهٔ بررسی‌شده متصل کنید.

PASS: هیچ step بدون Trace معتبر نباشد؛ U-P04-01 به fact تبدیل نشود؛ verification پیش از edit روشن باشد؛ و decision + reason همراه با همان spec_version و plan_version ثبت شود.

اگر probe fail شد، فقط همان مهارت متناظر در FND-001-P04 را repair کنید: اگر step منبع/criterion اصلی ندارد، Trace assignment؛ اگر unknown حدس زده شده، assumption/unknown + verification پیش از edit؛ و اگر verdict به هر دو نسخه وصل نیست، decision record نسخه‌بندی‌شده. Spec کامل نمی‌تواند plan تأییدنشده یا assumption پنهان را معتبر کند.

میزان راهنمایی مناسب را انتخاب کنید

همهٔ مسیرها به یک artifact و یک evidence bar می‌رسند؛ تفاوت فقط در مقدار scaffold است.

پروب چهارمفهومی مسیر

بدون خواندن ادامه، این چهار سؤال را جواب دهید:

  1. Implementation-ready specification: چرا یک spec آمادهٔ اجرا با یک prompt طولانی یا یک سند صرفاً توضیحی یکی نیست؟
  2. Traceability: اگر test پاس شده اما معلوم نیست کدام criterion را پوشش می‌دهد، چه چیزی از spec کم است؟
  3. Ambiguity/contradiction audit: اگر دو بخش spec رفتار متناقضی تعریف کنند، آیا می‌توان یکی را به AI سپرد تا «منطقی‌ترین» را انتخاب کند؟
  4. Executable example: چه زمانی Given/When/Then مفید است و چرا نباید همهٔ constraintها را مجبور کرد در این قالب جا شوند؟

۴/۴ → Fast Path؛ ۲–۳/۴ → فقط مفهوم‌های شکست‌خورده را repair کنید؛ ۰–۱/۴ → مسیر پایه.

  • پایه: کیس فیلتر فهرست کارها را با قالب خالی و کاملِ قابل استفادهٔ مجدد دنبال کنید.
  • ترمیم: فقط distinction آسیب‌دیده را بازسازی کنید.
  • باتجربه/Fast Path: مستقیم به کیس مستقل بروید؛ متن کمتر است اما contradiction/unknown و boundary pressure بیشتر است.

Fast Path evidence bar را کاهش نمی‌دهد.

مدل ذهنی: تعریف اجرایی محل اتصال تصمیم‌هاست، نه انبار متن

Implementation-Ready Spec v1 آخرین نقطهٔ این زنجیره قبل از decomposition است:

Problem → Scope/Constraints → Done criteria → Reviewed Plan → Implementation-Ready Spec → FND-002 decomposition

چهار مفهوم داخل این artifact نقش متفاوت دارند:

مفهومسؤال اصلیشاهد کافی
Implementation-ready specآیا یک اجراکنندهٔ جدید می‌تواند goal، boundary، done و plan gate را بدون حدس بازسازی کند؟artifact مستقل و قابل review
Traceabilityچرا هر criterion، plan step و evidence وجود دارد و از کدام need/problem/scope/constraint آمده است؟زنجیرهٔ source need/problem/scope/constraint → criterion → plan → evidence و نبود orphan
Ambiguity/contradiction auditآیا دو تفسیر تصمیم‌ساز یا unknown مسدودکننده باقی مانده؟صفر contradiction حل‌نشده و صفر blocking unknown
Executable exampleآیا یک rule رفتاری از یک مثال observable سود می‌برد؟مثال مرتبط با criterion، بدون پنهان‌کردن implementation داخل step

یک spec خوب الزاماً بزرگ نیست. ارزش آن از اتصال تصمیم‌ها می‌آید، نه حجم documentation.

چهار مفهوم پایه

۱. تعریف آمادهٔ پیاده‌سازی

بسته‌ای واحد است که problem، scope، constraints، acceptance evidence و plan-approved assumptions را به اندازه‌ای روشن کنار هم می‌گذارد که اجرا بدون تصمیم‌سازی حدسی شروع شود. «آمادهٔ پیاده‌سازی» یعنی artifact برای اجرا و review کافی است؛ به معنی آن نیست که خودش machine-executable باشد.

۲. ردیابی تصمیم / Traceability

Traceability رابطهٔ قابل دنبال‌کردن میان مسئله، محدوده، criterion، plan step و evidence است. یک criterion بدون مسیر plan/evidence، یا یک plan/evidence بدون منبع، orphan است. Traceability با زیادنوشتن یکی نیست؛ یک جدول کوچک با IDهای پایدار می‌تواند از چند صفحه prose دقیق‌تر باشد.

۳. ممیزی ابهام و تعارض

پیش از READY، واژه‌های چندمعنا، تصمیم‌های متناقض و blocking unknownها را پیدا کنید. proofreading کافی نیست: ممکن است دو جمله از نظر نگارشی عالی باشند اما رفتار متفاوتی تعریف کنند. اگر unknown تصمیم‌ساز هنوز باز است، آن را OPEN_BLOCKING نگه دارید؛ spec را با حدس «کامل» نکنید.

۴. مثال اجرایی اختیاری / Executable example

برای ruleهای رفتاری مناسب می‌توان یک مثال Given/When/Then یا معادل ساده نوشت که context، event و observable outcome را روشن کند. در ابزارهایی مانند Cucumber چنین مثال‌هایی می‌توانند به step definition و تست متصل شوند. این تکنیک اختیاری است؛ constraint معماری، scope boundary یا تصمیم انسانی لازم نیست به زور به scenario تبدیل شود.

ساخت تعریف اجرایی آمادهٔ پیاده‌سازی

ورودی‌ها را پاک نکنید یا دوباره از صفر ننویسید. آن‌ها را به یک قرارداد traceable وصل کنید:

  1. هویت و نسخه: خروجی یک ID/version دارد و هویت/نسخهٔ ورودی‌های Problem Brief، Scope Box، Done Matrix و Plan Review را ثبت می‌کند؛ رکورد Plan Review نیز spec_version و plan_version بررسی‌شده را نگه می‌دارد.
  2. Problem/Outcome: مسئله و نتیجهٔ مطلوب را کوتاه و بدون راه‌حل‌سازی دوباره بیان می‌کند.
  3. Scope Box: IN، OUT و constraints را جدا نگه می‌دارد.
  4. Acceptance Matrix: criterionهای observable را با ID پایدار ثبت می‌کند.
  5. Reviewed Plan: plan تأییدشده و assumptionهایی که gate انسانی اجازهٔ استفاده از آن‌ها را داده ثبت می‌شوند؛ assumption پنهان ممنوع است.
  6. Trace Map: هر ردیف از یک need/problem/scope/constraint منبع شروع می‌شود، به criterion مشخص می‌رسد و سپس به plan step و evidence وصل می‌شود. هیچ criterion، plan step یا evidence نباید بدون منبع بماند.
  7. Readiness Audit: contradictionها و unknownهای blocking باید صفر باشند. unknown غیرمسدودکننده فقط با owner، impact و follow-up روشن می‌تواند باقی بماند.
  8. Optional executable-example decision: برای هر rule مناسب، تصمیم را ثبت کنید: USED همراه با مثال observable و link به criterion، یا NOT_USED همراه با دلیل محدود و روشن.
  9. Boundary note: چیزی که متعلق به FND-002 است—task breakdown، vertical slicing و sequencing تحویل—در spec تولید نمی‌شود.

قالب خالی و قابل استفادهٔ مجدد

این قالب فقط فیلدهای همین درس را دارد؛ task breakdown یا vertical slicing به آن اضافه نکنید.

Spec ID: <id>
Spec version: <version>
Input artifact versions:
  Problem Brief: <id/version>
  Scope Box: <id/version>
  Done Matrix: <id/version>
  Plan Review record: <id/version>
Plan Review binding:
  spec_version: <reviewed version>
  plan_version: <reviewed version>
  gate: <ACCEPT|MODIFY|REJECT as supplied by the reviewed record>
Problem / Outcome: <bounded statement>
Scope IN: <items>
Scope OUT: <items>
Constraints: <items>
Acceptance: <AC IDs + observable criteria>
Reviewed Plan: <PLAN IDs + approved assumptions>
Trace Map: <source need/problem/scope/constraint → criterion → plan step → evidence>
Readiness Audit: <unresolved contradictions + blocking unknowns>
Executable-example decision: <USED + criterion-linked example | NOT_USED + bounded rationale>
FND-002 boundary: <task breakdown / vertical slicing / delivery sequencing remain for FND-002>

حداقل ردیف ردیابی:

منبع نیاز/مسئله/محدوده/قیدمعیارگام برنامهشاهدوضعیت
SCOPE-IN-02AC-01PLAN-02EV-01linked

اگر AC-01 شاهد ندارد، خروجی READY نیست. اگر PLAN-02 یا EV-01 به هیچ منبع need/problem/scope/constraint و criterionی برنمی‌گردد، باید حذف یا دوباره توجیه شود.

AI می‌تواند wording پیشنهاد دهد، orphanها را پیدا کند، contradiction احتمالی را flag کند یا consistency را critique کند؛ اما scope، unknown closure، acceptance و READY decision انسانی و evidence-backed می‌ماند.

مثال حل‌شده: فیلتر کارهای ناتمام

در کیس مشترک، فهرست موجود taskهای completed و unfinished را دارد. درخواست این است که کاربر بتواند «All» یا «Unfinished» را ببیند، بدون اینکه persistence جدید، schema change، redesign یا cleanup نامرتبط وارد scope شود. فرض می‌کنیم Plan Review مرحلهٔ قبل مسیر انتخاب‌شده را با evidence بررسی و approve کرده است؛ این درس plan را دوباره طراحی نمی‌کند.

بخش‌های اصلی تعریف اجرایی

هویت خروجی: spec_id=TASK-FILTER-SPEC؛ spec_version=v1

نسخهٔ ورودی‌ها: Problem Brief=TASK-FILTER-PB-v1؛ Scope Box=TASK-FILTER-SCOPE-v1؛ Done Matrix=TASK-FILTER-DONE-v1؛ Plan Review record=TASK-FILTER-PR-v1

Plan Review binding: spec_version=TASK-FILTER-REQ-v1؛ plan_version=TASK-FILTER-PLAN-v2؛ gate=ACCEPT

Statementهای منبع با شناسهٔ پایدار:

  • NEED-01: کاربر باید بتواند روی کارهای باقی‌مانده تمرکز کند، بدون تغییر دادهٔ اصلی task.
  • SCOPE-IN-01: کاربر می‌تواند بین All و Unfinished جابه‌جا شود و دوباره به All برگردد.
  • SCOPE-IN-02: در Unfinished، taskهای completed پنهان و taskهای unfinished قابل مشاهده می‌مانند.
  • SCOPE-OUT-01: persistence فیلتر، redesign صفحه و cleanup نامرتبط خارج از scope است.
  • CONSTRAINT-01: schema/storage contract مربوط به task و معنی completed/unfinished تغییر نمی‌کند.

Problem: NEED-01.

Scope IN: SCOPE-IN-01؛ SCOPE-IN-02.

Scope OUT: SCOPE-OUT-01.

Constraints: CONSTRAINT-01.

Acceptance:

  • AC-01: در حالت Unfinished، task completed نمایش داده نمی‌شود و task unfinished قابل مشاهده می‌ماند.
  • AC-02: بازگشت به All، مجموعهٔ قابل مشاهدهٔ معمول را برمی‌گرداند.
  • AC-03: failure یا حالت مرزی باعث تغییر schema یا persistence جدید نمی‌شود.

Reviewed plan:

  • PLAN-01: کنترل انتخاب view را به state فعلی list متصل کن.
  • PLAN-02: view ناتمام را با status موجود taskها بساز و boundaryهای scope را حفظ کن.
  • PLAN-03: mixed-status، all-completed و برگشت به All را verify کن؛ contract/schema را برای عدم تغییر inspect کن.

Trace map:

منبعمعیاربرنامهشاهدنتیجهٔ مورد انتظار
SCOPE-IN-02AC-01PLAN-02EV-01 mixed-status checkفقط unfinished دیده شود
SCOPE-IN-01AC-02PLAN-01/02EV-02 toggle-back checkAll دوباره کامل باشد
CONSTRAINT-01AC-03PLAN-02/03EV-03 contract/schema inspectionتغییر contract وجود نداشته باشد

Readiness audit: contradiction حل‌نشده = ۰؛ blocking unknown = ۰. اگر evidence جدید نشان دهد plan با data flow واقعی سازگار نیست، این مقدار باید فوراً از READY خارج شود و Plan Review باز شود.

مثال اجرایی اختیاری برای AC-01

Scenario: Show unfinished tasks only
  Given the task list contains completed and unfinished tasks
  When the user selects Unfinished
  Then only unfinished tasks are shown

Executable-example decision: USED برای AC-01، چون رفتار فیلتر observable است و مثال به همان criterion لینک می‌شود. این scenario فقط یک rule رفتاری را روشن می‌کند. OUT-of-scopeها، schema constraint و approval history همچنان در بخش‌های دیگر spec می‌مانند.

چهار شکست محتمل

شکست ۱: تعریف اجرایی به یک دستور طولانی تبدیل می‌شود

همهٔ تصمیم‌ها در prose هستند اما ID، trace یا readiness state ندارند. اجراکننده باید خودش ارتباط‌ها را حدس بزند. Repair: artifact را به Problem/Scope/Acceptance/Plan/Trace/Audit بخش‌بندی کنید و orphanها را پیدا کنید.

شکست ۲: آزمون پاس است اما معیار معلوم نیست

EV-07 = PASS ارزش کمی دارد اگر ندانیم کدام acceptance را اثبات می‌کند. Repair: evidence را به criterion مشخص وصل کنید؛ evidence بدون منبع و criterion بدون evidence هر دو defect هستند.

شکست ۳: تعارض با روان‌نویسی پنهان می‌شود

یک بخش می‌گوید filter persistence خارج از scope است و بخش دیگری می‌گوید انتخاب کاربر باید بعد از reload حفظ شود. AI ممکن است یکی را بی‌صدا ترجیح دهد. Repair: contradiction را صریح ثبت کنید، owner/evidence لازم را مشخص کنید و READY را تا حل آن متوقف کنید.

شکست ۴: همهٔ نیازمندی‌ها به Gherkin اجبار می‌شوند

مثال رفتاری مفید است، اما اگر architecture constraint یا scope boundary را به زور به scenario تبدیل کنید، بخشی از معنا گم یا مصنوعی می‌شود. Repair: executable example را فقط برای رفتار observable مناسب به کار ببرید و آن را به criterion لینک کنید.

پل مسیر باتجربه: وقتی خروجی‌ها با هم سازگار نیستند

فرض کنید Scope Box می‌گوید «filter persistence خارج از scope است»، اما یک note قدیمی در plan می‌گوید «selection را در URL ذخیره کن». این اختلاف را با معماری‌پسندترین انتخاب حل نکنید. ابتدا authority و نسخهٔ هر statement را بررسی کنید. اگر note متعلق به plan قدیمی است، آن را stale/deprecated کنید؛ اگر واقعاً requirement جدید است، spec فعلی هنوز READY نیست و باید change control انجام شود.

برای مسیر باتجربه سه فشار اضافه کنید:

  • یک dependency شناخته‌شده که contract دقیقش هنوز روشن نیست؛
  • دو evidence که تفسیرهای متفاوت می‌دهند؛
  • یک statement با زبان روان اما دو معنای تصمیم‌ساز.

هدف این نیست که spec همیشه READY اعلام شود. گاهی پاسخ درست NOT_READY — blocking contradiction است. ساختن certainty مصنوعی شکست است، نه سرعت.

قالب‌های مختلف و بده‌بستان آن‌ها

  • Prose-first spec: خواندنش طبیعی است، اما trace و orphan detection ممکن است سخت شود.
  • Matrix-first spec: برای review و traceability قوی است، اما اگر بدون context باشد می‌تواند مکانیکی و کم‌معنا شود.
  • Issue/template-based spec: برای workflow تیمی مناسب است، اما template نباید authority تصمیم را جایگزین کند.
  • Executable-example-heavy: برای رفتارهای قابل مشاهده مفید است، اما کل specification را پوشش نمی‌دهد.

Implementation-Ready Spec v1 به یک ابزار یا format خاص وابسته نیست. invariantها مهم‌اند: problem و boundary روشن، acceptance قابل داوری، plan/evidence traceable، audit بدون blocker، و human ownership.

تمرین هدایت‌شده و مستقل

تمرین هدایت‌شده — جست‌وجوی سفارش

Packet:

  • NEED-01: کاربر باید سفارش را با شمارهٔ کامل سفارش پیدا کند.
  • SCOPE-IN-01: exact order-number search روی orders page.
  • SCOPE-OUT-01: fuzzy search، جست‌وجوی نام مشتری، redesign.
  • CONSTRAINT-01: order schema تغییر نمی‌کند.
  • Done: exact match قابل مشاهده؛ no-match صریح؛ مسیر فهرست فعلی regression ندارد.
  • Input versions: Problem Brief=ORDER-PB-v1؛ Scope Box=ORDER-SCOPE-v1؛ Done Matrix=ORDER-DONE-v1؛ Plan Review record=ORDER-PR-v1.
  • Plan Review binding: spec_version=ORDER-REQ-v1؛ plan_version=ORDER-PLAN-v2؛ gate=ACCEPT.
  • Reviewed Plan: PLAN-01 دریافت شمارهٔ کامل؛ PLAN-02 استفاده از lookup capability تأییدشده؛ PLAN-03 render نتیجهٔ match/no-match؛ PLAN-04 verification مجموعهٔ match/no-match/regression.
  • Evidence packet: EV-01 lookup-capability review=verified؛ EV-02 exact/no-match acceptance packet=available؛ EV-03 existing-list regression verification=required.

Implementation-Ready Spec v1 بسازید. حداقل سه acceptance ID و سه ردیف کامل source → criterion → plan → evidence، یک readiness audit، یک boundary note برای FND-002 و یک Executable-example decision داشته باشد: USED با مثال لینک‌شده به criterion یا NOT_USED با دلیل محدود. task decomposition ننویسید.

تمرین مستقل مسیر سریع — نوسازی آواتار

Change request و packet بسته:

  • NEED-A1: پس از avatar replacement موفق، تصویر جدید در visit بعدی profile قابل مشاهده باشد.
  • NEED-A2: failure باید تصویر فعلی را حفظ و error واضح نشان دهد.
  • CONSTRAINT-A1: upload API contract و storage provider تغییر نمی‌کنند.
  • SCOPE-OUT-A1: crop editor، avatar history و profile redesign خارج از scope هستند.
  • Input versions: Problem Brief=AVATAR-PB-v1؛ Scope Box=AVATAR-SCOPE-v1؛ Done Matrix=AVATAR-DONE-v1؛ Plan Review record=AVATAR-PR-v1.
  • Plan Review binding: spec_version=AVATAR-REQ-v1؛ plan_version=AVATAR-PLAN-v2؛ gate=ACCEPT.
  • Reviewed Plan: PLAN-A1 نتیجهٔ success/failure قرارداد upload موجود را مصرف می‌کند؛ PLAN-A2 در success مسیر cache دارای owner شناخته‌شده را refresh می‌کند تا visit بعدی تصویر جدید را بخواند؛ PLAN-A3 در failure تصویر فعلی را حفظ و error واضح را نمایش می‌دهد؛ PLAN-A4 success/failure و عدم تغییر API/provider را verify می‌کند.
  • Evidence packet: EV-A1 upload-contract inspection=verified؛ EV-A2 cache-ownership record=verified؛ EV-A3 next-visit success verification=required؛ EV-A4 failure-preservation/error verification=required؛ EV-A5 API/provider non-change inspection=required.
  • Packet audit state: unresolved contradiction=0؛ blocking unknown=0 برای همین scope بسته.

یک Implementation-Ready Spec v1 مستقل بسازید که:

  1. problem/scope/constraints را بدون copy کردن wording کیس فیلتر بیان کند؛
  2. success و failure را با criterionهای جدا ثبت کند؛
  3. هر criterion را از source نام‌دار تا plan/evidence ردیابی کند؛
  4. readiness را فقط بر اساس همین packet اعلام کند؛
  5. برای executable example صریحاً USED + criterion-linked example یا NOT_USED + bounded rationale ثبت کند؛
  6. صریحاً بنویسد decomposition به tasks/vertical slices متعلق به FND-002 است.

اگر چیزی بیرون از این packet برای decision لازم شد، READY را حدس نزنید؛ defect را ثبت کنید.

بررسی آمادگی: چه زمانی تعریف اجرایی واقعاً آماده است؟

قبل از اعلام READY، این پنج سؤال را جواب دهید:

  1. آیا یک خوانندهٔ جدید می‌تواند problem، boundary، done و plan gate را بدون context مخفی بازسازی کند؟
  2. آیا هر criterion از یک need/problem/scope/constraint نام‌دار تا plan/evidence ردیابی می‌شود و هیچ plan/evidence orphan نیست؟
  3. آیا contradiction حل‌نشده و blocking unknown هر دو صفرند؟
  4. آیا تصمیم executable example ثبت شده است—USED با link به criterion یا NOT_USED با دلیل محدود—و در حالت USED، implementation detail داخل step پنهان نشده است؟
  5. آیا spec responsibility درس بعدی را جذب نکرده و تصمیم‌های blocking همچنان human-owned هستند؟

اگر هر پاسخ critical «نه» است، artifact هنوز implementation-ready نیست. machine validation می‌تواند structure و consistency را بررسی کند؛ sufficiency و acceptance نیازمند review انسانی است.

ارزیابی و انتقال

ارزیابی پنج لایه دارد: تعریف bounded، application روی artifact تازه، diagnosis شکست محتمل، decision انسانی روی statement مبهم، و transfer به domain جدید.

برای PASS در بخش‌های blocking باید:

  • هر چهار مفهوم داخل artifact قابل مشاهده باشند؛ برای مفهوم مثال اجرایی اختیاری، USED یا NOT_USED باید با شاهد/دلیل روشن ثبت شود;
  • Implementation-Ready Spec v1 مستقل از توضیح شفاهی قابل داوری باشد؛
  • مرز FND-002 حفظ شود؛
  • تصمیم نهاییِ آمادگی به AI واگذار نشود؛
  • transfer فقط تعویض اسم‌های کیس task-list نباشد.

Evidence نهایی این درس خود spec + trace/audit + decision record است. این درس implementation skill یا mastery کل canonical FND-001 را اثبات نمی‌کند.

منابع و تازگی

دو مرجع خارجی برای practiceهای این درس زمینهٔ مفیدی می‌دهند:

  • ISO/IEC/IEEE 29148:2018 همچنان Edition 2 منتشرشده است؛ Edition 3 بعدی هنوز در حال توسعه است و جای آن را نگرفته است.
  • مستندات رسمی Cucumber همچنان Gherkin/executable specifications و مثال‌های رفتاری Given/When/Then را توضیح می‌دهند. بنابراین در این درس executable example یک تکنیک اختیاری است، نه representation اجباری برای همهٔ requirementها.

این منابع از practiceهای requirements/specification مطرح‌شده در درس پشتیبانی می‌کنند؛ اما جای Problem، Scope، Done، Plan بررسی‌شده و evidence واقعیِ Implementation-Ready Spec v1 شما را نمی‌گیرند.

ارزیابی

پاسخ‌نامه‌ی این درس در بسته‌ی آموزش وجود ندارد؛ خودت جواب بده و صادقانه علامت بزن. «نیاز به مرور» درس را به صف تکرار می‌فرستد.

Q1 retrieval

Implementation-ready specification و executable specification را از هم جدا کنید. سپس توضیح دهید traceability چگونه یک need/problem/scope/constraint منبع را از criterion و plan step تا evidence قابل دنبال‌کردن می‌کند.

lesson ✗AI ✗notes ✗

Q2 application

کیس تازه — جست‌وجوی سفارش. Packet: `NEED-01`=کاربر سفارش را با شمارهٔ کامل پیدا کند؛ `SCOPE-IN-01`=exact order-number search؛ `SCOPE-OUT-01`=fuzzy/customer-name/redesign؛ `CONSTRAINT-01`=schema unchanged؛ Done=exact match visible، no-match explicit، existing list path without regression. Input versions: `Problem Brief=ORDER-PB-v1`، `Scope Box=ORDER-SCOPE-v1`، `Done Matrix=ORDER-DONE-v1`، `Plan Review record=ORDER-PR-v1`. Plan Review binding: `spec_version=ORDER-REQ-v1`، `plan_version=ORDER-PLAN-v2`، gate=`ACCEPT`. Reviewed Plan: `PLAN-01` receive full number؛ `PLAN-02` verified lookup capability؛ `PLAN-03` render match/no-match؛ `PLAN-04` verification. Evidence: `EV-01` lookup review=verified؛ `EV-02` exact/no-match acceptance packet=available؛ `EV-03` list-regression verification=required. یک `Implementation-Ready Spec v1` بسازید که حداقل سه acceptance ID، سه trace کامل `source→criterion→plan→evidence`، readiness audit، FND-002 boundary و تصمیم executable example (`USED` + criterion-linked example یا `NOT_USED` + bounded rationale) داشته باشد.

lesson ✗AI ✗notes ✗

Q3 diagnosis

این spec را diagnose کنید: `AC-02: no-match باید واضح باشد.` در trace table فقط `EV-09=PASS` آمده و هیچ plan step یا link به AC-02 ندارد. همچنین بخش دیگری می‌گوید no-match با empty screen بی‌پیام نمایش داده شود. حداقل دو defect را نام ببرید، آن‌ها را به مفهوم درست وصل کنید و repair مشخص بنویسید.

lesson ✗AI ✗notes ✗

Q4 decision

AI پیشنهاد می‌دهد: «برای یکدست‌شدن spec، همهٔ requirementها—including schema constraint و scope exclusions—را به Given/When/Then تبدیل کنیم و متن‌های دیگر را حذف کنیم.» یکی از `ACCEPT` / `MODIFY` / `REJECT` را انتخاب کنید و با evidence/boundary توضیح دهید. انتخاب را AI تعیین نمی‌کند.

lesson ✗AI ✗notes ✗

Q5 transfer

Transfer — Avatar refresh. Packet بسته: `NEED-A1`=پس از replacement موفق، avatar جدید در visit بعدی profile دیده شود؛ `NEED-A2`=failure تصویر فعلی را حفظ و error واضح نشان دهد؛ `CONSTRAINT-A1`=upload API/storage provider unchanged؛ `SCOPE-OUT-A1`=crop/history/redesign خارج از scope. Input versions: `Problem Brief=AVATAR-PB-v1`، `Scope Box=AVATAR-SCOPE-v1`، `Done Matrix=AVATAR-DONE-v1`، `Plan Review record=AVATAR-PR-v1`. Plan Review binding: `spec_version=AVATAR-REQ-v1`، `plan_version=AVATAR-PLAN-v2`، gate=`ACCEPT`. Reviewed Plan: `PLAN-A1` consume existing upload success/failure result؛ `PLAN-A2` success→refresh known-owner cache path؛ `PLAN-A3` failure→preserve current image + clear error؛ `PLAN-A4` verify behavior and API/provider non-change. Evidence: `EV-A1` upload-contract inspection=verified؛ `EV-A2` cache-ownership record=verified؛ `EV-A3` next-visit success verification=required؛ `EV-A4` failure-preservation/error verification=required؛ `EV-A5` API/provider non-change inspection=required. Packet audit: contradiction=0، blocking unknown=0 برای scope بسته. `Implementation-Ready Spec v1` بسازید؛ هر criterion را از source تا plan/evidence trace کنید؛ تصمیم executable example را `USED` + criterion-linked example یا `NOT_USED` + bounded rationale ثبت کنید؛ و دقیقاً مشخص کنید چه چیزی برای FND-002 باقی می‌ماند.

lesson ✗AI ✗notes ✗
ملاک‌های ارزیابی (rubric)

Canonical evidence descriptors are stored in questions.json; this Markdown index does not override them.

Implementation-ready specification, executable examples, and traceability

  • Critical: NO
  • Canonical descriptor: see Q1 expected evidence in questions.json.

Implementation-Ready Spec construction from a bounded packet

  • Critical: YES
  • Canonical descriptor: see Q2 expected evidence in questions.json.

Diagnosis and repair of traceability/contradiction defects

  • Critical: YES
  • Canonical descriptor: see Q3 expected evidence in questions.json.

Human decision on executable-example representation

  • Critical: YES
  • Canonical descriptor: see Q4 expected evidence in questions.json.

Changed-context transfer to an independent specification

  • Critical: YES
  • Canonical descriptor: see Q5 expected evidence in questions.json.

منابع و تازگی

· FOUNDATIONAL_STABLE
· PRACTICE_EVOLVING
· PRACTICE_EVOLVING
· TOOL_VOLATILE
· TOOL_VOLATILE

مطالعهٔ موارد (case studies)

REALISTIC

EDGE_OR_FAILURE

TRANSFER_NEAR

WRONG_APPROACH

رسانه و اسلایدهای درس

MAKNOW_FND-001-P05_FAILURE_REPAIR_v1.0.0.svg
-P05 FAILURE REPAIR v1.0.0.svg
MAKNOW_FND-001-P05_PRIMARY_MODEL_v1.0.0.svg
-P05 PRIMARY MODEL v1.0.0.svg
MAKNOW_FND-001-P05_TRACEABILITY_TABLE_v1.0.0.svg
-P05 TRACEABILITY TABLE v1.0.0.svg
MAKNOW_FND-001-P05_WORKED_EXAMPLE_v1.0.0.svg
-P05 WORKED EXAMPLE v1.0.0.svg

فایل‌های آموزشی (دانلود)

PPTX-P05 TEACHING DECK v1.0.0.pptxفایل‌های آموزشی (دانلود)
DOCX-P05 Implementation-Ready Spec v1 WORKSHEET v1.0.0.docxفایل‌های آموزشی (دانلود)
PDF-P05 Implementation-Ready Spec v1 WORKSHEET v1.0.0.pdfفایل‌های آموزشی (دانلود)