# Episode 1: Define the task and supply verified context

Production decision, 2026-10-17: English AI-cloned owner narration with English captions and Arabic translated subtitles. The Egyptian Arabic blocks below provide localized translation source text; Arabic audio is deferred. Natural length estimate: 6–8 minutes, including useful demonstrations and exercises. Measure rehearsal; never pad to a minimum. No release day assigned.

## Slide 1: two presses, two requests

On screen: an illustrated Save button and two numbered request lines. Label `Prepared example / sample data`. Reveal the second request after the second press. Keep this label visible on simulated UI and request diagrams throughout the series.

English:

You press Save, nothing seems to happen, and you press it again. Our sample now has two requests running. We could ask an AI assistant to fix the button immediately. But before it writes anything, we need to decide what a correct result looks like. In this series, we'll use this small React Native problem to build a complete working method: describe the change, supply the project context, check the result, and turn the review into a reusable skill.

Egyptian Arabic:

دست حفظ، ومفيش حاجة ظهرت، فدست تاني. المثال اللي قدامنا دلوقتي فيه طلبين شغالين. ممكن نطلب من الـ AI يصلّح الزرار فورًا. بس قبل ما يكتب أي كود، محتاجين نحدد النتيجة الصح شكلها إيه. في السلسلة دي هنستخدم مشكلة صغيرة في React Native عشان نمشي على طريقة شغل كاملة: نحدد التغيير، نوضح سياق المشروع، نراجع النتيجة، ونحوّل المراجعة لـ skill نستخدمها تاني.


## Slide 2: a request with missing decisions

On screen: `Fix the Save button`. Below it reveal `While pending?`, `After failure?`, `Which files?`. Hold each question briefly.

English:

The request says, fix the Save button. That leaves several decisions open. Should another press be ignored while a request is running? Should the user be able to try again after an error? Can the assistant replace the form library? A plausible answer might solve a different problem from the one we meant. I'll describe the sequence first: start one save, keep it pending, then attempt another. We want the second attempt to leave the first request alone.

Egyptian Arabic:

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


## Slide 3: acceptance cases

On screen: a short table: pending plus another call = one task; success plus later call = allowed; failure plus retry = allowed. These are expected behaviors, not measured native results.

English:

Now we can write checks that another person can understand. A second call during a pending save must not start another task. After success, a later save should work. After failure, retry should work too. Notice that preventing repeated requests is only part of the requirement. A button that stays blocked forever also prevents repeated requests, but it fails the retry case. We'll also preserve the original error so the caller can decide how to explain the failure.

Egyptian Arabic:

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


## Slide 4: the boundary of this change

On screen: `One mounted owner`. Show two independent forms, each with its own gate. Footer: `Server idempotency is outside this sample`.

English:

The scope matters. Our gate belongs to one mounted owner of the save operation. Another form can have its own independent gate. We aren't building a global lock for the whole application. We also aren't proving that the server can never receive a duplicate operation. A lost response, a second device, or a new app session introduces different questions. This lesson's contract is smaller: stop overlapping calls through this owner, release the gate afterward, and keep the failure visible to the caller.

Egyptian Arabic:

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


## Slide 5: the actual prompt

On screen: Episode 1 task-clarification prompt from [prompts.md](../sample/prompts.md), with the four clauses revealed separately. This is a prompt example, not a captured conversation.

English:

The prompt can now point to a real task file and the incomplete implementation. I ask the assistant to explain the triggering sequence, expected behavior, and smallest useful change before editing. If information is missing, it should identify that gap. I can review this explanation against our acceptance cases. There's no special phrase that makes the model understand every project. The useful part is that the problem, allowed scope, and expected observations are available together and can be checked.

Egyptian Arabic:

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


## Slide 6: your turn

On screen: `Prevent repeated upload presses`. Pause for 15-20 seconds, then reveal `One active upload / Retry after failure / Preserve selected file`. Label these as exercise requirements; uploads are not implemented in this sample.

English:

Try the same method on an upload button. Before choosing code, write what happens while an upload is pending and what should happen after it fails. Pause here if you want to write your answer. One useful set of requirements is to allow one active upload through this owner, permit retry after failure, and preserve the selected file. That last requirement is easy to miss when the original request mentions only repeated presses. Writing the behavior exposes decisions before they become code.

Egyptian Arabic:

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


## Slide 7: correct code in the wrong project

On screen: a prepared proposal importing a new button library, beside the existing `AppButton` contract. Label the proposal `Illustrative candidate`.

English:

An assistant can write code that looks reasonable and still makes the wrong change for your project. Imagine it installs a new button library even though the application already has AppButton, localization, and a loading state. Our task doesn't require replacing any of them. Now we'll supply the context that affects the save fix. The aim is to make the existing project visible enough that a proposed implementation can fit it and we can explain why.

Egyptian Arabic:

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


## Slide 8: files that answer a question

On screen: four file paths and their jobs: task, gate, caller, tests. Reveal one at a time.

English:

I start with files that answer specific questions. The task defines the behavior. The gate contains admission logic. The caller shows where that gate lives and how the screen responds. The tests show what we already know how to check. If the fix uses a shared button, we need its actual contract too. A complete repository dump isn't automatically better context. Each extra file should help resolve a decision or verify a claim relevant to the requested change.

Egyptian Arabic:

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


## Slide 9: verified instructions

On screen: excerpts from the teaching project-context file: existing components, labels passed in, gate retained per owner, available test command.

English:

Our sample context says that labels come from the host's localization system and AppButton already accepts loading and disabled props. It also says that the gate must be retained for one owner. These statements guide implementation. In a real project, check them against the source before writing them into instructions. An old instruction file can be wrong. When a file says something hasn't been verified, preserve that uncertainty and inspect the relevant source instead of turning the note into a confident rule.

Egyptian Arabic:

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


## Slide 10: instructions and the current task

On screen: `Project conventions` and `This task's requirements`. Small footer: `Automatic file discovery depends on the tool`.

English:

Project instructions and the current task have different jobs. Project instructions describe conventions that apply across changes. The task says what we need now. Tools may discover project instructions through files such as AGENTS.md or CLAUDE.md, with behavior specific to each tool. Our slides use an explicit request to read project-context.md, so the lesson doesn't depend on an unverified discovery rule. When you adopt automatic loading, check the documentation for your chosen assistant and confirm which instructions it actually reads.

Egyptian Arabic:

تعليمات المشروع والمهمة الحالية ليهم وظيفتين مختلفتين. تعليمات المشروع بتشرح قواعد بنستخدمها في تعديلات كتير. والمهمة بتقول إحنا محتاجين إيه دلوقتي. بعض الأدوات بتقرأ ملفات زي AGENTS.md أو CLAUDE.md تلقائيًا، بس التفاصيل بتختلف من أداة للتانية. هنا هنطلب صراحة قراءة project-context.md، عشان الشرح ما يعتمدش على افتراض عن التحميل التلقائي. لما تستخدمه في أداتك، راجع توثيقها واتأكد هي قرأت أنهي تعليمات فعلًا.


## Slide 11: a command with a defined purpose

On screen: `node --experimental-strip-types --test save-gate.test.mjs`. Under it: `Pure gate logic`. Separate line: `Native UI: not covered`.

English:

The context also needs honest verification instructions. This command runs the isolated gate tests in Node. It doesn't mount a React Native screen, check the TSX integration, or prove that a screen reader announces the error. Those are separate checks. Giving an assistant an exact command helps, but the meaning of that command matters just as much. If we later see a message saying all checks passed, we should be able to identify which checks ran and which behavior they covered.

Egyptian Arabic:

السياق كمان محتاج تعليمات مراجعة دقيقة. الأمر ده بيشغّل اختبارات البوابة لوحدها في Node. مش بيشغّل شاشة React Native، ومش بيراجع دمج TSX، ومش بيثبت إن قارئ الشاشة نطق الخطأ. دي فحوصات تانية. كتابة أمر واضح للمساعد مفيدة، بس لازم نعرف الأمر بيثبت إيه. لو شفنا بعد كده رسالة بتقول كل الفحوصات نجحت، نقدر نحدد أنهي فحوصات اتشغّلت، وراجعت أنهي سلوك.


## Slide 12: context ready for a small change

On screen: the Episode 1 verified-context prompt, then highlight `Do not infer a runnable native app`.

English:

We now have enough context to ask for a bounded implementation. We know the task, the available components, the ownership rule, and the limits of our tests. We'll keep the instructions short and update them when the source changes. In the next episode we'll look at the code change itself. We'll follow the path of a first save, a second overlapping call, and a failure, so we can understand the proposed solution before accepting it.

Egyptian Arabic:

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


## Recording and evidence

Slide cues are not narration. Use the matching task, context, implementation, verification, skill-authoring and evaluation prompts in [prompts.md](../sample/prompts.md). The exercise answers are in the spoken blocks and [evaluation answer key](../sample/review-skill/cases.md). Keep that answer key out of a real blind evaluation. Samples are teaching adaptations; no native app or actual AI evaluation result is claimed. Record slide by slide and time the selected takes.