Prompts module 3: building jobs, from code to architecture

Day 29 · 01/12 — Developer: code review

Goal: get a review that finds real defects, ranked, instead of style remarks.

Theory 1/2: the weak prompt

Review my code. (paste of 300 lines)

Diagnosis: no purpose for the code, no criteria, no priority. The model returns a dozen remarks on naming and comments, mixed with one real bug you may miss. A review prompt says what the change is meant to do, what matters (correctness, security, then style), and asks for findings with a concrete failure case each.

Theory 2/2: the edited prompt

Context: Python 3.13 function that parses uploaded CSV files of
orders; it runs on a server, files come from customers.
Task: review the diff below for defects, in this order of priority:
1) wrong results, 2) crashes on bad input, 3) security, 4) clarity.
<diff>…</diff>
Output: at most 8 findings, most severe first, each with: the line,
the input that triggers it, what happens, the smallest fix.
Do not report style unless it hides a defect. If you find nothing
in a category, say so.

Practice (30 min)

1. Take a function you wrote recently. Plant two bugs: an off-by-one and an unchecked empty input.
2. Run the weak and the edited prompts. Did each find the planted bugs? At what rank?
3. For each finding, write a test that shows it, or mark it as false.
4. Card prompts/dev-code-review.md; the planted-bug file becomes its test case.

With your AI: "Here is my function [paste]. Do not review it. Ask me five questions a careful reviewer would ask about edge cases (empty, huge, wrong type, concurrent, malicious input), one at a time, and tell me after each whether my answer reveals a bug."

Recap (10 min)

Three lines: purpose and priority, a failure case per finding, the planted-bug test. Then redo the exercises without notes.

Day 30 · 02/12 — Developer: asking for tests

Goal: get tests that would fail on a wrong implementation, not tests that mirror the code.

Theory 1/2: the weak prompt

Write unit tests for this function. (paste)

Diagnosis: given only the code, the model writes tests that assert what the code does, bugs included. Tests should come from what the function is supposed to do. Give the specification and the edge cases, ask for tests from them, and check the tests by breaking the code: a test that still passes on broken code tests nothing.

Theory 2/2: the edited prompt

Write pytest tests for slugify(title) from this specification only:
- lowercase; spaces and punctuation become single hyphens;
- accents removed ("Zürich" -> "zurich"); no leading or trailing hyphen;
- empty or only punctuation -> "" ; max length 60, cut at a hyphen.
Constraints: one test per rule, plus edge cases you think the spec
implies (list them separately so I can accept or reject them);
use pytest.mark.parametrize; no mocks.
Output: the test file only.

Practice (30 min)

1. Write slugify yourself from the specification, in Python.
2. Generate the tests with the edited prompt; run them with pytest.
3. Break your function three ways (drop accent removal, keep a trailing hyphen, cut at 61). After each, the tests must fail. Note which mutation survived.
4. Card prompts/dev-tests-from-spec.md.

With your AI: "Here is a specification [paste]. List the edge cases it does not settle (ambiguous inputs), as questions I must answer before any test is written. Do not write the tests."

Let an agent do it: now that you have checked tests against mutations by hand, a coding agent can write tests and run the mutations itself: "Write pytest tests for slugify from SPEC.md only, then apply three mutations to slugify one at a time, run the tests after each, and report which mutation survived; restore the file at the end." You still read the tests: an agent can also write tests that pass for the wrong reason.

Recap (10 min)

Three lines: tests from the spec, edge cases listed apart, mutations as the check. Then redo the exercises without notes.

Day 31 · 03/12 — Developer: debugging with a model

Goal: give a model a minimal reproduction and get hypotheses you can test.

Theory 1/2: the weak prompt

It doesn't work, here's my whole project. (zip of 40 files)

Diagnosis: too much and too little. Too much code dilutes the context (day 1); too little information on the failure: what you ran, what you expected, what you got. Stack Overflow's "minimal, reproducible example" is the same discipline: the smallest code that still fails, the exact error, the expected result.

Theory 2/2: the edited prompt

Context: Node.js 22, a script that reads a JSON config.
<code>(the 15 lines that fail)</code>
<run>node read.js config.json</run>
<error>(full stack trace)</error>
Expected: prints the "port" value. Already tried: the file exists,
JSON validates with jq.
Task: give 3 hypotheses ranked by likelihood; for each, the one
experiment that confirms or rules it out. Do not rewrite the code.

Practice (30 min)

1. Take a bug you had recently (or plant one in a small script). Cut the code down until it is under 20 lines and still fails.
2. Run the edited prompt. Run each proposed experiment yourself; note which hypothesis held.
3. If the bug came from a change, find it with git bisect as well, and compare with the model's ranking.
4. Card prompts/dev-debug-hypotheses.md.

With your AI: "Act as a rubber duck that asks questions. I will explain my bug; reply only with one question at a time that makes me state an assumption, and stop when I find the cause myself."

Recap (10 min)

Three lines: minimal reproduction, ranked hypotheses, experiments not fixes. Then redo the exercises without notes.

Day 32 · 04/12 — Developer: refactoring without changing behaviour

Goal: get a refactoring that keeps behaviour, proven by the tests you had before.

Theory 1/2: the weak prompt

Clean up this code.

Diagnosis: "clean" is not a goal. The model renames, reorders, "fixes" behaviour it found odd, and adds features. Martin Fowler defines refactoring as changing the structure of code without changing its observable behaviour; a refactoring prompt says which structural problem to fix, forbids behaviour changes, and rests on tests that pass before and after.

Theory 2/2: the edited prompt

Refactor the function below. Goal: split it into one function per
step (parse, validate, compute total), no other change.
Constraints: same public signature; same return values and
exceptions for every input; no new dependency; keep existing names
where possible. If you see a bug, report it in a comment at the end,
do not fix it.
<code>…</code>
<tests>(the existing tests, which must still pass)</tests>
Output: the new code, then a list of every change.

Practice (30 min)

1. Pick a long function of yours with tests (write three first if it has none).
2. Run the edited prompt; apply the result in a branch; run the tests.
3. Read the list of changes against the diff: anything in the diff that is not in the list?
4. Card prompts/dev-refactor.md.

With your AI: "Here is a diff that claims to be a pure refactoring [paste]. List every line where observable behaviour could have changed (return values, exceptions, side effects, order), with the input that would show it."

Recap (10 min)

Three lines: tests first, one structural goal, bugs reported not fixed. Then redo the exercises without notes.

Day 33 · 05/12 — Developer: reading unfamiliar code, writing commit messages

Goal: use a model to understand code faster, and to describe your own changes accurately.

Theory 1/2: explaining code

Weak:   What does this code do?
Edited: I am new to this codebase and know Python, not asyncio.
        Explain the function below for me: 1) its purpose in one
        sentence; 2) the path of one request through it, step by
        step; 3) the asyncio notions it uses, each in one line with
        a link to the Python documentation. Mark anything you infer
        rather than read in the code as (inferred).

The edited version says who reads, asks for a walk-through rather than a paraphrase, and separates what is in the code from what is guessed.

Theory 2/2: commit messages

A model can draft a commit message from a diff, but only you know why the change was made. Give it the why; ask it for the format your project uses, such as Conventional Commits; then check that every line of the message matches the diff.

Draft a commit message for the staged diff below.
Why: users with an empty cart got a 500 on checkout.
Format: Conventional Commits; subject under 60 characters,
imperative; body: what changed and why, wrapped at 72.
<diff>…</diff>

Practice (30 min)

1. Pick a file from an open-source project you use. Run the edited explanation prompt; check each "step" by reading the code yourself, and each documentation link by opening it.
2. For your next three commits this week, draft the message with the commit prompt from git diff --staged, then edit it by hand.
3. Cards prompts/dev-explain-code.md and prompts/dev-commit-message.md.

With your AI: "I have just read this function [paste]. I will explain it back to you in my own words; tell me what I got wrong or left out, without giving me a full explanation of your own."

Let an agent do it: coding agents draft commit messages from the staged diff as part of their work. Give them the why and the format in your project instructions file. You still read the message against the diff before the commit lands.

Recap (10 min)

Three lines: walk-through not paraphrase, label inferences, the why comes from you. Then redo the exercises without notes.

Day 34 · 06/12 — Web design: heuristic and accessibility review

Goal: get a design critique against named references, and check it with tools.

Theory 1/2: the weak prompt

What do you think of my website design?

Diagnosis: taste with no reference. The model will praise and suggest "more white space". A design review prompt names the users and their main task, and a reference: Jakob Nielsen's ten usability heuristics, or the WCAG 2.2 success criteria for accessibility.

Theory 2/2: the edited prompt

Context: sign-up page of a small booking site; users are mostly
over 60, many on phones.
Main task: create an account in under 2 minutes.
Inputs: <html>(the page's HTML)</html> and a description of the
screenshot: <screen>…</screen>
Task: review against Nielsen's 10 heuristics and these WCAG 2.2 AA
criteria: 1.1.1, 1.4.3, 2.4.7, 3.3.1, 3.3.2.
Output: | reference | element (quoted) | problem | fix |, most
harmful to the main task first. Say which criteria cannot be
judged from the inputs (contrast needs real colours, for instance).

Practice (30 min)

1. Take a page you built (or a simple public form you may copy for study). Run the edited review.
2. Check its contrast findings with the WebAIM contrast checker, and navigate the form with the keyboard only.
3. Mark each finding confirmed, wrong or not checkable.
4. Card prompts/design-heuristic-review.md.

With your AI: "Quiz me on Nielsen's ten heuristics: describe one interface problem at a time and ask me which heuristic it breaks. Ten rounds, then my score."

Recap (10 min)

Three lines: users and main task, named references, tool checks. Then redo the exercises without notes.

Day 35 · 07/12 — UX: research synthesis and interface text

Goal: use a model on real research notes and on microcopy, never as a substitute for users.

Theory 1/2: no invented users

Weak:   Create 3 personas for my app and tell me what they want.

Diagnosis: personas from nowhere are the model's stereotypes, presented as research. A model can help you organise what real people said: group interview notes by theme, count how many people raised each theme, quote them. It cannot tell you what your users want without data from them.

Edited: Here are notes from 6 user interviews, one per <interview>
        tag. Group the problems they mention into themes. For each
        theme: a name, how many interviews mention it, two exact
        quotes with the interview number. Do not add themes no
        interview mentions.

Theory 2/2: interface text

For microcopy (button labels, error messages), give the situation, the user's state of mind, the length limit and the rule: an error message says what happened and what to do next.

Write 3 versions of the error message shown when a password is
too short (minimum 12 characters). Users are mid-sign-up, often
on a phone. Max 80 characters. Say what to do, not only what
went wrong. No blame, no exclamation mark.

Practice (30 min)

1. Interview three people (friends, family) for ten minutes about a tool they find annoying. Take notes.
2. Run the synthesis prompt on your notes. Check every quote against your notes and every count by hand.
3. Write three error messages for your own project with the microcopy prompt; pick one and say why.
4. Cards prompts/ux-research-synthesis.md and prompts/ux-microcopy.md.

With your AI: "I am preparing a 10-minute user interview about how people manage their passwords. Review my five questions [paste] and flag any that are leading or ask about the future instead of past behaviour."

Recap (10 min)

Three lines: no invented users, counts and quotes, what an error message says. Then redo the exercises without notes.

Day 36 · 08/12 — Data: from a question to SQL

Goal: get a correct query by giving the schema and a question precise enough to have one answer.

Theory 1/2: the weak prompt

Write a SQL query to get the best customers.

Diagnosis: no schema, so the model invents table names; no dialect; and "best" has no definition (most orders? most revenue? this year?). Text-to-SQL works when the model sees the real tables and the question is unambiguous.

Theory 2/2: the edited prompt

Dialect: PostgreSQL 17.
<schema>
CREATE TABLE customers (id int PRIMARY KEY, name text, country text);
CREATE TABLE orders (id int PRIMARY KEY, customer_id int REFERENCES
  customers(id), placed_at timestamptz, total_cents int,
  status text CHECK (status IN ('paid','refunded','cancelled')));
</schema>
Question: the 10 customers with the highest paid revenue in 2026,
with their name, country and revenue in euros. Refunded and
cancelled orders do not count. Ties: order by name.
Output: the query only, then one line per assumption you made.

Practice (30 min)

1. Create the two tables in a local PostgreSQL (or SQLite, adjusting the dialect line), and insert 15 rows by hand with known answers, including a refunded order and a tie.
2. Write the query yourself first. Then run the edited prompt and run its query.
3. Compare both results with the answer you computed by hand.
4. Card prompts/data-text-to-sql.md, with your 15 rows as the test fixture.

With your AI: "Here is my schema [paste]. Give me five business questions of growing difficulty that this schema can answer, one at a time. I write the SQL; you tell me whether it answers the question exactly, and give a row set where it would differ if not."

Recap (10 min)

Three lines: schema, dialect, an unambiguous question. Then redo the exercises without notes.

Day 37 · 09/12 — Data: reviewing a query, cleaning data

Goal: get a performance review grounded in the query plan, and a cleaning plan you can audit.

Theory 1/2: performance needs the plan

Weak:   Why is my query slow?
Edited: PostgreSQL 17. The query below takes 4 s on 2 million rows
        in orders. <query>…</query>
        <plan>(output of EXPLAIN (ANALYZE, BUFFERS))</plan>
        <indexes>(output of \d orders)</indexes>
        Task: name the most expensive node of the plan (quoted),
        why it is expensive, and one change to test. Do not suggest
        changes to the server configuration.

Without the plan, the model can only recite general advice ("add an index"). With it, the expensive node is in the text, and you can check the quote.

Theory 2/2: cleaning data

For data cleaning, ask for a plan of rules before any transformed data: each rule, the rows it touches, and what it does to them. You apply the rules in code and count. A model that "cleans" a file directly will silently change values you never asked it to touch.

Practice (30 min)

1. Load 100 000 generated rows into orders (generate_series), run a query filtering on placed_at, and capture EXPLAIN (ANALYZE, BUFFERS).
2. Run the edited prompt. Apply its suggested change, rerun the plan, compare timings.
3. Take a small messy CSV (public data set). Ask for cleaning rules; apply them in Python or SQL; count rows changed per rule.
4. Cards prompts/data-query-plan-review.md and prompts/data-cleaning-rules.md.

With your AI: "Here is an EXPLAIN ANALYZE output [paste]. Do not tell me what is slow. Ask me to find the node with the highest actual time, then the reason, giving hints only when I am stuck."

Recap (10 min)

Three lines: the plan as input, the quoted node, rules not edits. Then redo the exercises without notes.

Day 38 · 10/12 — ML: experiment design and leakage

Goal: use a model to review an experiment plan, and catch the classic mistakes.

Theory 1/2: the weak prompt

How can I get 99% accuracy on my data set?

Diagnosis: the goal is a number, not a useful model. Very high accuracy is often a symptom: an imbalanced data set (99% of one class), or leakage, where information about the target slips into the features or the test set. scikit-learn's "Common pitfalls" page covers leakage with examples.

Theory 2/2: the edited prompt

Review my experiment plan for leakage and evaluation mistakes.
Data: 50 000 customer records, one row per customer per month,
target "churned next month" (8% positive).
Plan: <plan>(features, how I split, preprocessing, metric)</plan>
Output: each risk with: the step of the plan (quoted), why it can
leak or mislead, how to test for it. Then the metric you would
report and why. Do not propose a model architecture.

Practice (30 min)

1. Write a one-page plan for a small public data set (for example one of scikit-learn's built-in sets). Include one leak on purpose (random split of time-ordered rows, or scaling before split).
2. Run the edited prompt. Did it find your leak? Did it flag non-issues?
3. Run the experiment both ways in a notebook; note the difference in score.
4. Card prompts/ml-experiment-review.md.

With your AI: "Quiz me on data leakage: describe one experiment setup at a time, some with a leak and some clean, and ask me whether it leaks and why. Eight rounds."

Recap (10 min)

Three lines: suspicious scores, two kinds of leak, the metric for imbalanced data. Then redo the exercises without notes.

Day 39 · 11/12 — ML: a language model as a labeller, measured

Goal: use a model to label data, and measure it against labels you made yourself.

Theory 1/2: labelling is a classification task

A language model can label text (sentiment, topic, intent) without training, with the same prompt as day 27: fixed labels, definitions, examples, structured output, low temperature. Before using its labels, label a sample yourself (a "gold" set) and measure agreement. If the model disagrees with you often on one label, the definition is unclear, to the model and perhaps to you.

Theory 2/2: measure it

function accuracy(pred, gold) {
}

function accuracy(pred, gold) {
  if (pred.length !== gold.length || gold.length === 0) return null;
  let ok = 0;
  for (let i = 0; i < gold.length; i++) {
    if (pred[i] === gold[i]) ok++;
  }
  return ok / gold.length;
}

Practice (30 min)

1. Take 40 short public texts (product reviews from an open data set). Label them yourself: positive, negative, mixed.
2. Label them with your local model and a labelling prompt; compute accuracy and, per label, how many the model got right.
3. Rewrite the definition of the worst label; rerun; compare.
4. Card prompts/ml-labeller.md with the gold set as its test.

With your AI: "Here are 10 texts where my label and the model's label differ [paste]. For each, argue briefly for both labels, then tell me which part of my label definitions is ambiguous."

Recap (10 min)

Three lines: the gold set, the accuracy per label, fixing definitions. Then redo the exercises without notes.

Day 40 · 12/12 — QA: test cases from requirements

Goal: derive test cases from a requirement, with boundaries, in a format a team can run.

Theory 1/2: the weak prompt

Write test cases for the login page.

Diagnosis: no requirement, so the model tests what login pages usually do, not what yours must do. Test design starts from the rule: give the requirement text, ask for the classes of input (valid, invalid, boundaries) and the expected result of each.

Theory 2/2: the edited prompt

Requirement: <req>A user's account is locked for 30 minutes after
5 failed login attempts within 15 minutes. A successful login resets
the counter.</req>
Task: write test scenarios in Gherkin (Given/When/Then), covering:
nominal, each boundary (attempt count, time window, lock duration),
the reset. One scenario per behaviour.
Then list the questions the requirement leaves open (for example:
does a failed attempt during the lock extend it?). Do not answer
them yourself.

Practice (30 min)

1. Write the scenarios yourself for the lock rule: at least six.
2. Run the edited prompt; compare its scenarios with yours. Which boundaries did each of you miss?
3. Answer the open questions as a product owner would, and add the scenarios they imply.
4. Card prompts/qa-scenarios-from-requirement.md.

With your AI: "Here is a requirement [paste]. Act as a QA lead interviewing me: ask me, one at a time, for the boundary values and the expected result at each, and tell me when I forget one."

Let an agent do it: once you have written scenarios by hand, an agent can turn approved Gherkin scenarios into automated tests in your framework and run them: "Implement the scenarios in features/lock.feature as pytest-bdd steps, run them, and report which fail." You still review the step code: a step that asserts nothing makes every scenario green.

Recap (10 min)

Three lines: start from the requirement, boundaries, open questions. Then redo the exercises without notes.

Day 41 · 13/12 — QA: bug reports and exploratory charters

Goal: turn rough notes into a bug report a developer can reproduce, and plan an exploratory session.

Theory 1/2: the bug report

Weak:   Write a bug report: the cart is broken on mobile.
Edited: Turn my notes into a bug report with: title (what fails,
        where), environment, steps to reproduce (numbered), expected
        result, actual result, frequency, attachments to add.
        Use only what is in my notes; write [ASK] where a field is
        missing. <notes>…</notes>

The weak prompt invites invented steps. The edited one keeps the facts, structures them, and shows what to collect before sending.

Theory 2/2: exploratory charters

Exploratory testing is planned with a short charter: what to explore, with what resources, to find what kind of information. A model is good at proposing charters from a feature description; you choose and run them.

Feature: <feature>discount codes at checkout</feature>
Propose 5 exploratory charters in the form "Explore … with … to
discover …", each a 30-minute session, aimed at different risks
(calculation, combination with other offers, expiry, abuse, display).

Practice (30 min)

1. Find a real small bug in any web app you use (a layout glitch is enough). Write rough notes.
2. Run the bug report prompt; fill the [ASK] fields yourself; reproduce the steps on a second device.
3. Generate charters for one feature of a project of yours; run one for 20 minutes and note what you found.
4. Cards prompts/qa-bug-report.md and prompts/qa-charters.md.

With your AI: "Here is my bug report [paste]. Act as the developer who receives it: ask me the questions you would need answered before you could reproduce the bug. Stop when you could reproduce it."

Recap (10 min)

Three lines: the fields of a report, [ASK] over invention, the charter form. Then redo the exercises without notes.

Day 42 · 14/12 — Architecture: decisions and trade-offs

Goal: use a model to widen the options and stress a decision, then record it as an ADR.

Theory 1/2: the weak prompt

Should I use microservices or a monolith?

Diagnosis: no context, so the answer is "it depends", followed by a generic comparison. An architecture prompt gives the forces: team size, load, deadlines, skills, constraints. It asks for options with their consequences, and for the arguments against your preferred option.

Theory 2/2: the edited prompt and the ADR

Context: booking app, 2 developers, 200 daily users, one VPS,
release weekly; must add online payment in 3 months.
Decision to make: where the payment logic lives.
Task: 1) three options, each with consequences for deployment,
testing, failure isolation and cost; 2) the strongest argument
against my preferred option (a module in the existing monolith);
3) what would make me revisit the decision later.
Output: an Architecture Decision Record: Title, Status, Context,
Decision, Consequences. Leave Decision as [TO DECIDE].

Michael Nygard proposed the Architecture Decision Record in 2011: a short file per decision, kept with the code. The model drafts the options; the decision and its status are yours.

Practice (30 min)

1. Pick a real decision in one of your projects (database, hosting, framework).
2. Write the context with the forces. Run the edited prompt.
3. Check one claimed consequence per option against official documentation. Write the decision yourself.
4. Commit the ADR in docs/adr/0001-….md of that project; card prompts/archi-adr.md.

With your AI: "Here is my ADR [paste]. Act as a sceptical senior architect: ask me three questions that test whether the context really supports the decision, one at a time."

Recap (10 min)

Three lines: forces, options with consequences, the decision stays yours. Then redo the exercises without notes.

Day 43 · 15/12 — Module 3 review: the build prompt pack

Goal: deliver the tested prompts of the build jobs and fix the weakest one.

Theory 1/2: what changed from module 2

The build prompts added two habits: derive from the specification, not from the artefact (tests from the spec, not the code; test cases from the requirement), and keep decisions and behaviour changes with the human (report bugs during a refactoring, [TO DECIDE] in an ADR, no invented users). The external checks were tests, mutations, query plans, accessibility tools and gold sets.

Theory 2/2: pick the better prompt

Practice (30 min)

1. Rerun every card of the module on its test case; update ## History.
2. Pick the card with the lowest score; apply the day 8 loop twice.
3. Write jobs/build.md: one paragraph per job of the module, with the prompt you would reuse first.
4. Module 3 deliverable: the build prompt pack on your forge, with the before and after of the prompt you improved.

With your AI: "Here is my weakest prompt card and its failures [paste]. Do not rewrite it. Ask me questions until I can say myself which of the seven parts is causing the failures."

Recap (10 min)

Write the two habits and five external checks of the module from memory. Then redo the exercises you got wrong.