انضباط اشکال‌زدایی و یافتن علت ریشه‌ای

اصطلاح محوری: علت ریشه‌ای (Root Cause) زمان فعال تقریبی: ۷۵ دقیقه خروجی قابل دفاع: رکورد علت ریشه‌ای v1 (Root Cause Record v1)

از «یک چیزی خراب است» تا یک ادعای علّی محدود

یک سامانهٔ checkout فقط در مرز مشخصی از ترکیب کوپن و مالیات، عدد نهایی را غلط محاسبه می‌کند. سه ناحیهٔ کد در نگاه اول مشکوک‌اند. یک commit تازه هم وجود دارد که وسوسه می‌کند همان را مقصر بدانیم، و در log نیز هشداری دیده می‌شود که با رخداد خطا هم‌زمان است.

هیچ‌کدام از این‌ها هنوز علت نیستند. در این درس باید از یک نشانهٔ قابل تکرار به یک علت ریشه‌ای محدود برسید؛ آن هم با زنجیره‌ای از شواهد (Evidence) که بازبین بتواند بررسی کند: بازتولید، فرضیه‌های رقیب، probeهای تمایزدهنده، کاهش سطح خطا، بیان سازوکار علّی، اصلاح محدود و یک recurrence sensor که با بازگرداندن defect دوباره قرمز شود.

هدف این نیست که ثابت کنید هر خرابی فقط یک علت دارد. همچنین یک regression check محلی را با یک راهبرد آزمون (Test Strategy) کامل اشتباه نمی‌گیریم. اگر شواهد فقط یک مجموعه شرط یا یک contributing cause را پشتیبانی کند، همان را می‌نویسیم و دامنهٔ ادعا را بزرگ‌تر نمی‌کنیم.

در پایان، رکورد علت ریشه‌ای شما باید به این سؤال پاسخ دهد: «دقیقاً چه چیزی را مشاهده کردیم، چه توضیح‌هایی را آزمودیم، چه چیزی را رد کردیم، چه سازوکار محدودی باقی ماند، چه تغییری آن را اصلاح کرد، و چه شواهدی نشان می‌دهد defect می‌تواند دوباره شکار شود؟»

مسیر یادگیری؛ سطح پشتیبانی فرق می‌کند، معیار قبولی نه

سه مسیر دارید، اما خروجی نهایی و evidence bar برای هر سه یکسان است.

• Foundation: ابتدا تعریف‌ها، یک trace حل‌شده و قالب نیمه‌ساخت‌یافتهٔ Root Cause Record را ببینید؛ سپس این کمک‌ها حذف می‌شوند.
• Repair: اگر در یک checkpoint مشخص مشکل دارید، فقط همان بعد را ترمیم کنید؛ مثلاً فرق correlation و cause یا انتخاب probe تمایزدهنده. معیار نهایی پایین نمی‌آید.
• Experienced: می‌توانید توضیح‌های پایه را سریع‌تر رد کنید، اما باید همان reproduction، hypothesis ledger، محدودیت ادعا، transfer و تصمیم انسانی را تحویل دهید.

پیش‌نیاز عملی این درس، استفاده از نقشهٔ محدود repository از درس قبل است: باید بتوانید از رفتار مشاهده‌شده به چند anchor محتمل در کد برسید، نه اینکه کل repository را کورکورانه جست‌وجو کنید. اگر این اتصال برایتان شکننده است، یک bridge کوتاه بسازید: ورودی، مسیر اجرای قابل مشاهده، سه ناحیهٔ محتمل و نقطه‌ای که می‌توان رفتار را اندازه گرفت.

مدل ذهنی: symptom با cause یکی نیست

پنج مفهوم را جدا نگه دارید:

1. Symptom: اختلافی که می‌توانید مشاهده و توصیف کنید؛ مثلاً «برای subtotal مشخص، total با policy اعلام‌شده نمی‌خواند».
2. Correlation: دو رخداد با هم دیده می‌شوند؛ مثلاً یک warning هم‌زمان با خطا. correlation می‌تواند سرنخ باشد، نه اثبات.
3. Hypothesis: توضیحی قابل ردشدن دربارهٔ مکانیزم خطا؛ باید پیش‌بینی کند اگر درست باشد چه مشاهده‌ای خواهیم دید.
4. Cause / Root Cause: کوچک‌ترین سازوکار علّی یا مجموعه شرط‌هایی که evidence فعلی واقعاً پشتیبانی می‌کند. واژهٔ «ریشه‌ای» مجوز ادعای مطلق نیست.
5. Corrective action: تغییری که سازوکار پشتیبانی‌شده را اصلاح می‌کند. ناپدیدشدن symptom به‌تنهایی ثابت نمی‌کند corrective action علّی بوده است.

چرخهٔ کار را این‌گونه نگه دارید:

Observation → competing hypotheses → discriminating probe → update/reject → reduction → bounded causal statement → corrective change → recurrence evidence.

یک probe خوب فقط «اطلاعات بیشتر» تولید نمی‌کند؛ باید بین دست‌کم دو توضیح تمایز ایجاد کند. اگر نتیجهٔ probe در هر دو فرضیه یکسان است، information gain آن برای تصمیم فعلی کم است.

کنترل سریع

اگر تازه‌ترین commit را revert کرده‌اید و خطا ناپدید شده، هنوز ممکن است فقط مسیر اجرا تغییر کرده باشد. برای بالا بردن confidence باید نشان دهید revert دقیقاً چه مکانیزمی را تغییر داده و یک probe مستقل، توضیح‌های رقیب را ضعیف می‌کند.

لایهٔ پایه: قبل از توضیح دادن، failure را ببندید

۱) Reproduction note

یک reproduction خوب حداقل این فیلدها را دارد:

• Input: دادهٔ مشخصی که failure را فعال می‌کند.
• State / Preconditions: تنظیمات، نسخه، fixture یا state لازم.
• Expected behavior: نتیجه‌ای که contract یا policy می‌طلبد.
• Observed behavior: نتیجهٔ واقعی، با عدد یا خروجی قابل مشاهده.
• Repeat condition: چند بار و تحت چه شرطی تکرار شد.
• Boundary: نزدیک‌ترین حالت‌هایی که fail نمی‌شوند.

اگر فقط نوشته‌اید «گاهی checkout غلط می‌شود»، هنوز فضای failure بیش از حد بزرگ است.

۲) Hypothesis ledger

حداقل دو فرضیهٔ رقیب پیش از اصلاح بنویسید. برای هر فرضیه این موارد را ثبت کنید: پیش‌بینی، probe، نتیجه، وضعیت و probe بعدی. chronology مهم است چون نشان می‌دهد نتیجهٔ نهایی بعداً روی تاریخچه سوار نشده است.

۳) Reduction

ابعادی را حذف کنید که symptom بدون آن‌ها باقی می‌ماند. اگر failure با database واقعی و repository in-memory یکسان است، persistence در این reproduction خاص ضعیف‌تر می‌شود. Reduction به معنی «کوتاه کردن کد به هر قیمت» نیست؛ شرط اصلی این است که symptom حفظ شود.

۴) Root Cause Record v1

رکورد نهایی باید شامل reproduction، ledger، evidence ردشده، reduced case، causal statement، corrective change، recurrence sensor، limitations، disclosure استفاده از ابزار/AI و تصمیم نهایی باشد. یک روایت زیبا بدون evidence قابل بازرسی، artifact کافی نیست.

توضیح عمیق: چگونه confidence را بدون جهش بالا ببریم

فرضیه‌ها را طوری بنویسید که بتوانند ببازند

فرضیهٔ ضعیف: «احتمالاً tax code مشکل دارد.» فرضیهٔ بهتر: «اگر tax calculation خودش علت باشد، وقتی همان taxable base را مستقیم به tax function بدهیم باید همان اختلاف تولید شود.»

نسخهٔ دوم یک پیش‌بینی دارد. اگر تابع tax با ورودی کنترل‌شده مقدار درست بدهد، hypothesis ضعیف می‌شود و باید وضعیت آن در ledger تغییر کند.

probe تمایزدهنده بسازید

فرض کنید سه توضیح دارید:

• H1: discount اشتباه محاسبه می‌شود.
• H2: tax function روی base درست، نرخ اشتباه اعمال می‌کند.
• H3: wiring مقدار اشتباه را به tax function می‌فرستد.

چاپ یک log عمومی ممکن است هر سه را هم‌زمان زنده نگه دارد. اما ثبت سه مقدار subtotal, discounted_subtotal, taxable_base_passed در boundary اجرای tax می‌تواند H3 را از H1/H2 جدا کند. probe باید دقیقاً به یک decision boundary وصل باشد.

از reduction برای حذف توضیح‌های بی‌ربط استفاده کنید

یک failure کوچک‌شده که فقط با یک کوپن، یک نرخ و یک boundary رخ می‌دهد، بهتر از بازپخش تمام checkout است. اگر با repository جایگزین هم failure باقی بماند، noise مربوط به cache دیگر evidence علّی قوی نیست؛ حتی اگر در log هم‌زمان دیده شود.

causal statement را کوچک نگه دارید

بد ننویسید: «سیستم مالیاتی خراب بود.» بهتر: «در حالت X و شرط Y، مسیر wiring مقدار pre-discount را به tax function می‌داد؛ probe مستقیم نشان داد discount و tax function مستقل درست بودند و تغییر همین انتخاب base، reproduction را اصلاح کرد.»

اگر دو شرط با هم لازم‌اند، causal set را همان‌طور ثبت کنید. Root Cause لزوماً یک اسم فایل یا یک commit نیست.

recurrence sensor باید defect را تشخیص دهد

بعد از اصلاح، یک check اضافه کنید که قبل از fix fail می‌شد و بعد از fix pass می‌شود. سپس defect را به‌صورت کنترل‌شده reintroduce کنید. اگر sensor همچنان سبز ماند، sensor فقط وضعیت فعلی را تأیید می‌کند، نه recurrence را.

متن معادل نمودار «چرخهٔ شواهد تا recurrence»: از یک observation واحد، چند hypothesis شاخه می‌شوند. هر شاخه یک پیش‌بینی دارد. probe تمایزدهنده بعضی شاخه‌ها را رد می‌کند و بعضی را نگه می‌دارد. پس از reduction، یک causal statement محدود باقی می‌ماند. corrective change روی همان مکانیزم اعمال می‌شود و recurrence sensor با mutation کنترل‌شده بررسی می‌کند که defect قابل شکار است. هیچ شاخه‌ای صرفاً به دلیل «جدیدتر بودن commit» یا «وجود warning» برنده نمی‌شود.

مثال حل‌شده: یک مسیر پیوسته، نه چک‌لیست مکانیکی

در یک checkout آزمایشی، کوپن WELCOME5 باید ۵٪ تخفیف بدهد و سپس مالیات روی مبلغ تخفیف‌خورده اعمال شود. برای subtotal برابر ۲۰۰، مقدار مورد انتظار ۲۰۵٫۲۰ است، اما سیستم ۲۰۶٫۰۰ برمی‌گرداند.

Reproduction: ورودی و policy ثابت‌اند و failure در پنج اجرای پیاپی تکرار می‌شود. با کوپن دیگری failure وجود ندارد.

فرضیه‌ها:

• H1: موتور discount عدد اشتباه تولید می‌کند.
• H2: tax function نرخ یا rounding غلط دارد.
• H3: policy ذخیره‌شده برای این نوع کوپن، taxable base نادرست انتخاب می‌کند.

Probe 1: مقدار discount را در boundary خروجی discount اندازه می‌گیریم: ۱۰٫۰۰. H1 برای این case رد می‌شود.

Probe 2: tax function را با base=190 مستقیماً اجرا می‌کنیم: ۱۵٫۲۰. H2 برای این input ضعیف و رد می‌شود.

Probe 3: policy object بارگذاری‌شده را بررسی می‌کنیم و می‌بینیم یک fixture قدیمی برای این coupon family، tax_after_discount=false دارد. با جایگزین‌کردن repository in-memory و policy صحیح، failure ناپدید می‌شود؛ با policy قدیمی دوباره برمی‌گردد.

Reduction: database، cache warning و commit تازه از case حذف می‌شوند و failure فقط با policy object قدیمی قابل بازتولید است.

Causal statement محدود: در این fixture، policy persisted قدیمی باعث می‌شود taxable base قبل از discount انتخاب شود. این statement دربارهٔ تمام tax failures یا تمام couponها ادعا نمی‌کند.

Corrective action: migration/fixture correction محدود به همان policy family، نه یک bypass عمومی.

Recurrence evidence: تستی اضافه می‌شود که policy قدیمی را seed می‌کند و انتظار دارد migration آن را اصلاح کند. با reintroduce کردن مقدار قدیمی، تست fail می‌شود؛ بعد از correction pass می‌شود.

نکتهٔ مهم: این مثال روش را نشان می‌دهد، اما جواب Lab شما نیست. در Lab باید evidence جدید تولید کنید و نمی‌توانید location یا explanation این مثال را کپی کنید.

سه failure mode که خیلی قانع‌کننده به نظر می‌رسند

۱) «تازه‌ترین commit احتمالاً علت است»

Recency یک cue قوی است، اما causal evidence نیست. یک commit تازه می‌تواند فقط هم‌زمان باشد. repair move: یک probe بنویسید که اگر commit واقعاً علّی باشد نتیجه‌ای متفاوت از حداقل یک فرضیهٔ دیگر بدهد.

۲) «سبز شد؛ پس Root Cause را حل کردیم»

یک flag می‌تواند مسیر مشکل‌دار را دور بزند و symptom را حذف کند. اگر defect زیر flag خاموش هنوز وجود دارد، شما symptom را suppress کرده‌اید. repair move: recurrence sensor را روی defect mutation اجرا کنید و مکانیزم را توضیح دهید.

۳) «Root Cause باید یک علت یکتا باشد»

برخی failureها حاصل interaction چند condition هستند. اگر evidence فقط ترکیب «state A + boundary B» را پشتیبانی می‌کند، همان causal set را بنویسید. مجبورکردن روایت به یک عامل یکتا، overclaim است.

Formative check

فرض کنید warning مربوط به cache فقط در اجرای failing دیده می‌شود. چه چیزی کم است؟ حداقل یک probe که cache state را مستقل تغییر دهد یا repository را جایگزین کند و نشان دهد symptom با آن تغییر چه می‌کند. هم‌زمانی به‌تنهایی کافی نیست.

برای برنامه‌نویس باتجربه: ابزارهای قبلی را به evidence contract وصل کنید

احتمالاً از debugger، tracing، git bisect، profiling، log correlation یا feature flags استفاده کرده‌اید. این‌ها خودشان verdict نیستند؛ هرکدام یک probe یا وسیلهٔ reduction هستند.

• git bisect می‌تواند نقطهٔ تغییر رفتار را پیدا کند، اما هنوز باید مکانیزم را نشان دهید.
• tracing می‌تواند boundary اشتباه را آشکار کند، اما trace بدون فرضیهٔ رقیب ممکن است فقط noise بیشتری بسازد.
• feature flag برای containment عملی مفید است، اما containment را با causal correction یکی نکنید.
• یک unit test سبز بعد از fix مفید است، اما برای recurrence evidence باید نشان دهید روی defect قبلی fail می‌شود.

Fast path برای شما یعنی توضیح کمتر، نه evidence کمتر. اگر در پنج دقیقه می‌توانید reproduction و دو hypothesis معتبر بسازید، مستقیم به probe و reduction بروید؛ اما Root Cause Record، limitation و transfer همچنان لازم‌اند.

انتخاب روش: چه زمانی probe را عوض کنیم، defer کنیم یا escalate کنیم

هیچ probe واحدی برای همهٔ failureها بهترین نیست.

• Black-box reproduction زمانی مناسب است که ابتدا باید boundary رفتار را تثبیت کنید.
• Instrumentation/tracing وقتی مفید است که چند component می‌توانند مقدار را تغییر دهند و باید boundary عبور داده را ببینید.
• Reduction وقتی مفید است که noise زیاد است و می‌توانید dependencyها را حذف کنید بدون اینکه symptom از بین برود.
• History tools مثل bisect زمانی ارزشمندند که behavior change در بازهٔ versionها پایدار و قابل بازتولید باشد؛ نه صرفاً چون commit تازه‌ای وجود دارد.
• Containment/workaround ممکن است برای محدودکردن impact لازم باشد، اما باید جدا از causal closure ثبت شود.

اگر failure nondeterministic است، دادهٔ کافی برای reproduction ندارید، یا چند سیستم خارجی قابل کنترل نیستند، تصمیم درست ممکن است bounded defer یا escalation باشد. این شکست نیست؛ به شرطی که دقیقاً بنویسید چه چیزی هنوز ثابت نشده و چه evidence برای ادامه لازم است.

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

گذر هدایت‌شده

برای یک failure کوچک این شش مورد را تکمیل کنید:

1. نشانه و boundary دقیق؛
2. دو فرضیهٔ رقیب؛
3. یک probe تمایزدهنده؛
4. یک alternative ردشده همراه با شواهد؛
5. یک reduced case؛
6. یک causal statement موقت همراه با non-claim.

مسیر Foundation با نسخهٔ نیمه‌ساخت‌یافتهٔ artifact و ledger شروع می‌شود: چند مشاهدهٔ از قبل معلوم برچسب‌گذاری شده‌اند و فقط یک next probe پیشنهادی وجود دارد. پس از اولین گذر، next probe پیشنهادی را حذف کنید و نسخهٔ blank را با تصمیم خودتان ادامه دهید. در transfer مستقل هیچ prompt یا ساختار prefilled باقی نمی‌ماند.

Lab محلی checkout

fixture محلی checkout یک defect مرزی دارد. سه ناحیهٔ کد plausible هستند، cue مربوط به recent commit عمداً گمراه‌کننده است، log noise هم‌زمان وجود دارد و یک compatibility option می‌تواند symptom را پنهان کند.

باید:

• failure را از input/state مشخص بازتولید کنید؛
• پیش از modification حداقل دو فرضیه را ثبت کنید؛
• حداقل یک alternative را با probe تمایزدهنده رد کنید؛
• case را به‌اندازهٔ کافی reduce کنید؛
• corrective change محدود اعمال کنید و نتیجهٔ reproduction اصلی را بعد از اصلاح ثبت کنید؛
• recurrence sensor بسازید؛
• defect را کنترل‌شده reintroduce کنید و نشان دهید sensor روی mutation fail و بعد از correction pass می‌شود؛
• documentation/AI/tool support را افشا کنید و validation و تصمیم نهایی را خودتان انجام دهید.

مرز استفاده از پشتیبانی: AI یا documentation فقط بعد از بسته‌شدن retrieval/first-diagnosis probe لازم می‌تواند گزینه‌های جست‌وجو یا probeهای بعدی پیشنهاد دهد. این پشتیبانی جای evidence بسته‌شده، validation مستقل یا تصمیم انسانی را نمی‌گیرد.

شبکهٔ خارجی، production data، secret یا دستور destructive لازم نیست.

خودبازبینی پیش از انتقال مستقل

پیش از رفتن به S5، نسخهٔ scaffold-faded از Root Cause Record v1 را بررسی کنید. باید evidence، decision و limitation قابل بازرسی داشته باشد و هیچ inference بدون پشتوانه به fact ارتقا پیدا نکرده باشد. اگر این خودبازبینی ناموفق بود، فقط همان بُعد ناموفق را اصلاح کنید و رکورد را دوباره بررسی کنید؛ معیار نهایی پایین نمی‌آید.

انتقال مستقل با fixture اجرایی shipping

fixture مستقل transfer_shipping/ failure متفاوتی را در مرز وزن ۱۰٫۰ کیلو بازتولید می‌کند. recent UI cue و database warning وجود دارند، اما هیچ‌کدام از قبل علت اعلام نشده‌اند. با ابزارهای همان fixture reproduction و boundaryهای جدید بسازید، حداقل دو hypothesis جدید ثبت کنید، probeهای مناسب همین context را انتخاب کنید و recurrence evidence جدید تولید کنید. path، evidence یا answer مربوط به checkout را کپی نکنید.

در این مرحله scaffold Foundation و next-probe suggestion نباید استفاده شوند؛ فقط invariants روش حفظ می‌شوند: reproduction، hypothesis/refutation، reduction، bounded claim و mutation-backed recurrence.

چه چیزی برای قبول Root Cause Record کافی است

بازبین باید بتواند بدون حدس این زنجیره را دنبال کند:

1. Reproduction quality: input/state/expected/observed/repeat/boundary روشن است.
2. Hypothesis discipline: حداقل دو explanation واقعی ثبت شده و یک alternative با evidence رد شده است.
3. Reduction quality: حداقل یک dimension بی‌ربط حذف شده در حالی که symptom حفظ شده است.
4. Bounded causal statement: statement دقیقاً به evidence وصل است و limitation دارد.
5. Corrective change: تغییر روی همان مکانیزم اعمال شده، نه صرفاً روی ظاهر symptom.
6. Mutation-backed recurrence: sensor روی defect reintroduced fail و روی correction pass می‌شود.
7. Human decision: شما accept / modify / reject / bounded defer را با rationale انتخاب کرده‌اید.

مواردی که closure را invalid می‌کنند: narrative بدون evidence trail، green output بدون causal explanation، قبول خروجی ابزار/AI به‌عنوان authority نهایی، یا ادعای transfer بدون evidence جدید.

یک regression sensor محلی فقط recurrence همان defect محدود را می‌سنجد؛ از آن نتیجه نگیرید که کل Test Strategy سیستم کامل است.

ارزیابی و transfer

S1 — Retrieval

در یک failure، recent commit و warning هم‌زمان دیده می‌شوند. observation، hypothesis و چیزی را که هنوز cause نیست از هم جدا کنید و دو evidence step برای افزایش causal confidence نام ببرید.

S2 — Application

از case محدود ارائه‌شده بخش مرکزی Root Cause Record v1 را بسازید: reproduction، حداقل دو hypothesis، probe/result، rejected alternative، reduced case، causal statement، corrective change، recurrence sensor و limitation. خروجی narrative-only کافی نیست.

S3 — Diagnosis

یک تیم compatibility flag را فعال می‌کند، main test سبز می‌شود و تیم Root Cause را fixed اعلام می‌کند. اولین promotion بدون evidence را مشخص کنید و یک probe تمایزدهنده برای repair پیشنهاد دهید.

S4 — Decision

برای candidate conclusion یکی از accept، modify، reject یا bounded defer را انتخاب کنید. evidence، limitation، یک explicit non-claim، support disclosure و human rationale را ثبت کنید.

S5 — Transfer

در fixture اجرایی shipping، سرویس هزینهٔ ارسال فقط در مرز وزن ۱۰٫۰ کیلو fail می‌شود. recent UI commit و database warning هم وجود دارند. بدون کپی‌کردن path، evidence یا answer از checkout، روش را با probeهای مناسب این context اجرا و evidence جدید تولید کنید.

شرط قبولی: پنج critical dimension منجمد عبارت‌اند از Reproduction quality، Hypothesis/refutation discipline، Reduction quality، Bounded causal statement و Mutation-backed recurrence evidence. failure در هرکدام blocking است. Evidence traceability، human decision همراه با limitation/support disclosure، و changed-context transfer نیز hard conditionهای blocking هستند. هیچ میانگین عددی نمی‌تواند failure در این موارد را جبران کند.

منبع، freshness و مرز ادعا

پایهٔ روش‌شناختی این درس با منبع Google SRE — Effective Troubleshooting هم‌راستاست: troubleshooting را می‌توان با observation، ساخت hypothesis، آزمودن/ردکردن و simplification/reduction پیش برد. این منبع برای ادعای «هر failure دقیقاً یک Root Cause دارد» استفاده نمی‌شود.

• بازیابی ثبت‌شده: ۲۰۲۶-۰۹-۰۲
• موعد بازبینی: ۲۰۲۷-۰۹-۰۲
• Freshness class: foundational stable

Design rule این درس که closure را به causal statement محدود و recurrence evidence وصل می‌کند، معیار آموزشی همین درس است؛ نه ادعایی که به منبع بیرونی نسبت داده شود.

چهار non-claim را همیشه حفظ کنید: هر failure یک علت یکتا ندارد؛ recent change مساوی causation نیست؛ green rerun به‌تنهایی causal mechanism را ثابت نمی‌کند؛ regression sensor محلی یک Test Strategy کامل نیست.

منشأ و ردپای منبع (Provenance): وقتی از documentation، AI یا ابزارهای دیگر برای پیشنهاد hypothesis یا probe استفاده می‌کنید، استفاده را ثبت کنید. evidence blocking و final decision باید قابل دفاع توسط خود شما باشد.