Urazuke — the course. Manual with hands-on tasks, step by step, up to the application in production

Author: Pablo Kuschniroff, assisted by Claude Code. Version 2, 18 October 2026. It is a working document of the Urazuke project: I am going to correct it with the first cohort that uses it. It is written in everyday language, and every acronym or odd expression is in the glossary of the main document (ESCALERA_METODOLOGICA.md). When I cite a real case I do it with a [Ref. N] mark that leads to the references document; the manual stays clean and the detail is one click away. The public repository of the method is github.com/pkuschnirof/urazuke.

Before you start

Who this course is for

For someone who wants to build software with artificial intelligence and wants that software to be used for real, by real people, for months. It is not a programming course: you are not going to learn a language or a framework. Nor is it a "prompts" course: you are not going to learn tricks to make the model write better. It is a course of method: of what to do in what order, what to ask the model for at each moment, what it has to deliver to you, and how to know —without reading code— that what it delivered is complete.

It is useful to you if you are one of these people:

• You have a business, a practice, a small consultancy, and you want your own system without hiring a development team.
• You are an automation consultant or freelancer and your clients ask you for "something more" than a robot.
• You know how to program, but you want the model to do the heavy lifting and keep the decisions for yourself.
• You already "vibecoded" something, it worked for two weeks, and in month three it fell over.

It is not useful to you if what you want is a prototype for Friday's demo. There are faster tools for that, and this method is going to feel slow to you. The method is for what has to keep working after the demo.

What you will have at the end

An application of your own, running in production, with: tests that were seen failing before they passed; end-to-end tests of every flow; reproducible deployment with rollback; configuration and secrets outside the repository; the business decisions written down with their date; a semantic tree of the system and the detailed specification of every thing that was built, in its pending items; locks on everything that charges, sends or deletes; three manuals that a person can follow without AI; an audit done by an agent different from the one that built; and a retrospective with numbers. That is what I call "production grade" here: it is not that it works, it is that it can be sustained.

And you will have something more, which is what you really take with you: the reflex of not believing the model without evidence, and of knowing exactly what evidence to ask it for at every step.

What you need

1. An AI tool for programming. Any one that can read and write files in your repository and run commands: Claude Code, Cursor, Codex CLI, Gemini CLI, Forge. The method does not depend on which one; the main document has a table of where each artefact goes in each tool. In this manual I say "the agent" to refer to whichever one you use.
2. A GitHub account (or equivalent) and minimal notions of what a repository, a commit and a push are. If you do not have them, spend an afternoon on it before starting; any introductory tutorial is enough. Nothing more is needed.
3. A project. Ideally it is your own: a system you need or that a client asked you for, with users who are going to use it. If you do not have one, use the guide project I describe below; it is designed to go through the twenty-four steps without skipping any. If what you have is a system that already exists and has to be corrected or made to grow, this first part teaches you the method on a new project, and part 2 of the course teaches you to normalize it first, with a second, inherited guide project.
4. Time. The course has twenty-four lessons, one per step, and an order that tells you in which stage each thing falls (see "The order of the course"). I give you no deadlines, on purpose: the method is a process, not a promise of speed, and how long each stage takes is set by the size of your project. What I do give you is the order, and that one is not negotiable.
5. A domain owner with time to decide. If the project is yours, that is you. If it is a client's, it is the client, and they have to know that they are going to have to answer questions throughout the whole project. This point is not negotiable: without an owner who decides, the model decides, and there the method breaks.

How the course works

Every lesson has the same structure:

• What you need to understand: the concept, explained the way you explain it to a person.
• The task: step by step, with the exact prompt you are going to give the agent (in English, because models follow instructions more precisely in English; below each one it is explained what you are asking for) and what to do with what it gives you back. Before each prompt there is a block that says "Before sending the prompt": the files and the inputs you have to have made yourself, with your own hands, before pasting it. Do not skip it: the prompt names those files, and if they do not exist or are empty, the agent is going to invent them or is going to ask you for them.
• The completeness check: the list of questions you ask yourself about what the agent delivered, without opening the code. If any of them comes out "no", the lesson is not finished.
• The deliverable: the file or the evidence that has to exist at the end.
• Typical mistakes: what happens to almost everybody the first time.
• In the guide project: what this lesson looks like applied to the example project.

One rule for the whole course: do not move on to the next step with a check at "no". The temptation of "I'll fix it later" is exactly what the method exists to avoid. If a step is not climbed completely, the next one is built on sand.

The order of the course: when each thing happens

The main document has, in its Part B, the complete timeline of the method. Here I translate it into the order of the course for the guide project. They are stages, not weeks: each one lasts as long as your project demands, and what is not negotiable is the order and, above all, what happens between one lesson and the next.

If your project is bigger, what grows is stages 2 and 3 (more blocks), not stage 1 or stages 4 and 5. And if at some point you find yourself doing infrastructure in stage 3, or running the end-to-end suite for the first time in stage 5, go back to the order: something was skipped.

The guide project: "Turnera"

If you do not have a project of your own, use this one. It is small, but it has everything needed so that none of the twenty-four steps is a fake: real users, personal data, messages that go out into the world, and money.

The business. A practice (it can be a studio, a hairdresser, a workshop: any place that gives appointments). Today the appointments are written in a notebook and confirmed by WhatsApp by hand. Appointments are lost because people forget, there are double bookings because two people wrote in different notebooks, and nobody knows how many appointments were cancelled last month.

What they want. A web schedule where the two receptionists and the three practitioners see the appointments; automatic reminders 24 hours before, by WhatsApp or email; the possibility of asking for a deposit through a payment link for certain appointments; and a couple of numbers at the end of the month (how many appointments, how many no-shows, how many deposits).

The owner. The practice manager. She has judgement about the business (she knows which appointments carry a deposit, how far in advance one can cancel, what to say to a patient who has missed three times) and she has fifteen minutes a day to answer questions. She does not program, and she is not going to read code.

The numbers only she knows. About forty appointments a day, two hundred and fifty days a year. About three messages per appointment (confirmation, reminder, sometimes rescheduling). Patient data is kept for five years. The peak is Monday morning, with the two receptionists entering at the same time. And a question she cannot answer and that matters: if this works, are they going to sell it to other practices? (The answer changes the sizing by ten.)

What has consequences. Sending a reminder (if it is sent twice, it annoys; if it is sent to the wrong number, it is a privacy problem). Charging a deposit (money). Cancelling an appointment (irreversible for the patient who loses it). Deleting a patient (personal data).

The use cases the practice manager names, just as she says them: "I book an appointment", "I look up a patient", "I cancel an appointment", "the patient gets the reminder", "I ask for the deposit", "I see how many appointments there were this month". There are six; they will be the end-to-end flows.

This is enough to start. Everything else the agent is going to ask, and it is part of the exercise that it asks.

The start-up stretch: lessons 0 to 4

These five lessons are done once per project, in stage 1, before writing functionality. They are the ones that tempt you most to skip ("I want to see something working"), and they are the ones that cost the most to skip. Do them in one go, and only then open the loop.

Lesson 0 — Can this project be run this way?

What you need to understand. The method does not work for every project, and knowing that before starting is the first quality decision. There are two conditions without which it does not work: that there is a standard repository where the evidence can be left (X1), and that the screens can be driven by a program in order to test end to end, from the screen to the backend (X2). If either of the two fails, the agent is not going to be able to verify itself, and then you are going to end up reading code yourself, which is exactly what the method promises to avoid. I took both from projects I turned down Ref. 46. Then there are weighted criteria (whether there is an owner with time, whether an error has consequences, whether it can be tested in a separate environment, etc.), which I am still calibrating.

For the guide project the two conditions are met: it is a new project (there is no legacy) and we are going to build it with a web interface that can be driven by a program. For a project of your own, this lesson may end in "no-go", and that is a valid outcome of the course.

The task.

1. Paste it this prompt:

You are asking it to read the two files, to evaluate whether the survey is sufficient and ask for what is missing before answering (this clause is repeated in every prompt of the course; it is the heart of the method), to fill in the sheet saying where each answer comes from, and not to decide: the decision is yours.

2. Answer its questions. If it did not ask you any, be suspicious and ask it what it assumed.
3. When it presents you the sheet, read it and decide.

4. Paste it the closing prompt:

Completeness check. Open docs/ELIGIBILITY.md and ask yourself: do the two exclusionary criteria have an explicit answer and a source? Is there any criterion answered with "probably"? (If there is, the agent had to ask.) Does the decision have a date and a name? Can the conditions, if there are any, be verified? Are the questions it asked and your answers there?

Deliverable. docs/ELIGIBILITY.md, one page.

Typical mistakes. Writing the survey "complete" so that the agent does not ask: you miss the exercise and, worse, you get used to doing the model's job. Answering "go" with five conditions: it is a "no-go" in disguise. And the most common one: skipping the lesson because "it is obvious that it is a go". What is obvious is what does not get written, and what does not get written is what gets argued about later.

In the guide project. The agent should ask, at a minimum, whether the interface is going to be web or mobile (because X2 depends on that), whether there is a previous system even if it is an Excel, and which message channel is going to be used (WhatsApp has requirements that email does not). The sheet ends in "go", with one reasonable condition: having the message channel defined before step 14.

Lesson 1 — The working agreement

What you need to understand. The agent arrives at every session with no memory of the previous one. It is like a new collaborator every morning. The working agreement is what you tell it on the first day and what it is going to re-read every day: how you work, what you do not tolerate, what level of autonomy you give it. Without an agreement, you are going to repeat the same things to it every session, and each time a little differently. I wrote it for the first time after two weeks of repeating myself Ref. 1.

Each of the six minimum rules has a failure behind it: "my time is sacred" prevents it from consulting you on every detail; "zero debt" prevents the "I'll fix it later"; "exact scope" prevents it from adding things "while it is at it"; "documentation in the same commit" prevents old manuals; "never report as done what was not verified" prevents the "done" that was not; "speak my language" prevents it from answering you in English because the prompt was in English.

The task.

1. Paste it this prompt:

You are asking it for the six rules with the failure each one prevents, rules of its own marked as proposals so that you accept or reject them, and to ask you about yourself.

2. Answer its questions. Read the proposals: accept the ones that are useful to you, reject the ones that are not, always with a one-line reason.

3. Close with:

If there is no project file yet (you make it in lesson 2), it is going to create a minimal one with that instruction; that is fine.

Completeness check. Are the six rules there, each with the failure it prevents? Is any of them written as an aspiration ("try to…")? Does the project file order it to be read at the start of every session? Did it ask you at least one question about how you work?

Deliverable. docs/WORKING_AGREEMENT.md with date and version, hooked into the project file.

Typical mistakes. Accepting twenty rules because they all sound good: nobody respects twenty; six or eight get respected. Leaving a rule that says the agent may change the agreement: no. And the quietest one: never testing whether it reads it. In lesson 2 you are going to see how.

In the guide project. A rule of its own that the agent tends to propose for Turnera, and that is worth accepting: "I never send a real message to a patient from an environment that is not production; in test, messages go to a fake inbox". It is step 14 peeking in early.

Lesson 2 — The project definition, the semantic tree and mandatory reading

What you need to understand. The project file (PROJECT.md, or CLAUDE.md, or whatever name your tool uses) is the map the agent reads at the start of every session. It has to be short: what the system is, for whom, what it is NOT, the modules, the decisions taken with their date, and the order to read the agreement. What happened each day does not go there: it goes to the living state (docs/STATUS.md) and to the pending-items register. One of my systems let this file grow to more than nine thousand lines; in that state, nobody reads it, and neither does the model Ref. 41.

But the map has a second piece, and it is the one that does the most work: the semantic tree. It is the system broken down as a tree: the domains at the first level, and under each one its actors, its processes (the use cases you named in the intake, with actor, trigger, steps, outcome and exceptions), its entities with their attributes and their states, its screens and its external integrations. It is the domain model of requirements engineering as it has always been, put in the form of a tree so that the model reads it. From each node will hang the pending items and the decisions that touch it. Its value is twofold: it gives the agent the exact context of the node it is going to touch, and it gives you a way to verify, without reading code, that the system the agent understands is the one the business asked for. If the tree has a state the business never named, the model invented it, and you are going to see it before it builds on it.

The "what it is NOT" section is still the most important one and the one everybody leaves empty. What is not written is what the model is going to invent when it runs into a gap.

The task.

1. Paste it:

You are asking it to ask before drafting, for a short project file with the "what it is not" section, the semantic tree with its complete structure and with the inferred nodes marked, and the living state in another file.

2. Read PROJECT.md in full. It has to fit in five minutes. Correct whatever is not true or not yours.
3. Walk the semantic tree as if you were the client. Look at every node marked as inferred and confirm or correct it. Look for missing actors, entity states the business does not use, screens you did not ask for.

4. Close with:

5. The reading test. Close the agent's session and open a new one. Without telling it anything else, ask it: "What must this system not do? And which node of the tree does the schedule screen hang from?". If it answers you with what PROJECT.md and the tree say, the hook works. If it answers you anything else, it is not reading the map: check how your tool loads the project file.

Completeness check. Can PROJECT.md be read in five minutes? Does it say what the system does NOT do? Does the tree have every actor you know, and does every entity have the states the business uses, no more and no less? Did you confirm or correct every inferred node? Does every decision have a date and who took it? Did the agent ask something before drafting? Is the living state in another file? Did it pass the reading test?

Deliverable. PROJECT.md (three hundred lines at most), docs/SEMANTIC_TREE.md with the nodes confirmed, docs/STATUS.md, and the reading test passed.

Typical mistakes. Pasting into PROJECT.md the whole specification you already had: it is the programme, not the specification. Leaving "what it is not" empty. Accepting the tree without walking it: the model infers states and screens with a naturalness that is frightening, and every invented node is functionality it is going to build without anyone having asked for it. And not doing the reading test: it is the only way to know that steps 1 and 2 are acting and not just existing.

In the guide project. In Turnera's "what it is NOT" there should be, at a minimum: it is not a medical records system (it does not store medical data), it is not a payment gateway (it uses a payment link from a provider, it does not process cards), and it does not send marketing messages (only confirmations and reminders). The tree has a "Schedule" domain with the actors receptionist and practitioner, the processes "book appointment", "cancel appointment" and "look up patient", the entities Appointment (with states pending, confirmed, cancelled, no-show) and Patient, and the screens "day view" and "patient record"; a "Messages" domain with the process "send reminder", the entity Message and the integration with the WhatsApp provider; and a "Payments" domain with "ask for deposit" and the integration with the payment provider. If the agent adds a "rescheduled" state to the appointment, ask it where it got it from: the practice manager did not name it. Maybe it is needed, maybe not; you decide, not the agent.

Lesson 3 — Size before designing the architecture

What you need to understand. There are decisions that, taken badly, cost weeks: which database, whether the calls to the database are synchronous or asynchronous, how many people can use the system at the same time. And they all depend on numbers that only the business has: how many appointments a day, how many messages per appointment, how many years the data is kept. The model cannot infer those numbers; it can infer what is derived from them (rows per year, size in five years). That is why the prompt requires it to distinguish primary data from derived data, and to ask for the missing primary figures instead of estimating them. When the model estimates a primary figure, it does it with the same straight face as when it computes; and you have no way to tell the difference by the tone. Not having done this in time cost me an entire stage of re-engineering Ref. 15.

There is also a kind of decision that is always worth taking: the asymmetric ones, cheap if they turn out unnecessary and very expensive if they are missing. The canonical example is making the interface with the database asynchronous from day one even if the first database is a file: if you never change database, one await was superfluous; if you do change, you saved yourself rewriting everything.

The task.

1. Paste it:

You are asking it to: distinguish primary from derived; ask you for the primary figures that are missing or at "assumption", and never estimate them; compute what is derived with the arithmetic in view; the "times ten" scenario; three options with the cost of changing from one to another; and not to choose.

2. If it asks you for the "assumptions", good: that was the exercise. Get the numbers (ask the owner, count in the notebook) and give them to it. If it did not ask for them and computed anyway, stop and ask it what it did with the assumptions: it is a failure of the step and it is better to see it now.
3. Read the three options. Redo one calculation by hand (for example, rows per year of the largest table): it has to give you the same. Choose.

4. Close with:

Completeness check. Is there any primary figure with source "assumption" or with no source? Does every derived figure show the arithmetic, and does it give you the same if you redo it? Are there three options and one chosen with a reason? Does it say what happens "times ten"? Are the asymmetric decisions written down? Did it ask you?

Deliverable. docs/SIZING.md.

Typical mistakes. Filling in the survey with numbers you invented so that the agent does not ask (it is the same mistake as in lesson 0, and it is worse here because those numbers decide the architecture). Choosing the "most powerful" option just in case: the cost of migrating is in the table precisely so that you choose the smallest one that withstands the "times ten". And not writing down the asymmetric decisions: if they are not written, in lesson 4 the agent is not going to respect them.

In the guide project. Primary figures: 40 appointments/day × 250 days = 10,000 appointments/year; 3 messages per appointment = 30,000 messages/year; 5 years of retention; a peak of two simultaneous receptionists. The "times ten" is the question of whether it is sold to other practices: 100,000 appointments and 300,000 messages a year. The three typical options: a SQLite file (enough for one practice for years, does not withstand the times ten with several writers), PostgreSQL from the start (withstands everything, costs a bit more infrastructure), or SQLite now with the asynchronous interface and a planned migration to PostgreSQL (the asymmetric one). For the course we choose the third: it is the one that teaches the most.

Lesson 4 — The skeleton with its gates

What you need to understand. Before the system does anything useful, it has to start up, be tested and be deployed empty. It looks like a waste of time ("deploy what, if there is nothing?") and it is the opposite: the path to production is part of the product, and the only way to know it works is to walk it when there is still nothing to lose. In one of my systems the deployment arrived a month after the start and cost five pending items in a row Ref. 32; with the skeleton deployed during start-up, those five blows would have landed on an empty system.

This lesson is, moreover, where all the infrastructure and the integration and deployment chain of the project get done. You are not going to touch it again until lesson 15, and in between you are going to build all the functionality on top of it. That is why it takes up most of stage 1.

The gates are the conditions for moving from one stage to the next ("the test suite is green", "the deployment to test worked"). Writing them now, even if they seem obvious, is what later lets you say "this does not go through" without arguing.

The task.

1. Paste it:

You are asking it to verify access before starting, for the exact list of what a skeleton is, the gates written down, a real screenshot of the test environment, and the prohibition on adding functionality.

2. This task is long and it is going to have back and forth: missing credentials, a service that asks you to confirm your email, etc. That is normal. What is not normal is for it to tell you "done" without the screenshot of the test environment.
3. When it shows you the screenshot, open the URL yourself in your browser. It has to look the same. It is the first human look at the system, and it is a milestone.

4. Close with:

Completeness check. Did you open the test environment URL yourself and see the empty screen? Is there a link to a green continuous integration run? Was the deployment run twice and did the second run break nothing? Does every gate have a verifiable condition? Is there any functionality you did not ask for?

Deliverable. The repository with the skeleton, continuous integration green, the test environment URL working, docs/GATES.md, and docs/STATUS.md with the three commands.

Typical mistakes. Accepting "it works locally, we'll look at the deployment later": no, the deployment is the skeleton. Accepting a screenshot of the agent's machine instead of the test environment. And letting it add "while it is at it" a login screen, a menu, a logo: every thing that comes in without a pending item is scope that got away.

In the guide project. Turnera's skeleton is a web page that says "Turnera — version 0.0.1" running on a public URL of a test environment, a server that answers "ok" on a health route, a smoke test that calls that route, continuous integration running that test on every push, and automatic deployment to the test environment. The gates: "suite green to merge", "test environment green to promote to production", "rollback tested for the first deployment to production". Nothing more. And it is strange how satisfying it is to see that empty page on a real URL.

The loop stretch: lessons 5 to 12

These eight lessons are the ones you are going to use with every change, throughout the whole project. They are learned in stages 2 and 3 on the first two functional blocks, and practised until the end. They go in the order in which they are done with every pending item: open a block by turning the request into specified pending items, take one, decide whatever is missing, measure whatever has to be measured, build, prove red and end to end, pass the quality gate, write the manual test cases, update the other side, and report separating what was verified from what is believed. At the close of the block, execute the manual test cases yourself. That reflex is the method.

To practise them you are going to need real functionality. In the guide project, the first block is the basic schedule: see the day's appointments, book an appointment, cancel it. The second, patients and search. No messages or payments yet; that comes after the locks (lesson 14).

Lesson 5 — The plan is the pending items, and the detailed specification lives in each one

What you need to understand. There is no "plan" on one side and a "task list" on the other: the list of pending items is the plan. But there are two more ideas, and they are the ones that distinguish this method from any old task list.

The first: the detailed specification lives in each pending item. In the classical method there was a requirements specification document, long, that aged before it was finished. Here it is broken down: every pending item carries the node of the semantic tree it hangs from, the user story or the use case that originates it in the client's words, the detailed description, the applicable business rules with their decision and their date, the data that goes in and out, the screens affected, the edge cases, the acceptance criteria in the form "given, when, then", and how it is verified. Reading the specification of a pending item is the closest you are going to get to reading code, and it is exactly the right distance: that is where you detect that the agent understood something else, before it builds.

The second: closed pending items are documentation. When a pending item is closed, it stays with its specification, the decision that originated it, the evidence with which it was closed, the commit and the date. The queue of closed pending items is the functional history of the system, and from there come the changelog and the new sections of the manual. And the golden rule for the agent: whatever appears outside the list is written down as a new pending item, with its specification, not done.

The task.

1. Paste it:

You are asking it to turn the request into verifiable items, to ask when the request is not enough to write a verifiable one, for the complete specification of each one field by field, the node of the tree it hangs from, the business rules with their decision or marked as missing, the acceptance criteria that will later be the script of the test, and an order with its reason.

2. Answer the questions (for Turnera it is going to ask, for example, what "the day" is: today's, or any day that gets chosen?; does cancelling delete or mark?). Those questions are business decisions; in lesson 6 you are going to see where they get written.
3. Read the specification of every pending item as if you were the client. This is the most important task of the lesson, and the one that tempts you most to skip. Does it describe what you asked for, in your words? Are the acceptance criteria the ones you would use to say "that is right"? Is there an edge case you know of that is not there? Does it hang from the right node? Correct before anything gets built.

4. Add the routine of every session to the working agreement. Paste it:

5. Now, yes, start building. Ask it to take the first pending item. From here on, every session starts with "which pending item are you taking and why", and every close leaves the pending item documented.

Completeness check. Read the specification of a pending item at random: does it have every field, and does it describe what you asked for? Does every pending item hang from a node of the tree that you recognise? Does each one say how it is verified? Are there rules marked "missing, asked" that it did not ask you about? Are there closed pending items without evidence or commit? Do the closed ones keep their specification and their closing documentation? Take three commits at random: do they cite their pending item? Did anything show up in the code without a pending item?

Deliverable. docs/PENDING.md with the first block specified, the routine in the agreement, and the first pending item in progress.

Typical mistakes. Accepting one-line specifications: the agent wrote them to comply, and it is going to invent what is missing at the moment of building. Not reading the specifications: it is the only moment when you can catch a misunderstanding before it costs. Letting the agent close pending items without evidence because "I already saw it working". Letting it close without documenting: six months later nobody knows why the system does what it does. And the one that is hardest to correct: letting it do "one little thing more" outside the list. The first time you allow it, you lost the exact scope.

In the guide project. Turnera's first block is about six pending items, hanging from the "Schedule" domain of the tree: PND-001 see the appointments of a day; PND-002 book an appointment with patient, practitioner, date and time; PND-003 prevent two appointments of the same practitioner at the same time; PND-004 cancel an appointment (mark, do not delete: a lesson 6 decision); PND-005 look up a patient by name or phone; PND-006 registering a patient with the minimum data. The specification of PND-003, for example, says: node Schedule → process "book appointment" → entity Appointment; story: "there cannot be two appointments of the same practitioner at the same time, it happened to me twice with the notebook" (the practice manager's words); rule: "double appointment only if the practitioner enabled it" (pending decision, asked); data: practitioner, date, start time, duration; screen: booking form; edge cases: partially overlapping appointments, appointments of different duration; acceptance criteria: "given an appointment of Dr. A at 10:00, when I try to book another of Dr. A at 10:00, then the screen warns and the database does not save it"; verification: end-to-end test of the form plus a database query. That is a specification.

Lesson 6 — Decisions are written next to the code

What you need to understand. The model, when it finds a gap in the business rules, fills it. It does not stop to ask; it completes with what seems most likely to it, with the same naturalness with which it writes everything else. That is why this lesson is not "write down the decisions" but "require it to stop and ask when one is missing". And when you decide, the decision is written with your exact words, your name and the date, in the commit, in the specification of the pending item and in a register. I have done it since the first system Ref. 29; six weeks later, when someone asks "why does cancelling not delete?", the answer is written and it is yours.

The task.

1. Add the decisions routine to the agreement. Paste it:

You are asking it to stop before an unwritten rule, to ask with a recommendation and an alternative (so that you can decide in ten seconds), to record your exact words in the three places, and, when you do not answer, to choose the most reversible option and mark it.

2. Keep building the pending items of the block. Every time it asks you a business rule, decide and answer with the closing format.

3. Paste it:

4. Do the opposite test, once, on purpose: leave a question unanswered for a session and watch what it does. It has to choose the most reversible option and mark it "by omission". If it chose what it felt like and did not mark it, it is a failure of the step: correct it in the agreement.

Completeness check. Open three commits that touch business rules: do they cite who decided and when? Is the rule also in the specification of the pending item? Are there "by omission" decisions left unconfirmed? Is there any rule in the system you do not recognise as yours? Are the sentences exact or "improved"?

Deliverable. docs/DECISIONS.md growing, with at least five decisions from the first block, and the commits and the pending items citing them.

Typical mistakes. Answering the questions in the chat and not requiring them to be written down: by the third session nobody remembers. Letting the agent "improve" your words: a paraphrased rule is a different rule. And the most serious one: discovering in production a rule nobody decided. When it happens (it is going to happen), it is not a bug: it is a failure of step 6, and it is fixed in the agreement, not only in the code.

In the guide project. Typical decisions of Turnera's first block: "cancelling marks the appointment as cancelled and records who and when; nothing is deleted"; "a practitioner cannot have two appointments at the same time, but can have two patients in a double appointment if the practitioner enabled it"; "the patient's phone number is mandatory; the email is not". Each one with a date and with the practice manager's name, and each one pasted into the specification of the pending item that needed it.

Lesson 7 — Measure before building, with an instrument that is itself verified

What you need to understand. The model produces claims with a number in them ("there are about 120 queries of that kind") and they sound exactly the same whether they were measured or estimated. You cannot tell them apart by tone. The only way is to demand the instrument: "what did you measure it with? show me the command". The rule of the step is that no number that decides anything comes from an impression: it comes from a meter that lives in the repository, that has a test checking it against a known case, and that you can run yourself.

And there is something more, which I learned the hard way and which is the reason I took so long to formalise a rule I took for granted: meters lie too. In one of my systems, a meter read zero because it did not see part of the code, and another said 27 when there were 44 Ref. 35, Ref. 36. Hence the audit in both directions: from the code to the measurement (is everything that should be counted, counted?) and from the measurement to the code (does everything counted actually exist?).

In a small project, "measuring" is modest: counting how many queries a screen runs when it loads, how long the monthly report takes, how many messages were sent yesterday. You do not need a ratchet or a budget per path. What you do need is a command behind the number.

The task.

1. Paste it this:

You are asking it for the meter in the repository, the meter's test, to ask for what it lacks instead of approximating, to mark what is approximate, the number with its command, the audit in both directions, and the order: first measure, then propose.

2. Run the command it gave you, yourself. It has to give you the same number. You do not need to understand the script; you do need to execute it.
3. If the hypothesis was true and the agent proposes fixing it, ask it for a budget.

4. Paste it:

That way, if someone puts the loop back in three months from now, the test suite catches it.

5. Add rule five to the agreement, for when a plan comes with numbers:

Completeness check. Did you run the meter and get the same number? Does it have a test, and against which known case? Is there any number in the report without a meter behind it? Is what is approximate marked? Is there a budget with a test?

Deliverable. A meter in the repository with its test, a number with its command and date in docs/STATUS.md or in the pending item, and (if it applied) a budget protected by a test.

Typical mistakes. Accepting the number without running the command: half the value of this lesson is in you running it. A meter that reads zero: it is almost never zero; it is almost always failing to see something. And letting the agent "fix while it measures": the order is the method.

In the guide project. Turnera's meter is a script that loads a day with 10, 50 and 200 appointments into a test database, opens the day view for that day counting the queries, and writes down the three numbers. The meter's test verifies that with 0 appointments it counts exactly the baseline queries (say, 2). If there was a loop, the numbers are 12, 52 and 202; it gets fixed, they become 3, 3 and 3, and the budget is set at 4 with a test that fails if the day view runs more than 4 queries for any number of appointments.

Lesson 8 — Tests as locks, proved red, and the end-to-end tests

What you need to understand. This is the central lesson of the course. A test you never saw fail, you do not know whether it proves anything. The model writes the code and the test in the same session, with the same understanding: if it misunderstood the request, the test proves what it understood, and it passes. The only cheap way to know that the test is looking at what matters is to see it red against the old code: if the code from before the change also passes it, the test does not distinguish before from after, and then it is useless. That is why the request is not "write tests" but "show me the red, then the green, then the regression". The case that shows it best is the one of the counters that did not match Ref. 26.

And the second idea, which is as important as the first: the end-to-end tests. A test that verifies from the screen (clicks, types, reads) and checks the effect in the backend (the row is there, the state changed) is the one that replaces your reading of the code. The acceptance criteria of the pending item ("given, when, then") are its script. And they are run three times, at three scales: the flow touched, with every pending item; every flow that exists, at the close of every block; and every flow with the exact version, before every deployment to production. If you only do the third, you reach the end with a system nobody tested end to end for weeks.

The task.

1. Add the evidence routine to the agreement. Paste it:

You are asking it for the test guided by the acceptance criteria, the red demonstrated as a receipt (the command, the version, the counts and the exit code, so that you can run it again yourself), the green, the regression of the neighbours, the end-to-end test of the flow with the effect in the backend, no mocking of exactly what is being tested, and asking for what is missing instead of simulating it.

2. Take the double-booking pending item (PND-003 in Turnera, or the equivalent in your project: a rule that prevents something). Ask it to close it with the routine. Read the report: there has to be a red output with numbers ("1 of 1 fails against the version without the rule"), then the green, and the end-to-end test: a browser driven by a program that opens the screen, tries to book the double booking, reads the warning, and checks in the database that it was not saved.
3. If it tells you it cannot test end to end because the screen cannot be driven by a program, stop: that is X2 failing, and it has to be fixed now (adding identifiers to the screen elements) before going on.

4. Paste it:

5. At the close of the block, when the six pending items are closed, run the complete suite.

6. Paste it:

7. And after that, use the system yourself. Open the test environment and do what the receptionist would do: book an appointment, try the double booking, cancel, search. Whatever bothers you, whatever you do not understand, whatever is where it should not be: write it down as a pending item. This while finds what no test finds.

Completeness check. Does the report show the red, with numbers? Did the regression run in the same session, with numbers? Does the end-to-end test also verify the backend? Is there any part mocked exactly where the change is? Does the commit say "proved red"? At the close of the block: are all the flows in the end-to-end suite? Did you use the system yourself and write down what you found?

Deliverable. At least three pending items closed with the full routine (red, green, regression, end to end), the full end-to-end suite of the block green, and the pending items that came out of your human testing.

Typical mistakes. Accepting "the tests pass" without numbers and without red. Accepting that the suite gets "sped up" by replacing the end-to-end tests with mocks. Letting a "cannot be tested" go by without opening the pending item. And closing the block without using it yourself: the human look is not delegated.

In the guide project. The red of the double booking looks like this: the agent temporarily removes the rule, runs the test, and the output says the test failed because the second appointment was saved. It puts the rule back, runs, green. Then the regression: the tests of PND-001 and PND-002 are still green. And the end-to-end one: a browser driven by a program fills in the form, presses "save", reads the message "that time slot is already taken", and a database query confirms there is a single appointment at that time. At the close of the block, the end-to-end suite walks the three flows that exist (see the day, book, cancel), and the practice manager enters ten test appointments and discovers that the time is chosen with an awkward drop-down menu. New pending item. When you see that report for the first time, you are going to understand what the whole method is for.

What changed on 19 October 2026 (D-037). In the first block of a new project there is no previous code: the new test fails because the module does not exist, and that red proves nothing. Since that day, when the previous version does not have the module, the red is proven by mutation: the agent plants a deliberate defect in the function it just wrote, shows the test red against that defect (the receipt carries the diff), reverts it and shows the green. In Forge, a red that only says "the file does not load" no longer closes the pending item. One mutant per item; mutation testing over the whole codebase stays the optional reinforcement of lesson 9.

Lesson 9 — Code quality verified by machine

What you need to understand. You do not read the code, and that is fine; but the code exists and somebody is going to maintain it. If nobody reads it, a machine has to look at it: a linter (like the spell checker of a word processor, but for code), a formatter (a single style for everything), limits on the size of files and functions, limits on complexity (how many paths a function has), detection of duplicated and dead code, and test coverage with a ratchet (today's is tomorrow's floor). All of it in continuous integration, red when it is violated. I did it in all my projects; an audit handed me back a component of more than two thousand lines because no limit had stopped it Ref. 41.

1. Paste it the opening prompt of the step 9 contract (in docs/peldanos/), with your limits in the gaps.
2. Read docs/CODE_QUALITY.md. There is going to be a list of what fails today; decide what gets fixed now (one pending item each) and what gets tolerated with a date, and write it in the same file.

3. Add the routine of step 9 to the agreement, wrapped in "Add this routine to docs/WORKING_AGREEMENT.md:" like the others.
4. Ask it to put, on purpose, on a branch, a function of a hundred lines and an unused variable: the chain has to go red for both things.

Completeness check. Does the last run of the chain have quality green? Did the branch test go red? Are there linter exceptions, and does each one have a written reason? Is today's coverage greater than or equal to yesterday's?

Deliverable. The quality gate in the chain, docs/CODE_QUALITY.md with limits and values, and the routine in the agreement.

Typical mistakes. Letting the agent "disable this rule because it is too strict" without it going through you. Raising a limit so that it passes. And confusing coverage with quality: coverage counts tests, the red of lesson 8 says whether they prove anything.

Optional reinforcement. Once the block is closed, the step 9 contract has a third prompt, the one for mutation testing: a tool breaks the code on purpose, one small change at a time, and counts how many of those bugs the tests catch. It is the measure that coverage does not give, and the one that answers the objection that the agent can fake the red. In Turnera we do it at the close of the second block, only on the lines changed.

In the guide project. Turnera's first run goes red on three things: the appointment form has a function of 70 lines (it gets split in two: pending item), there are two copies of the date format (a single one, on the server: pending item), and coverage is at 61 %. The ratchet is set at 61 and goes up with every pending item. At the close of the block, 74 %.

Lesson 10 — Manual test cases are written together with the functionality

What you need to understand. All the tests we have seen so far are written and run by the model, and they test what the model understood. What is missing is the test a person does with their eyes and their hands, following a script: a manual test case, with a precondition, steps, an expected result and a table to write down each execution. The script is written by the agent together with every pending item, out of the acceptance criteria; you (or the practice manager) execute it at the close of each block, before the first deployment and after every deployment; and what fails comes back into the loop as a corrective pending item, in your words. It is the human look with a script, and it is the closing of the circuit of the process diagram: the manual execution reinjects requirements.

1. Add the routine of step 10 to the agreement (in the contract, "Routine of every pending item"), wrapped like the others. From now on, every pending item that touches a screen is closed with its case.
2. Ask it to write the cases of the pending items of the block that are already closed. Take one at random and follow it yourself in the test environment without asking it anything: if you had to ask, the case is not written for a person; have it rewritten.
3. At the close of the block, execute all the cases of the block yourself, by hand, and write in each one the date, your name, passed or failed, and the observation. Whatever annoys you and does not fall into any case, write it at the end of the file.

4. Paste it the execution prompt of the step 10 contract. Every failure has to come back as a corrective pending item in your words.

Completeness check. Could you follow a case without asking? Does every closed pending item that touches a screen have its case? Does every case say what to verify on the other side of the screen? Does the execution have a date and a name in every case? Does every failure have its pending item with your words?

Deliverable. docs/MANUAL_TESTS.md with one case per flow of the block, the first execution recorded, and one pending item per failure.

Typical mistakes. Letting the agent mark the cases as executed. Cases that are the automated test in prose. And fixing the failures on the spot, without a pending item: your words and the trail of what repeats get lost.

In the guide project. The cases of Turnera's first block are six: see the day's schedule, book an appointment, try an overbooking, cancel, search for a patient, register a patient. In the first execution two fail: cancelling (the schedule does not refresh until the page is reloaded; the practice manager's observation: "I thought it had not been cancelled") and searching (with two patients with the same surname, it shows only one). Two corrective pending items, in their words. The awkward drop-down menu for the time, which no test saw, appears as a loose observation.

Lesson 11 — Producer/consumer symmetry, and the anti-pattern register

What you need to understand. When you change one end of the system (the server, the database, a robot), the other end (the screen, a counter, a report) has to change in the same commit. If it does not, they diverge, and the user sees one number on one side and a different one on the other Ref. 26. The principle that prevents it is simple to state and hard to sustain: every list has a single owner. The possible states of an appointment, the columns of a report, the reasons something is waiting: one single part (the producer) defines them and all the others read them from there Ref. 27. The semantic tree is the first place where those lists are declared. As soon as there are two copies, one of them is out of date; the only question is which.

The second half of the lesson is the anti-pattern register (GOTCHAS): the mistakes you have already paid for once, written down with their smell, their root cause, their fix and how to detect them earlier Ref. 2. The important part is not writing them down: it is adding the automatic check that detects them, because an anti-pattern that is recorded but not automated repeats itself the moment the session changes.

The task.

1. Ask it for the contract map:

You are asking it for the inventory of contracts with both of their sides, and for whatever it cannot see to be declared rather than left out.

2. Add the routine to the agreement:

3. Do the list test: pick a list that appears on the screen (in Turnera, the states of an appointment: pending, confirmed, cancelled, no-show) and ask the agent to show you where it is defined and where it is read. If there are two definitions, ask it to leave only one, and to make it match the semantic tree.
4. The first time something breaks for the second time (it will happen), record it.

5. Paste it:

Completeness check. Pick a contract from the map: does every consumer read it from the producer, or does it keep its own copy? Is there a number shown on two screens, and do they agree? Do the states of the entities match between the code and the semantic tree? Does every GOTCHAS entry have the four parts? Did anything that was already recorded happen again?

Deliverable. docs/PRODUCER_CONSUMER_MAP.md, the routine in the agreement, and docs/GOTCHAS.md (even if it starts with a single entry).

Typical mistakes. Building the map once and never looking at it again: it has to grow with every new contract. Recording anti-patterns as anecdotes ("once it happened that…") without the "how to detect it earlier" part. And the classic: the same text of a state typed by hand on the server and on the screen; the day one of them changes, the other stays behind.

In the guide project. Turnera's map has, at the start, four or five contracts: the list of appointment states (the server defines it; the screen and the monthly report read it); the appointments table (the booking form writes it; the day view and the report read it); the patients table; and, later on, the message queue (the day view writes it; the sender reads it). The first GOTCHA is usually about dates: the day view showed the appointment on the wrong day because the server stored one time zone and the screen displayed another. Smell: "the 11 pm appointment shows up tomorrow". Root cause: two time zones. Fix: a single one, on the server. Detection: a test with an appointment at 11:30 pm.

Lesson 12 — Honest verification and proportional reporting

What you need to understand. If you are not going to read code, the agent's report has to be trustworthy, and that does not happen on its own. The model was trained to be helpful and complete, and a report that says "I could not verify this" feels less helpful than one that says "done". So you have to explicitly ask it for the bad news, the blind spots and what it did not do. If you do not ask, it does not give them to you; not because it hides them, but because it does not consider them part of the answer. I once had an authentication error reported to me with the label "success" Ref. 43.

The structure that makes a report honest is three blocks: verified (with the proof next to it), believed (what it thinks works and why it did not test it), and blind spots (what it cannot see from where it is). And one rule: bad news first.

The task.

1. Add the reporting routine to the agreement:

2. Ask it to close the next pending item and read the report against the checklist below. The first time, almost certainly, the "blind spots" block will be empty. Ask it: "what can you not see from where you are?". There has to be something (your browser, the production environment, the real data). If it insists there is nothing, you insist too.
3. Practise the "still broken". Ask it for something small, check in the test environment, and if for any reason you do not see the change (it is common: the deployment takes a while, or was not done), tell it "still broken".

4. Paste it:

Half of the "still broken" cases are fixes that are in the repository and not in the place you are looking at Ref. 45. This clause saves you hours.

Completeness check. Are the three blocks there? Did you pick a "verified" claim at random, does it have its proof next to it, and could you reproduce it? Does it cover every item you asked for? Is the bad news at the top? Did it ever say a bare "done"?

Deliverable. The routine in the agreement and three consecutive reports with the three blocks, one of them with a real blind spot.

Typical mistakes. Reading only the "verified" block and skipping the other two: the other two are the ones that protect you. Accepting "it should work" inside "verified": that is "believed" in disguise. And getting used to ever longer reports: an inflated report is covering something up with volume.

In the guide project. A good closing report for PND-004 (cancel an appointment) in Turnera: "VERIFIED: the cancellation test passes (1/1, proved red against the version that deleted); regression 6/6; end-to-end of the 'cancel' flow green, with the row marked in the database; in the test environment, appointment 17 of 3 November shows as cancelled by 'reception1' at 10:42 (screenshot). BELIEVED: the monthly report will count cancellations correctly, but I did not test it because the report is PND-011 and does not exist yet. BLIND SPOTS: I cannot see how the 'cancelled' state looks on the receptionist's phone; test that yourself."

The going-live stretch: lessons 13 to 20

These eight lessons are the ones that turn "it works" into "it can be sustained", and they are done once, in order, when the first two blocks have been built with the loop and tested by you in the test environment, and before the system acts on the world (sends messages, charges money) or has real users. In the guide project, this is the moment to add the reminders and the deposit, and that is why lesson 14 (locks) comes before building those features, not after. The four on operational quality (16 to 19) are the ones I used to do without naming them; if you are a beginner, each of their contracts has an "If you are a beginner" paragraph that explains its words; read it before the lesson.

Lesson 13 — The periodic audit as input to the plan

What you need to understand. Every so often you have to look at the whole system with fresh eyes, and what is seen does not go into a report that gets filed: it goes into the list of pending items. The important part is "fresh eyes": the one who audits must not be the one who built, because they share their assumptions. A model that built a module "knows" that the password written in the code was provisional; a model that sees it for the first time reports it for what it is. That is how two administrator doors the builder had left in a single day were found Ref. 40. You do not need another company: another session, with another instructions file, that did not take part is enough.

The task.

1. Paste it this:

You are asking it for read-only, to declare what it could not audit instead of approving it by omission, all of the code and not a sample, every finding with location, risk, evidence and priority, grades per dimension, and the P0s already as proposed pending items.

2. Read the report. Pick two findings and ask the auditor to show you the evidence (the command, the line). It has to be able to.

3. Go back to the builder's session and paste it this:

4. Repeat this lesson before the first deployment to production (lesson 15) and, afterwards, every one or two months.

Completeness check. Does the report say what it could NOT audit? Do two findings picked at random have file, line and reproducible evidence? Does every P0 have its pending item open? Will the grades be comparable with the next audit? Did a session other than the one that built do the audit?

Deliverable. docs/AUDIT_[date].md and the P0/P1 pending items opened.

Typical mistakes. Auditing with the same session that built: it will confirm its own assumptions. Accepting a report with no P0 at all on a system older than a month: it is almost never true. And filing the report without opening the pending items: there the audit was good for nothing.

In the guide project. Turnera's first audit usually finds: patient data in the log (phone numbers printed when sending messages: P0); the patient search by name without an index (P1, it will show at 5,000 patients); the appointment form not validating that the date is in the future (P1); and some dependency with a known vulnerability (P1). Four new pending items, all with file and line.

Lesson 14 — Fail-closed, locks and zero silent harm

What you need to understand. Software, by default, goes ahead when in doubt: if the validation fails, the code continues; if the service does not respond, everything is assumed to be fine. It is "fail-open", like a door that opens when the power goes out. The method inverts the default: when in doubt, no. Every consequential action (charging, sending, deleting, approving) carries a lock, has a written way back, and every new automation starts in dry-run mode, logging what it would have done, until you enable it. The locks I put in my first system are the model Ref. 28.

This lesson comes before building the features that act on the world. In Turnera, before the reminders and the deposit, which are the third block.

The task.

1. Paste it this:

You are asking it to compare what the business said with what the code does (that is where the actions nobody remembered show up), to ask about the differences, and for every action its reversibility, its lock and its way back, with the fail-closed rule written down.

2. Confirm lock by lock, with the owner.

3. Close with:

4. Now open the third block (the reminders, the deposit) with lesson 5, build it with the full loop of lessons 5 to 12, and leave it in dry-run mode. Watch the "would have sent" log for a few days before enabling real sending.

Completeness check. Is every action that charges, sends, approves or deletes in the table? Does every lock have its red test? Does every irreversible action have a written way back? Did the new automations start in dry-run mode, and did you see the log before enabling them?

Deliverable. docs/LOCKS.md, one test per lock proved red, and the automations in dry-run mode with their log.

Typical mistakes. Enabling real sending "to test with a message to my own phone": dry-run mode exists precisely for that. A lock that can be bypassed with a "for testing" parameter: that parameter will end up set in production. And not looking at the "would have done" log: it is the only window to see a mistake before it reaches a patient.

In the guide project. Turnera's lock table: send reminder (not reversible; lock: idempotency per appointment, a single send per appointment and channel, limit of 200 per day, dry-run mode first; way back: none, hence the limit); charge deposit (reversible with a refund; lock: explicit confirmation by the receptionist, amount set by the practitioner; way back: refund through the payment provider); cancel appointment (irreversible for the patient; lock: confirmation and a record of who did it; way back: recreate the appointment); delete patient (irreversible; lock: double confirmation, only the practice manager, and only if there are no future appointments; way back: none, hence double). Each lock with a test that shows that, without the lock, the action happened.

Lesson 15 — Continuous integration, environments, secrets and deployment as part of the product

What you need to understand. Reaching production has to be a reproducible package: the tests run once, the deployment only packages and uploads, the configuration lives on the server and not in the repository, there is a procedure to promote from test to production that can be run twice, and the rollback is tested (a rollback that was never tested does not exist). Tests run three times per commit burned through my continuous integration quota Ref. 39. About secrets, a rule with no exceptions: a secret that was seen in a chat, in a log or in a commit is no longer a secret; it gets rotated, full stop Ref. 42.

You already have a good part of this from the skeleton (lesson 4): continuous integration and the deployment to test. This lesson completes it towards production.

The task.

1. Paste it this:

You are asking it for the access before starting, the tests once per commit, the deployment that only packages, the configuration outside, the repeatable promotion, the tested rollback, the lock against secrets, and the documentation for a person.

2. Before the first deployment to production, do the audit of lesson 13 if you have not done it, and run the complete end-to-end suite of every flow with the exact version you are going to promote (the block-closing prompt of lesson 8).

3. Add the deployment routine to the agreement:

4. Do the first deployment to production, with the system still without real users. And then test the rollback: ask it to go back to the previous version and show you that it is running, and then to go back to the new one.
5. If at any point in the course you pasted a secret into the chat (an API key, a password), rotate it.

6. Paste it this:

Completeness check. How many times does the test suite run per commit? (once; ask for the link). Is there any real configuration value in the repository? (ask it for the empty search). Could you follow docs/DEPLOYMENT.md on your own? Was the rollback tested, when, with what evidence? Was every secret that showed up in the chat rotated? Do you know how much continuous integration quota you have left?

Deliverable. Continuous integration once per commit, the deployment that only packages, docs/DEPLOYMENT.md, the tested rollback, the anti-secrets lock active, and the system running in production (without users yet).

Typical mistakes. The deployment "by hand, quickly, because it is a small change": small changes break production because nobody tests them. The example configuration file with values that look real (they are). And not testing the rollback until the day you need it.

In the guide project. For Turnera, continuous integration runs the test suite (about 30 tests at this point, including the six end-to-end flows) on every push; the deployment to test is automatic on merging into main; the promotion to production is a command that packages the version that is in test and uploads it, with the configuration (the messaging provider's key, the payment provider's key, the database URL) in an environment file on the server that is not in the repository. The rollback is the same command with the previous version. And the anti-secrets lock is a check on every commit that rejects anything that looks like a key.

Lesson 16 — Observability and traceability, with a configurable level

What you need to understand. When something fails in production, you are going to want to know what happened without opening the code and without the agent "having a look": searching for a number and having the complete story of that action appear, from the screen to the database. That is a structured log record with a correlation id. And you are going to want to raise the detail of what the system writes, for a minute, while you investigate, without redeploying: that is the configurable level. Traceability is the other half: every consequential action (charged, sent, deleted) ends up in a list the application cannot edit, with who, when and what. Without this, the resident agent of lesson 23 operates blind and the monitorings of lessons 21 and 22 have nothing to look at Ref. 16.

1. Paste it the opening prompt of the contract of step 16 (in docs/peldanos/), exactly as it is.
2. When it shows you the identifier of a real request, search for it yourself in the log records of the test environment: it has to appear on the screen, in the backend, in the database and in the call to the message provider.
3. Raise the level to debug yourself, do an action, look, lower it. If you had to deploy, the step is not climbed.
4. Search for "Juan" (or any test name) in the log records: it must not be there.

5. Add to the agreement the routine of step 16 (in the contract, "Routine"), wrapped in "Add this routine to docs/WORKING_AGREEMENT.md:" like the others.

Completeness check. Did you follow an identifier through every layer yourself? Did you change the level without deploying? Is there any personal data in the log records? Did the cancellation of an appointment in the test environment end up in the audit trail with who and when? Is docs/OBSERVABILITY.md enough for you to find a record on your own?

Deliverable. Structured log records with a configurable level, the identifier propagated, the audit trail of the consequential actions, docs/OBSERVABILITY.md, and the routine in the agreement.

Typical mistakes. Accepting "logs" that each module writes differently. Leaving production at debug "for now". And the identifier not reaching the nightly reminders job, which is exactly where incidents get lost.

In the guide project. The identifier of "cancel appointment 17" appears in the click, in the server, in the row marked in the database and in the email to the professional. The audit trail says "reception1 cancelled appointment 17 at 10:42 from the day's schedule; outcome: ok". The receptionist in charge raises the level to trace to see why a reminder was late, finds it, and lowers it.

Lesson 17 — Optimization of the persistence layer, measured before and after

What you need to understand. The database is where systems die slowly: fine with a hundred appointments, badly with a hundred thousand. An index is like a book's: without it, the database reads the whole table to find an appointment. An N+1 loop is making a hundred queries to show a hundred appointments instead of one. This lesson applies lesson 7 to the database: measuring every query with a meter that has a test, changing what the numbers say, measuring again on the same data, and leaving a budget with a test so that it does not come back Ref. 18, Ref. 37. It is not rewriting the database or changing the engine: that was lesson 3.

1. Paste it the opening prompt of the contract of step 17.
2. Read the list of proposed changes the way the receptionist in charge would read a list of repairs for the practice: do you understand what each one gains and what risk it has? Approve or reject them one by one. Redo one calculation by hand (rows per month of the appointments table).

3. Paste it the closing prompt of the contract of step 17, with the approved list.
4. Run a meter yourself before and after, with the two commands it gave you.

Completeness check. Do your runs match the table in docs/PERSISTENCE.md? Is there any query left that reads a whole table in a critical flow? Does every table have a written retention? Do the budgets have tests (ask it to exceed one and show you the red)?

Deliverable. The meters with their test, docs/PERSISTENCE.md with before and after, the budgets with their test, and the suite green.

Typical mistakes. Measuring with the skeleton's ten records. Accepting "we had better migrate to another database". And improving a number while breaking the monthly spreadsheet that read that table: the map was missing.

In the guide project. The day's schedule was making one query per appointment (the loop of lesson 7): 52 queries for 50 appointments become 3. The search for patients by name read the whole table: an index brings it down from 800 milliseconds to 4 with ten thousand patients. Retention: the messages are archived after a year; the appointments, never. Budget: 4 queries for the schedule, with a test.

Lesson 18 — Scanning and fixing vulnerabilities

What you need to understand. A vulnerability is a defect somebody can use to get in, steal data or make the system do what it should not. The audit (lesson 13) looks for them with judgement, every so often; this lesson looks for them by machine, all the time, in four layers: the dependencies (other people's pieces that your system uses, with their known defects published), the code (static analysis), the secrets in the repository's history, and the server's configuration. And one rule: upgrading a dependency is a change, and it goes through the loop; "I bumped the version to close the finding" without a regression suite is the most common way of breaking production on a Friday Ref. 41, Ref. 23.

1. Paste it the opening prompt of the contract of step 18, with your criteria in the slot.
2. Read docs/SECURITY_[date].md. Pick two findings and ask it for the evidence. Does it say what it did NOT scan?

3. Paste it the closing prompt of the contract of step 18.
4. Ask it to slip in on purpose, on a branch, a dependency with a known vulnerability: the chain has to go red.

Completeness check. Is the last run of the scan green and from what date? Does every P0 have a pending item closed with evidence? Is the scan a gate in docs/GATES.md? Do you know when the next scheduled scan runs?

Deliverable. The four-layer scan in the chain and on a schedule, docs/SECURITY_[date].md, docs/SECURITY.md, the P0s and P1s fixed, the gate.

Typical mistakes. A scan that is "clean on the first try" on a system more than a month old: a layer was missing. Ten dependencies upgraded in one commit. An "accepted" P0 with no pending item and no date.

In the guide project. The Turnera scan finds: a dependency of the PDF generator with a known vulnerability (P1, it is upgraded with a regression suite and end-to-end suite); the header that prevents the schedule from being embedded in another site, absent (P1, one line of configuration, with a test); a test key of the payment provider in the repository's history (P0: it is rotated, even though it is a test one); and a database port open to the world on the test server (P0: it is closed). The scan is left as a gate and runs on Mondays.

Lesson 19 — Performance tests at volume and the breaking point

What you need to understand. Lesson 3 sized the system with calculations; this one checks them with the system running. A load test simulates many users at once. You look at throughput (actions per second), latency (how long each action takes; the median and the 95th percentile, which is what the ones who complain see) and the error rate, at the expected volume and at "times ten". And then you raise the load until something breaks: the breaking point is not "it gets slow" but "the database connections ran out at 180 users". That number is the most useful of the stretch, because the alert thresholds of lesson 21 come out of it Ref. 12, Ref. 44.

1. Paste it the opening prompt of the contract of step 19, with the flows and the tolerance in the slots.
2. Read docs/PERFORMANCE_[date].md with the tolerance alongside: does the day's schedule fit in two seconds at the expected volume? And at times ten? What broke first and at which load?
3. Decide with the receptionist in charge up to which volume the bottlenecks get fixed now: if they are thinking of selling it to other practices, the "times ten" is now; if not, with a date.

4. Paste it the closing prompt of the contract of step 19.
5. Run the script yourself at the expected volume with the command it gave you: the numbers have to look similar.

Completeness check. Does the most used screen fit within the tolerance, or is there a pending item with the number? Does the breaking point say what broke and at which load? Are the thresholds of docs/PERFORMANCE.md below the breaking point and above the expected one? Is the test a gate and is the first run archived?

Deliverable. The load script with its test, docs/PERFORMANCE_[date].md, docs/PERFORMANCE.md with thresholds and gate, and one pending item per bottleneck.

Typical mistakes. "It holds the times ten with no problem" without a breaking point: it did not raise the load enough. A script that hits the API and not the screen. Fixing bottlenecks during the test, "while we were at it".

In the guide project. At the expected volume, the schedule responds in 300 milliseconds; at times ten, in 1.4 seconds; the nightly sending of 400 reminders takes 50 seconds. The breaking point: at 180 concurrent users the connection pool (10) runs out and the actions start failing. Thresholds: an alert if the schedule goes over 1.5 seconds or if the connections in use go over 7. Pending item: the nightly sending in batches of 50, because the receptionist in charge does want to sell it.

Lesson 20 — Living documentation and manuals a person can follow without AI

What you need to understand. The system has to be usable, maintainable and recoverable without the agent and without you. The criterion for the recovery manual is concrete: a trusted person who does not program has to be able to follow it, at three in the morning, with the system down and the agent offline. If a step says "check with the developer", it is incomplete. And since regenerating documentation with a model is free, the rule becomes "in the same commit": every change that touches what the user sees, what the operator does or how it is deployed updates the manual in the same commit. The manuals I wrote for my first system with that criterion are the model Ref. 24.

And a source you already have: the closed pending items. If you documented every closure as lesson 5 asks, the user manual is not written from scratch: it is assembled from the pending items that were closed, block by block, and the changelog comes straight out of them.

The task.

1. Add the routine to the agreement:

2. Paste it this:

You are asking it for the three manuals with real screenshots, the three-in-the-morning criterion for the recovery manual, to ask what only the business knows instead of leaving gaps, and a date and version.

3. The real test: give the recovery manual to someone who does not program (the owner, a relative) and ask them to follow the "it went down" section in the test environment. Wherever they get stuck, the manual has to be fixed.
4. After the next screen change, check that the commit touched the user manual.
5. And now the acceptance testing: the owner uses the whole system in the test environment, with realistic data, following the six flows, before the first real user comes in. Whatever they find becomes pending items; with those closed, the system is accepted.

Completeness check. Does a screenshot picked at random match today's test environment? Could someone who does not program follow the "it went down" section? Did the last commit that changed a screen touch the manual? Does the changelog have one entry per closed pending item? Are there gaps like "[to be completed]"? Does every manual say which version it is valid for? Did the owner do the acceptance testing on every flow?

Deliverable. The three manuals with date and version, the test with a person done, and the acceptance testing closed.

Typical mistakes. Generating the manuals once and not putting the routine in the agreement: two months later they have screenshots of screens that no longer exist. A recovery manual that starts with "open a session with the agent". And not doing the test with a person: it is the only check that counts.

In the guide project. Turnera's user manual has six screens with screenshots, assembled from the closed pending items of the three blocks; the maintenance manual explains where every module is and how to run the test suite; and the recovery manual says, in order, with the commands: how to tell whether the system is down, how to restart it, how to go back to the previous version, how to restore the database from the latest backup (which is made every night: that also comes out of this lesson), and whom to call. The practice manager followed it in the test environment and got stuck at "restore the database" because the command assumed a folder she did not have; the manual was fixed.

The operation stretch: lessons 21 to 23

These three lessons begin with the first deployment to production and do not end: the two monitorings are set up with it and run on their own from then on, and the retrospective closes each stage and goes back to step 0 for the next one.

Lesson 21 — Monitoring of resources and performance, with a cyclic report

What you need to understand. Lesson 19 says how the system behaves on one day; production is every day, with the data growing. To monitor is to look by machine, all the time, at the usage of resources (processor, memory, disk, connections, the message provider's quota) and at the response time of every function and every query, and to warn when something goes out of range: above a threshold (the ones from lesson 19) or very different from the baseline (what it had been giving). An alert warns at the moment; the cyclic report is read calmly every week or every month. Two rules: an alert nobody reads is a defect of the alert; and a threshold is not raised to silence an alert without a measured reason written down Ref. 37, Ref. 39.

1. Paste it the opening prompt of the contract of step 21, with the channel, the cycle and the deviation in the slots.
2. Ask it to exceed a threshold on purpose in the test environment: the alert has to reach you through the channel.
3. Read the first report: every out-of-range event has to have a cause or a proposal.

4. Add to the agreement the routine of step 21, wrapped in "Add this routine to docs/WORKING_AGREEMENT.md:".

Completeness check. Did the provoked alert reach you? Does the report have every deviation with a cause or a proposal? Is there a pending item for every deviation you decided to attend to, with the number as the criterion? Did any threshold go up since lesson 19, and with what reason? Does the report look at the message provider's quota?

Deliverable. Collection with history, alerts, the cyclic report, docs/MONITORING.md, the routine in the agreement.

Typical mistakes. Alerts every day that nobody reads. Three reports in a row saying "everything normal". A threshold raised "so that it stops warning". Personal data stored "to diagnose".

In the guide project. Turnera's first monthly report says: disk at 40 %, memory stable, the day's schedule at 320 milliseconds median (baseline), the patient search up from 4 to 9 milliseconds (the table is growing; within range), and the message quota at 60 % (proposal: warn at 80 %). One deviation: the receptionist's monthly report took 11 seconds on the 1st (proposal: precompute it at night; pending item).

What changed on 19 October 2026 (D-039). The measurement that revalidates the sizing carries its verifiable window: the first and the last record read from the database, not a number typed by hand. In practice, 30,000 rows of three years passed as one year raised a false alarm. A window typed by hand is marked as such in the report and only warns.

Lesson 22 — Error monitoring and cyclic report

What you need to understand. A system in production produces errors nobody reports: the receptionist who saw a blank screen and tried again, the nightly job that was cut short. This lesson captures them in the three places where they hide (the backend, the jobs and the browser), groups them (a thousand times the same error is one entry with a counter), warns about the new ones and the ones that grow, and produces a report with the error rate per flow (out of every hundred appointments booked, how many failed). Two rules: no error without a pending item, and there is no such thing as a "known error" without a pending item that says why it is tolerated and until when Ref. 43, Ref. 22.

1. Paste it the opening prompt of the contract of step 22, with the channel, the cycle and the number in the slots.
2. Provoke an error yourself in the browser, in the test environment (an impossible date in the appointment form, for example): it has to appear in the capture with your identifier, and the alert has to reach you if it is new.

3. Add to the agreement the routine of step 22, wrapped like the others.
4. With the first report: open the corrective pending items for the new errors, each with its reproduction, and close them with the routine of lesson 8 (the test that reproduces it in red).

Completeness check. Did your provoked error reach the capture, the alert and the report? Is there any recurring error with no pending item and no reason with a date? Does a "fixed" error from the report have its test in red in its pending item? Is the error rate per flow there, and compared with the previous period? Is there any personal data in the capture?

Deliverable. The centralized and grouped capture, the alerts, the cyclic report with the rate per flow, docs/MONITORING.md complete, the routine in the agreement, and one pending item per error.

Typical mistakes. "Zero errors in a month" with real users: the capture does not see the browser or the jobs. An error with a thousand occurrences and the comment "known, no impact". Errors that get "fixed" by restarting. And reading the error report without cross-reading it with the resources one: the slow query of the one is the timeout of the other.

In the guide project. Turnera's first report has three errors: one in the browser (the schedule fails if the professional's name has an apostrophe; 14 times; pending item, test in red), one in the nightly job (the message provider returned an error one night; 1 time; pending item to retry with a log record), and a "known" one from the nephew in the monthly spreadsheet (pending item with a date: it is replaced by the report of lesson R2 in part 2). Error rate: 0.3 % in "book appointment", 0 % in the rest.

What changed on 19 October 2026 (D-038). Error capture separates by source: the errors of the system and those of the tools that watch it (the panel, the resident agent, the monitoring itself) go in different sections of the report, and only the system's errors open pending items. In practice, the first cyclic report opened six "bugs" that were the tool talking to a server that was off.

Lesson 23 — The agent inside the system, and the retrospective with numbers

What you need to understand. Two things close the cycle. The first is optional: leaving the agent resident in production, with a bounded scope, to diagnose and give support without you being there Ref. 13. The rule that orders it is that it acts on behalf of someone: its credential is mapped to a responsible person, and everything it does is logged under that person's name; it is not an anonymous account, it is an employee with a boss. The second is mandatory: the retrospective with numbers. What it cost, how many pending items, which ones went round in circles, which incidents there were and which step they fall into, and at least one proposed change to the ladder. A retrospective that changes nothing was not a retrospective; the one that led me to eliminate an entire team of agents is the model Ref. 6.

The task (resident agent, if applicable).

1. Paste it this:

You are asking it for the map before operating, for the gaps in the map to be declared, three levels of scope so that you pick one, and the credential in a person's name.

2. Pick the level (to begin with, always the first: read-only and diagnosis).

3. Close with:

The task (retrospective, always).

4. Paste it this:

You are asking it for numbers with a source, every incident mapped to a step (an incident that falls into none is a missing step), to ask you for the numbers it does not have, and a concrete proposal to change the ladder.

5. Read the proposed change. If it seems valid to you, send it to the Urazuke repository as an improvement proposal (see CONTRIBUTING.md): that is how the method learns from every project.

Completeness check. Does the map say what the agent can NOT see? Did you see in the log that an action outside the scope is rejected? Does the credential act on behalf of a person? Does the retrospective have numbers with a source, or adjectives? Does every incident fall into a step? Is there at least one concrete proposed change?

Deliverable. docs/RESIDENT_AGENT.md (if applicable) and docs/RETROSPECTIVE_[date].md.

Typical mistakes. Giving the resident agent a high level "so it can solve everything": start with read-only and raise it when there is evidence. A retrospective that says everything went well: nothing ever goes entirely well; it is written for you, not for the method. And not sending the proposed change: step 23 closes when the ladder changes, not when the document gets written.

In the guide project. Turnera's retrospective, in a typical course: about forty hours of the student's time, twenty-eight pending items, the ones that went round the most were the messaging ones (time zones and the WhatsApp provider); two incidents, one in step 11 (the "no-show" state existed on the screen and not on the server, nor in the semantic tree) and another in step 15 (a deployment to production with the test configuration, caught by the end-to-end check after the deployment). Proposed change: that the deployment routine of step 15 require showing the configuration difference between test and production before promoting, not just "what changes".

The go-live checklist

When the twenty-four lessons are done, the system meets this list. It is the operational definition of "production grade" in Urazuke, and it can be used as the final checklist, with the owner, without opening the code:

1. There is an eligibility sheet with a decision, date and name (S0).
2. There is a working agreement the agent reads in every session, and it was proved that it reads it (S1, S2).
3. The project file can be read in five minutes and says what the system is NOT; there is a semantic tree confirmed by the owner, and every pending item hangs from a node (S2).
4. There is a sizing with primary data with its source, derived data with its arithmetic, and the "times ten" scenario (S3).
5. The skeleton was deployed empty during start-up, with the integration and deployment chain, and the deployment was run twice (S4).
6. Every change has its pending item with a detailed specification, and every closed pending item keeps its specification and its evidence: it is the documentation of what was done (S5).
7. Every business rule has an owner, a date and the exact words, in the commit, in the pending item and in the register (S6).
8. Every number that decided something has a meter with a test that you can run (S7).
9. Every important test was seen red before green; every flow has its end-to-end test that verifies the backend from the screen; the full suite was run at the close of every block and before production (S8).
10. The quality of the code is verified by machine on every commit, it is a gate, and the coverage never dropped (S9).
11. Every feature has its manual test cases, written for a person; they were executed at the close of every block and in the acceptance, with a date and a name; every failure came back as a pending item (S10).
12. Every list has a single owner; there is a producer/consumer map; there is an anti-pattern register with automatic checks (S11).
13. Every report separates verified, believed and blind spots (S12).
14. There was at least one audit by a different session, and its P0s are pending items (S13).
15. Every consequential action has a lock with a red test and a way back; the automations went through dry-run mode (S14).
16. The tests run once per commit; the configuration is outside the repository; the rollback was tested; no secret lives in the repository or in the chat without being rotated (S15).
17. The log records are structured, with a level configurable without deploying, with an identifier that follows each action from the screen to the database; the consequential actions are kept in an immutable audit trail; no personal data in the log records (S16).
18. The real queries were measured at the expected volume, corrected with a before and an after, and there are budgets with a test per critical path (S17).
19. The vulnerability scan runs on every push and on a schedule, it is a gate, and there is no open P0 (S18).
20. There is a load test with its test, run at the expected volume and at "times ten", with the breaking point written down and the thresholds derived from it (S19).
21. There are three manuals with date and version, assembled from the closed pending items; a person who does not program followed the recovery one; the owner did the acceptance testing on every flow (S20).
22. Resource usage and response times are watched with alerts and a cyclic report, and every deviation has a cause or a pending item (S21).
23. The errors are captured in the backend, the jobs and the browser, they are grouped, they are reported per cycle with the rate per flow, and none is left without a pending item (S22).
24. There is a retrospective with numbers and a proposed change to the ladder (S23).

If all twenty-four say "yes", the system is ready to go live. If any says "no", you already know which step to climb again.

And then: part 2, the inherited project

This first part teaches the method on an empty folder because that is the clearest way to learn it. But in real life you are almost never handed an empty folder: you are handed a system that already runs and you are asked to "fix this" or "add that". Part 2 of the course takes the same practice on another timeline, with an application a nephew built them one summer and that nobody understands in full, and teaches the normalization stretch of the evolutive-corrective path: eight lessons to recover the inputs the method takes for granted, build the safety belt and order the debt, and two more to correct the first bug and build the first new functionality with the full method.

Annex A — How to assess (for whoever teaches the course or self-assesses)

A simple rubric, per lesson, with three levels:

• Not climbed: the deliverable is missing, or some completeness check says "no".
• Climbed: the deliverable exists and every check says "yes".
• Climbed with evidence of judgement: in addition, the student can tell of a case in which the agent did something wrong in that lesson (assumed, invented, over-reported) and how they caught it. That is the real goal of the course: not the artefact, but the reflex.

What is not assessed: the quality of the code. Nobody reads it. What is assessed is the quality of the evidence.

Annex B — Adapting the course to each tool

The prompts are the same in any tool. What changes is where the routines that the course adds to docs/WORKING_AGREEMENT.md go:

• In Claude Code, the routines go in the project's CLAUDE.md (or the agreement is included from there), and they are read on their own in every session.
• In Cursor, they go in .cursor/rules/, as always-active rules.
• In Codex CLI or Gemini CLI, in AGENTS.md or GEMINI.md at the root.
• In Forge, the agreement and the routines are doctrines, the step prompts are injected on their own when each gate is crossed, the pending-items register is native and the semantic tree is the project's knowledge graph. The course with Forge is the same course with less copying and pasting.

The reading test of lesson 2 holds for all of them: if a new session does not know what the system does NOT do, the tool is not loading the file where you put the agreement.

Annex C — What this manual does not have yet

• A cohort that has taken it. The order of the stages, the typical mistakes and the guide project are written from my three systems, not from students. The first cohort will correct them (and that is, literally, step 23 applied to the course).
• The weights of the eligibility criteria (lesson 0), which I am calibrating.
• A complete example of the guide project's docs/PENDING.md, with the twenty-eight pending items specified and closed, so that a student can see what the documentation of what was done looks like at the end of a project.