Applied Reasoning for AI Work

About 135 min read

🧠 Applied Reasoning for AI Work#

About 135 min read

A complete guide to thinking clearly, solving problems well, and getting the best work from an AI agent.

16 subjects · 103 thinking moves · 10 playbooks · simple English

Examples come from three places: the PPSC practice platform (past-paper MCQs), client websites (Next.js + Sanity), and an online store.


Part 0: Start here#

What is Applied Reasoning?#

  • Reasoning = the way you think to reach an answer or a decision.
  • Applied = used on real problems, not on school exercises.

So Applied Reasoning is practical thinking. It is the skill of:

  1. understanding a problem,
  2. finding its real cause,
  3. creating good options,
  4. choosing well,
  5. building safely,
  6. checking the result,
  7. and learning from what happened.

This guide teaches this skill for one special situation: working with an AI agent.

The agent is fast and knows a lot. But it does not know your project, your goals, or what is in your head. It also has its own bad habits. When your thinking is clear, the agent's work becomes much better.

💡 The main idea of this guide: most bad answers from an agent are not caused by bad writing. They are caused by unclear thinking before the writing. This guide fixes the thinking.


What is a "thinking move"?#

A thinking move is a named way of thinking. The name is short, but it carries a full set of instructions.

Example: you write "use first principles". The agent understands a whole procedure:

  1. Forget the existing solution.
  2. Find the real goal.
  3. Find what must be true.
  4. Build up from there.

You did not write these 4 steps. The name did the work.

Names are powerful for three reasons:

Reason What it means
You remember When you know the name, you remember the move at the right moment.
The agent knows The agent already knows famous moves. The name starts the full procedure.
Same meaning You and the agent think of the same thing. Less confusion.

This guide has 103 moves. You do not need all of them every day. You need to know they exist, so you can pick the right one when you need it.


The 7 bad habits of AI agents#

The agent is not a person, but it has habits. Many moves in this guide exist to fight these habits.

# Habit What it means Moves that help
1 Anchoring If you show your solution, it improves YOUR solution. It does not question it. 2.1 Anchoring, 6.1 First principles, 6.6 Clean-slate comparison
2 The typical answer It gives the most common answer, not the best answer for you. 2.9 Typical-answer default, 3.7 Scale, 5.1 Expanding the solution space
3 Pleasing you It agrees too easily, to make you happy. 2.8 Sycophancy, 8.2 Steelman, 15.5 Fresh-eyes review
4 Silent guessing When something is unclear, it guesses and continues. 4.1 Ambiguity, 12.2 Missing information, 12.8 Stop condition
5 Doing too much It adds features and "cleans" code you did not ask about. 3.6 Non-goal, 13.5 Minimal change
6 Claims without proof It says "done" or "fixed" without checking. 12.5 Definition of done, 15.1 Evidence
7 Forgetting in long chats In long chats, early rules get weaker. 2.10 Context drift, 11.6 Fresh start

The map of the field#

Applied Reasoning has 16 subjects in 6 parts. The parts follow the life of a problem, from "I have a problem" to "I learned from it".

Part Subjects The question it answers
1. Your own mind 1 Metacognition · 2 Thinking traps Is my own thinking clear and fair?
2. Understanding the problem 3 Problem framing · 4 Shared meaning What is the real problem, in clear words?
3. Finding solutions 5 Generating ideas · 6 Designing from scratch · 7 Systems thinking What could we do? How should it be built?
4. Choosing 8 Testing your thinking · 9 Decisions under uncertainty · 10 Rules of thumb Which option is best? Is my plan really good?
5. Doing the work 11 Working with your agent · 12 Giving clear tasks · 13 Changing code safely How do we build it without breaking things?
6. Checking and learning 14 Diagnosis · 15 Verifying work · 16 Learning loops Did it work? If not, why? What do I learn?

After the subjects:

  • Part 7: Playbooks. Common situations, with the moves to use in order, and a ready prompt.
  • Part 8: Cheat sheets. All 103 moves on one page, and a "which move should I use?" table.

How the subjects connect

Think of it as a circle:

text
   Understand  →  Find solutions  →  Choose  →  Do  →  Check  →  Learn
       ↑                                                          │
       └──────────────────────────────────────────────────────────┘
  • Part 1 (your own mind) sits around the whole circle. Thinking traps can damage every step.
  • Learning loops send you back to the start, smarter than before.
  • Diagnosis (Part 6) and Problem framing (Part 2) are close friends. Both ask "what is really going on?" Framing asks it before you build. Diagnosis asks it after something went wrong.

How each move is explained#

Every move has the same simple parts:

Part What it gives you
In one line The whole idea in one sentence.
The idea A short, simple explanation. Often with an everyday example.
How to do it Clear steps.
Example ❌ a weak prompt and ✅ a better prompt.
Say this A sentence you can copy into your chat.
Careful When NOT to use it, and what it is often confused with.

At the end of each subject there is a short practice task.

Hard English words are explained in brackets, like this: bias (a habit of the mind that pushes you in a wrong direction).


How to study this guide#

  1. First, read Part 0 (this part) and Part 7 (Playbooks). Then you see the whole field and how it is used.
  2. Then study one subject per day. Do the practice task. Use 1 or 2 moves in real chats that same day.
  3. After studying a move, you should be able to:
    • say what it means in your own words,
    • know when to use it, and when not to use it,
    • use it in a prompt without looking at this guide.

⚠️ Do not put 10 moves in one prompt. Usually 1 to 3 moves are enough. Too many moves confuse the agent, and you.


Start with these 12 moves#

If you only learn 12 moves first, learn these. They help in almost every chat.

Move Why it is in the starter set
3.1 Goal vs. proposed solution Fixes the most common prompt mistake.
1.5 Interview me For ideas that are still unclear in your head.
6.1 First principles For building things the way they should be.
2.1 Anchoring Explains why the agent copies your bad ideas.
3.5 Constraint (hard vs. soft) Stops impossible suggestions.
3.6 Non-goal Stops the agent from doing extra work.
2.8 Sycophancy Gets honest answers, not polite ones.
8.4 Pre-mortem Finds problems before you build.
14.6 Five Whys Finds the real cause of a failure.
12.4 Acceptance criteria Makes "finished" clear.
13.6 Inspect before changing Stops the agent from editing code blindly.
15.1 Evidence (not claims) Stops fake "done".

Contents#

Part 1: Your own mind

  • Subject 1: Metacognition (know your own mind)
  • Subject 2: Thinking traps (biases)

Part 2: Understanding the problem

  • Subject 3: Problem framing
  • Subject 4: Shared meaning

Part 3: Finding solutions

  • Subject 5: Generating ideas
  • Subject 6: Designing from scratch
  • Subject 7: Systems thinking

Part 4: Choosing

  • Subject 8: Testing your thinking
  • Subject 9: Decisions under uncertainty
  • Subject 10: Rules of thumb

Part 5: Doing the work

  • Subject 11: Working with your agent
  • Subject 12: Giving clear tasks
  • Subject 13: Changing code safely

Part 6: Checking and learning

  • Subject 14: Diagnosis
  • Subject 15: Verifying work
  • Subject 16: Learning loops

Part 7: Playbooks

Part 8: Cheat sheets


Part 1: Your own mind#

Before you explain anything to an agent, your own thinking must be clear and fair. Part 1 is about the thinker: you.


Subject 1: Metacognition#

Knowing what is in your own mind, and what is not.

Meta = about. Cognition = thinking. So metacognition = thinking about your own thinking.

Why this subject comes first: sometimes you cannot explain an idea because the idea is not clear in your own head yet. Then no prompt can be good. The problem is not your English or your writing. The problem is that the thinking is not finished. This subject gives you tools to finish the thinking, often with the agent's help.

6 moves: Know / think / don't know · Confidence level · Explain it simply · Thinking by writing · Interview me · Notice confusion


1.1 Know / think / don't know#

In one line: Sort what you believe into three boxes: I know, I think, I don't know.

The idea. When we explain a problem, we mix facts, guesses, and unknowns in one paragraph. The agent treats all of it as fact. When you sort them, the agent knows what to trust, what to check, and what to find out.

There is also a hidden fourth box: things you don't know that you don't know. You cannot fill this box yourself. But you can ask the agent to help.

How to do it:

  1. Write three headings: I know, I think, I don't know.
  2. Put each belief under one heading. "I know" needs proof (data, a test, something you saw).
  3. Ask the agent: "What might be in the fourth box?"

Example:

  • ❌ "Students stop using the app because the questions are too hard."
  • ✅ "I know: 60% of students stop after their first quiz (from analytics). I think: the questions are too hard. I don't know: if they come back later. What important things might I not even know to ask?"

Say this:

"Here is what I know, what I think, and what I don't know: [...]. What might I not even know to ask about?"

Careful: Everything in the "I think" box is an assumption (see 3.8). This move is the fastest way to find your assumptions.


1.2 Confidence level#

In one line: Say how sure you are, with a number or a simple word.

The idea. "The problem is the cache" and "maybe it is the cache?" look almost the same in a chat. A number tells the agent how much weight to give your words. Also ask the agent for its confidence. Agents sound sure even when they are guessing.

How to do it:

  1. Next to important statements, add how sure you are: "(90% sure)" or "(only a guess)".
  2. Ask the agent: "How sure are you, and what would make you more sure?"

Example:

  • ❌ "The slow page is caused by the images."
  • ✅ "I am about 70% sure the slow page is caused by the images. How sure are you about your answer? What would you check to be more sure?"

Say this:

"How confident are you in this, from 0 to 100%? What would change your mind?"

Careful: The agent's numbers are rough, not science. Use them to find weak spots, not as truth.


1.3 Explain it simply (the Feynman test)#

In one line: Explain your idea in very simple words, as if to a 12-year-old. The place where you get stuck is the place you do not understand yet.

The idea. Richard Feynman was a famous physicist. He believed: if you cannot explain something simply, you do not fully understand it. Difficult words can hide holes in your thinking. Simple words show the holes.

How to do it:

  1. Write your idea in about 5 simple sentences. No technical words.
  2. Mark the places where you got stuck, or where you wrote words like "somehow" or "it just works".
  3. Ask the agent to question you about those places.

Example:

  • You write: "My topics feature puts each question into a topic. Somehow it knows the right topic."
  • The word "somehow" is the hole. How exactly is a topic chosen? By a person? By the AI? By keywords? Now you know what to think about.

Say this:

"Here is my idea in simple words: [...]. Where is my explanation weak or unclear? Ask me about those parts."

Careful: Simple does not mean incomplete. Keep the important details. Remove only the difficult words.


1.4 Thinking by writing#

In one line: Write your messy thoughts down before you ask the agent. Writing makes thinking clear.

The idea. In your head, an idea feels complete. On paper, the gaps appear. Programmers have a famous trick called rubber duck debugging: they explain their code, line by line, to a toy duck. Very often they find the bug themselves, halfway through explaining. Writing works the same way.

How to do it:

  1. Brain dump: write everything about the problem for 5 minutes. No order, no rules.
  2. Read it again.
  3. Mark the important parts: the goal, the problem, the limits, the open questions.
  4. Now send it to the agent. Or send the messy dump and ask the agent to organize it.

Example:

  • ❌ Sending a 3-page messy text and asking: "What should I do?"
  • ✅ "Here is a messy brain dump about my idea. Do not solve anything yet. Organize it into: goal, problem, facts, guesses, and open questions."

Say this:

"This is a brain dump. Do not solve it yet. Organize it into goal, problem, facts, guesses, and open questions."

Careful: Do not ask for a solution in the same message as a long brain dump. The agent will pick random parts and solve the wrong thing.


1.5 Interview me#

In one line: Ask the agent to ask you questions, one at a time, until your idea is clear.

The idea. When an idea is fuzzy, you cannot write a good prompt. So switch roles. The agent asks, and you answer. Good questions pull the idea out of your head, step by step. This is the best move for moments when you think: "I know what I want, but I cannot explain it."

How to do it:

  1. Describe your rough idea in 2 or 3 sentences. It is fine if it is unclear.
  2. Ask the agent for one question at a time. Ten questions at once is too many.
  3. After about 5 to 10 answers, ask the agent to write a summary of your idea.
  4. Correct the summary. Now you have a clear description.

Example:

  • ❌ "I want a toolkit for thinking, but it's not normal vocabulary, it's something different, you know?"
  • ✅ "I have a fuzzy idea for a thinking toolkit for working with AI agents. I cannot explain it well yet. Interview me. Ask one question at a time. When you understand it, write a clear summary and I will correct it."

Say this:

"Interview me about this. Ask one question at a time. When you understand my idea, summarize it, and I will correct it."

Careful: This is not the same as "What information are you missing?" (12.2). That is one list at the start of a clear task. Interview me is a conversation for an unclear idea. Stop when the idea is clear. Do not let it continue forever.


1.6 Notice confusion#

In one line: When something feels strange or "does not fit", stop and look at it. Confusion is a signal.

The idea. We often ignore small surprises: "Strange, the number is different... anyway." But surprises often point to the real problem, or to a wrong belief. Agents do the same. They see a strange warning and continue.

How to do it:

  1. When you feel "huh?", write down exactly what surprised you.
  2. Ask: "What would have to be true for this to make sense?"
  3. Tell the agent to report surprises instead of ignoring them.

Example:

  • ❌ "The dashboard shows 412 questions, the database has 398. Whatever. Continue."
  • ✅ "Strange: the dashboard shows 412 questions, but the database has 398. Before we continue, explain this difference. Also, while you work, tell me anything surprising you notice."

Say this:

"If you see anything surprising or anything that does not fit, stop and tell me. Do not ignore it."

Careful: Not every surprise matters. Focus on surprises that are close to the problem you are working on.


✏️ Practice: Subject 1#

Take one idea that is not clear in your head right now.

  1. Write a 5-minute brain dump (1.4).
  2. Sort it into I know / I think / I don't know (1.1).
  3. Open a new chat and use Interview me (1.5). Compare the final summary with your first brain dump.

Subject 2: Thinking traps (cognitive biases)#

Natural habits of the mind that push thinking in a wrong direction, without you noticing.

A bias is a habit of the mind that bends your thinking in one direction. Everyone has biases, even very smart people. You cannot remove them. But when you know their names, you can catch them.

Agents have their own traps too. So this subject has two sections:

  • Your traps: 2.1 to 2.7 (the agent also has many of these)
  • The agent's special traps: 2.8 to 2.10

10 moves: Anchoring · Confirmation bias · Sunk cost trap · Status quo bias · IKEA effect · Availability trap · Planning fallacy · Sycophancy · Typical-answer default · Context drift


2.1 Anchoring#

In one line: The first idea or number you see pulls all later thinking toward it.

The idea. Think of a ship's anchor. The ship can move, but not far. If a client says "a website should cost about $300", every later price feels "high" or "low" compared to 300.

For agents, anchoring is very strong. Whatever is in the chat (your solution, your code, your first idea) becomes the anchor. If you say "improve my solution", you get a slightly better version of the same solution, even if the whole idea is wrong. This is why "first principles" helped you: it breaks the anchor.

How to do it:

  1. Notice what the anchor is: your first idea, your existing code, a number.
  2. To break the anchor: describe the goal instead of your solution, or ask for the agent's ideas before you show yours.
  3. Then compare.

Example:

  • ❌ "Here is my topic system code. How can I make it better?"
  • ✅ "Do not look at my code yet. Goal: every PPSC question must belong to the right topic. How would you design this? After that, I will show you my version and we compare."

Say this:

"Before you see my solution, propose your own approach. Then we compare."

Careful: Sometimes you want the anchor. A small bug fix should stay inside the existing code. Break the anchor only when the existing thing might be wrong.


2.2 Confirmation bias#

In one line: You notice proof that agrees with you, and you miss proof that does not.

The idea. If you believe "students love the timed mode", you remember the 3 students who said yes. You forget the 10 who never used it. Agents do the same. If you ask "Is X the cause?", the agent searches for reasons to say yes.

How to do it:

  1. Write your belief.
  2. Ask: "If I am wrong, what would I expect to see?"
  3. Look for that.

Example:

  • ❌ "Confirm that the cache is the problem."
  • ✅ "I think the cache is the problem. Look for evidence that it is not."

Say this:

"Look for evidence against my idea, not only evidence for it."

Careful: The name of the trap is confirmation bias. The cure is falsification (8.3).


2.3 Sunk cost trap#

In one line: Continuing on a bad path only because you already spent time or money on it.

The idea. Sunk = sank, gone. The time you already spent is gone, whatever you choose now. The only real question is: from today, what is the best path? People keep bad code because "I worked 3 weeks on it". This trap is very common when a solution "did not turn out good".

How to do it:

  1. Imagine someone else built it, and you arrived today.
  2. Ask: "Would I choose this path today, if I were starting now?"
  3. Judge only the future cost and the future value.

Example:

  • ❌ "I spent 3 weeks on this quiz engine, so help me fix it."
  • ✅ "I spent 3 weeks on this quiz engine. Ignore that. If a new developer arrived today, would they keep it or replace it? Compare only future cost and future value."

Say this:

"Ignore the time I already spent. From today, what is the best choice?"

Careful: This does not mean "always throw away old work". Old work often has value. See Salvage audit (6.5) and Chesterton's fence (6.2).


2.4 Status quo bias#

In one line: Preferring things to stay the same, only because change feels risky.

The idea. Status quo = the current state. "We always did it this way" is not a reason. Change has real costs, yes. But "no change" also has costs. They are just hidden. The trap is giving "no change" a free pass.

How to do it:

  1. Add "keep it as it is" to your list of options.
  2. Write its costs too (lost time, lost clients, growing problems).
  3. Compare all options fairly.

Example:

  • ❌ "Should I move my client sites to a new CMS?" (You secretly feel "no".)
  • ✅ "Compare three options, including 'keep the current setup'. For each one, list the costs for the next 6 months, including the cost of not changing."

Say this:

"Treat 'do nothing' as an option with its own costs. Compare it fairly."

Careful: Close to the sunk cost trap, but different. Sunk cost = looking at past effort. Status quo = fear of change.


2.5 IKEA effect#

In one line: You value the thing you built more than it deserves.

The idea. Researchers found that people value furniture they built themselves more than the same furniture built by others. The same happens with code, designs, and plans. Your solution feels better because it is yours. The agent also defends code that it wrote earlier in the same chat.

How to do it:

  1. Present your work as someone else's: "A colleague made this."
  2. Ask for a review in a fresh chat (see 15.5).

Example:

  • ❌ "Here is my onboarding flow. It's good, right?"
  • ✅ "A developer I hired built this onboarding flow. Review it honestly. What would you change?"

Say this:

"Someone else made this. Review it honestly."

Careful: Pride in your work is fine. Just do not let it make the decision for you.


2.6 Availability trap#

In one line: Believing something is common or important only because it is easy to remember.

The idea. One angry client message is fresh and loud, so it feels like "all clients are unhappy". A bug from yesterday feels like the biggest problem. Easy to remember is not the same as true.

How to do it:

  1. Ask: "Is this based on one memorable event, or on real numbers?"
  2. Count instead of remembering.

Example:

  • ❌ "Students hate the timer. Remove it."
  • ✅ "One student complained about the timer. Before I change it: how can I check how many students actually have this problem?"

Say this:

"Is this one loud example or a real pattern? How can I count it?"

Careful: One single event can still matter if it is serious. For example, one security problem is enough to act.


2.7 Planning fallacy#

In one line: People almost always think a task will take less time than it really does.

The idea. Fallacy = a mistake in thinking. We plan for the best case: no bugs, no interruptions, no waiting for the client. Real life has surprises. Agents do this too: "This is a quick change" is often not quick. See also Hofstadter's law (10.5) and Base rate (9.5).

How to do it:

  1. Look at how long similar past tasks really took.
  2. Break the task into steps (12.7). Hidden work appears.
  3. Add a buffer (extra time), often 1.5× to 2×.

Example:

  • ❌ "How long will it take to add payments? A few days, right?"
  • ✅ "List every step to add payments, including testing, edge cases, and deployment. Add the hidden work people usually forget. Then estimate."

Say this:

"What hidden work am I forgetting? Estimate with that included."

Careful: Use this for planning and for promises to clients. Do not let it stop you from starting.


2.8 Sycophancy (the agent wants to please you)#

In one line: The agent agrees with you or praises you only to please you, not because you are right.

The idea. A sycophant (say: SIK-uh-fant) is a person who praises too much to be liked. AI models learned from people who liked friendly, agreeable answers. So they lean toward "yes". The agent also reads your opinion from your words. If you write "I think X is great, right?", it hears the answer you want.

The warning sign: you disagree without new facts, and the agent suddenly changes its answer.

Why it matters: if the agent only agrees, nothing protects you from your own mistakes. A weak plan feels strong. You find the problem later, when it costs more.

6 tricks to get honest answers:

  1. Hide your opinion. Ask "Compare A and B", not "A is best, right?"
  2. Give a critic role: "Act as a strict senior developer. Find problems."
  3. Make it someone else's idea: "A colleague proposed this plan."
  4. Ask for the case against: "Give the 3 biggest reasons this will fail."
  5. Test its backbone: "If I disagree without new facts, keep your answer."
  6. Ask for honest, not negative: "If it is good, say so and explain why."

Example:

  • ❌ "I think storing student scores in localStorage is great. Right?"
  • ✅ "A colleague proposed storing student scores in localStorage for a PPSC practice platform. Review it as a strict senior developer. List the 3 biggest risks. If the plan is fine, say so and explain why."

Say this:

"Be honest, not agreeable. Find the real problems. If it is good, say why."

Careful: Agreement is fine when the agent gives reasons or evidence. Also, do not ask for harsh criticism all the time. Then the agent may invent problems just to obey you. That is the same mistake in the other direction. This is why trick 6 matters.


2.9 The typical-answer default#

In one line: The agent gives the most common answer, not the best answer for your situation.

The idea. The agent learned from millions of examples. When you give little context, it gives the "average" answer: a popular library, a common structure, standard advice. Average answers fit average situations. But your situation is specific. For example: a solo developer, local payment methods, 200 students, a small budget.

How to do it:

  1. Give your specific facts: scale (3.7), constraints (3.5), your skills.
  2. Ask: "Is this the standard answer? Does it fit my situation?"
  3. Ask for one option that is not the obvious one.

Example:

  • ❌ "What is the best way to build user accounts?"
  • ✅ "Is your answer the standard textbook answer? I am a solo developer, with 200 students and almost no budget. What would you suggest specifically for this?"

Say this:

"Is this the typical answer, or the best answer for my situation? Explain why it fits me."

Careful: The typical answer is often good. It is typical because it works (see 5.5 Boring solution and 10.6 Lindy effect). The problem is only when it does not fit you.


2.10 Context drift#

In one line: In a long chat, the agent slowly forgets or mixes up earlier instructions.

The idea. An agent has a limited working memory, called the context window. In a long chat, early rules get weaker, old wrong ideas stay in the chat, and quality drops.

Signs of drift:

  • It repeats a mistake you already corrected.
  • It forgets a constraint you gave at the start.
  • It goes in circles.

How to do it:

  1. Notice the signs.
  2. Ask for a summary of all decisions so far.
  3. Start a fresh chat with that summary (see 11.6).
  4. Keep your key rules in a file (project notes, glossary) that you paste or the agent reads every time.

Example:

  • ❌ Correcting the same mistake for the fourth time in the same chat.
  • ✅ "Summarize everything we decided in this chat: goal, decisions, constraints, and open questions. I will start a new chat with this summary."

Say this:

"Summarize our decisions and open questions, so I can continue in a new chat."

Careful: Not every mistake is drift. Sometimes the instruction was unclear. Check your instruction first.


✏️ Practice: Subject 2#

Think of the last solution you built that did not work well.

  1. Which traps were active? Check: anchoring, sunk cost, IKEA effect, confirmation bias.
  2. Write one sentence for each trap: "This trap made me ___."
  3. Write the one prompt sentence that would have protected you.

Part 2: Understanding the problem#

A perfect solution to the wrong problem is useless. Part 2 makes sure you and the agent understand the same problem, in the same words.


Subject 3: Problem framing#

Deciding what the problem really is, before you try to solve it.

Framing = putting a frame around the problem: what is inside, what is outside, what matters. A doctor finds the illness before giving medicine. In the same way, you find the real problem before asking for a solution.

Most wasted work with agents starts here. The agent solved the problem you wrote, not the problem you had.

8 moves: Goal vs. proposed solution · XY problem · Problem statement · Job to be done · Constraint (hard vs. soft) · Non-goal · Scale · Assumption


3.1 Goal vs. proposed solution#

In one line: Separate WHAT you want to achieve from HOW you thought to do it.

The idea. We usually ask for our solution: "Add a filter dropdown." But the real goal is: "Students should find questions on their weak topics fast."

When you give only the solution, the agent builds it, even if a better way exists. When you also give the goal, the agent can suggest better ways. The goal also lets you judge whether your solution is good.

How to do it:

  1. Write your request.
  2. Ask yourself: "Why do I want this?" The answer is closer to the goal. Ask "why" again if needed.
  3. Give both: the goal, and your idea. Say that your idea is optional.

Example:

  • ❌ "Add a dropdown to filter questions by subject."
  • ✅ "Goal: students should quickly find questions in their weak subjects. My idea: a dropdown filter. If there is a better way to reach the goal, tell me."

Say this:

"My goal is [...]. My proposed solution is [...]. If there is a better way to reach the goal, suggest it."

Careful: For small, clear tasks (change a color, fix a typo), just give the task.


3.2 The XY problem#

In one line: You ask about your attempted solution (Y), not about your real problem (X).

The idea. This is famous in programming forums. You want X. You think Y will solve it. Y does not work. So you ask: "How do I fix Y?" Everyone helps you with Y. But Y was the wrong path from the start.

A classic example: someone asks "How do I get the last 3 letters of a file name?" The real problem is "How do I get the file type?" But file types can have 4 letters (.jpeg), so the Y approach was wrong.

How to do it:

  1. When you are stuck on "How do I...", stop.
  2. Add: "What I am really trying to do is..."
  3. Ask: "Is my approach the right one?"

Example:

  • ❌ "How do I force Next.js to re-render the whole page every 5 seconds?"
  • ✅ "How do I re-render the page every 5 seconds? What I am really trying to do: show the live number of students online. Is re-rendering the right approach?"

Say this:

"What I am really trying to do is [X]. My current approach is [Y]. Is Y the right path?"

Careful: Very close to 3.1. Use 3.1 when planning. Use XY when you are already stuck on your approach.


3.3 Problem statement#

In one line: A few sentences that say who has the problem, what it is, why it matters, and how you will know it is solved.

The idea. A good problem statement is the foundation for everything after it. If you cannot write one part of it, you found something you still need to think about.

Template:

[Who] needs [what] because [why]. Today, [current situation]. It is solved when [something we can check].

How to do it:

  1. Fill in the template.
  2. If one part is empty, think about it, or use Interview me (1.5).
  3. Put the problem statement at the top of your prompt.

Example:

  • ❌ "I want to improve practice on my PPSC app."
  • ✅ "Students preparing in the last 2 weeks before the exam need to practice their weakest topics, because time is short. Today, they practice random papers. It is solved when a student can start a weak-topic quiz in 2 taps."

Say this:

"Help me write a problem statement: who, what, why, the current situation, and how we know it is solved. Ask me for any missing part."

Careful: A problem statement is not a full plan. Keep it to 3 to 5 sentences.


3.4 Job to be done#

In one line: People do not want your product. They want progress in their life. Ask: what "job" do they "hire" your product to do?

The idea. This idea comes from Professor Clayton Christensen. A famous example: a fast-food company found that many people bought milkshakes in the morning. Not for the taste. The milkshake did a "job": it kept them busy and full during a long, boring drive to work. Knowing the job changed what the company should improve.

  • A PPSC student does not want "an MCQ app". The job is: "pass the exam and feel ready, not anxious".
  • A dental clinic does not want "a website". The job is: "get more patients to book appointments".

How to do it:

  1. Complete this sentence: "When [situation], I want to [motivation], so I can [result]."
  2. Check each feature: does it help this job or not?

Example:

  • ❌ "Which features should my PPSC app have?"
  • ✅ "Job: when I have 20 free minutes on my phone, I want to practice the questions I am most likely to get wrong, so I can feel ready for the exam. Which features help this job, and which ones do not?"

Say this:

"What job is the user hiring this for? Write it as: when [situation], I want to [motivation], so I can [result]."

Careful: Use this for products, features, and marketing. Not for technical tasks like "fix the build".


3.5 Constraint (hard vs. soft)#

In one line: A constraint is a limit. A hard constraint can never be broken. A soft constraint is a wish that can bend.

The idea. The agent does not know your limits, so it guesses. It may suggest a paid service or a new framework you cannot use. When you give limits, it removes bad options early. When you mark them hard or soft, it knows what it may bend when two things conflict.

  • Hard = fixed. If it is broken, the solution is useless.
  • Soft = preferred. You can trade it away (give it up to get something better).

Quick test: "If this limit is broken, is the solution useless?" Yes = hard. No = soft.

How to do it:

  1. List your limits: time, money, tools, rules, skills.
  2. Mark each one hard or soft.
  3. Tell the agent what to do when they conflict.

Example:

  • ❌ "Add payments to my PPSC platform."
  • ✅ "Add payments to my PPSC platform. Hard: must work with local payment methods like JazzCash or Easypaisa, and must stay on Next.js and Vercel. Soft: low monthly cost, finish in 2 weeks."

Say this:

"Hard constraints: [...]. Soft constraints: [...]. If they conflict, keep the hard ones and tell me what you gave up."

Careful: A goal is what you want to reach. A constraint limits how you may reach it. Also, do not mark everything as hard. Then the agent has no room to find a good answer.


3.6 Non-goal#

In one line: Something you are NOT trying to do in this task, even if it looks related.

The idea. Agents like to be "helpful". They fix extra things, add features, and refactor (rewrite the structure of) files you did not mention. A non-goal puts a fence around the task. The result is smaller, safer, and easier to review.

How to do it:

  1. Think: "What will the agent be tempted to do here?"
  2. Write 2 or 3 of those things as non-goals.
  3. Tell the agent to ask before doing any of them.

Example:

  • ❌ "Improve the results page." (The agent may redesign the page, add charts, and change the database.)
  • ✅ "Improve the loading speed of the results page. Non-goals: do not change the design, do not add features, do not change the database."

Say this:

"Non-goals (do not do these): [...]. If you think one is needed, ask me first."

Careful: A constraint limits HOW you do the work. A non-goal limits WHAT work is done. Keep the list short: 2 or 3 items.


3.7 Scale#

In one line: How big the problem is, in numbers: users, orders, questions, requests.

The idea. The best solution for 200 students is different from the best solution for 200,000. Without numbers, the agent picks something "average". Or it builds something far too big and complex for your real size. One number prevents this.

How to do it:

  1. Give the size today.
  2. Give the size later (for example, in 12 months).
  3. Use real numbers. A rough guess is fine. Say it is a guess.

Example:

  • ❌ "What is the best way to store quiz results?"
  • ✅ "What is the best way to store quiz results? Scale: today 200 students, each doing about 20 quizzes a month. In one year, maybe 5,000 students. Only the student reads their own results."

Say this:

"Scale: now about [number], in 12 months about [number]. Choose a solution that fits this size, not a bigger one."

Careful: Scale is the numbers. Scalability is the ability of a system to keep working when the numbers grow. Skip this move when size does not matter (a text change, a color).


3.8 Assumption#

In one line: Something you believe is true, but you have not checked.

The idea. Many bad answers come from one wrong, hidden assumption. There are two kinds:

  • Your assumptions (in your head).
  • The agent's assumptions (silent guesses it made).

An assumption is dangerous when your solution depends on it and nobody checked it. When you write it down, you and the agent can check it.

How to do it:

  1. List what you believe but have not checked. (The "I think" box from 1.1.)
  2. Ask the agent to list its assumptions too.
  3. Check the important ones before building.

Example:

  • ❌ "Make the quiz page faster."
  • ✅ "Make the quiz page faster. I assume the slow part is loading questions from the database. I have not measured it. Check this first, before you change any code."

Say this:

"My assumptions are: [...]. I have not checked them. Also list the assumptions you are making."

Careful: A fact is checked. An assumption is not. List only assumptions where being wrong would change the solution. Not obvious things like "the internet works". To find the most dangerous one, use Weakest assumption (8.1).


✏️ Practice: Subject 3#

Pick one feature you plan to build.

  1. Write a problem statement (3.3) and a job to be done (3.4).
  2. Add 2 hard constraints, 1 soft constraint, and 2 non-goals.
  3. Write your scale in numbers, and your top 2 assumptions.

You now have the top half of a very strong prompt.


Subject 4: Shared meaning#

Making sure a word means the same thing to you and to the agent.

Words in your head have an exact meaning. The same words, for the agent, may have a different meaning. The agent usually does not ask. It picks the most common meaning, not yours. This subject makes sure you are both talking about the same thing.

5 moves: Ambiguity · Glossary · Operational definition · Example and counter-example · One name per thing


4.1 Ambiguity#

In one line: A word or sentence is ambiguous when it can mean more than one thing.

The idea. Ambi- = both ways. You mean one thing; the agent picks another. Hidden ambiguity is the worst kind, because your meaning feels obvious to you, so you do not see the problem.

Risky words: test, user, session, result, page, fast, simple, secure.

Sentences can be ambiguous too. "Show students and teachers with results." Who has results? Only the teachers, or both?

How to do it:

  1. Before a big task, ask the agent to find words in your message that have more than one meaning.
  2. Choose the meaning you want.
  3. Write it clearly.

Example:

  • ❌ "Add a test page to the PPSC platform." ("Test" can be a practice quiz, an admin page for trying things, or code tests.)
  • ✅ "Add a test page. By 'test' I mean a timed practice quiz for students, not a code test. Before you start, list any words in my message that could mean more than one thing."

Say this:

"Which words in my message could mean more than one thing? List them with their possible meanings. Ask me before you guess."

Careful: Vague is different from ambiguous. A vague word is not exact enough ("fast"). It needs a number (see 4.3). An ambiguous word has two exact meanings ("test"). It needs a choice.


4.2 Glossary#

In one line: A short list of your key words, with their exact meaning. Write it once and reuse it in every chat.

The idea. Gloss = a short explanation. Over time, words slowly change meaning. In chat 1, "result" means the score. In chat 3, it means the exam result. A glossary keeps the same meaning in all chats. The agent also uses your words in code names, so your code stays easy to read.

How to do it:

  1. Pick 5 to 10 key words in your project.
  2. For each word, write one sentence of meaning, and (if useful) what it is NOT.
  3. Save it in a notes or project file. Paste it at the top of a new chat, or let the agent read it.

Example:

  • ❌ "Show the user's result after the session."
  • ✅ "Glossary: Student = a person who practices. Admin = me. Attempt = one full try of a quiz. Score = the points from one attempt. Result page = the page that shows the score of one attempt. Now: show the score on the result page after each attempt."

Say this:

"Use these words exactly as defined: [word = meaning]. If you need a new word, ask me first."

Careful: Your glossary gives your meaning, for this project. It is not a dictionary. Keep it short. A glossary with 50 words will not be used.


4.3 Operational definition#

In one line: Turn a vague word into something you can measure or check.

The idea. "Fast" means different things to different people. The agent does not know your level. When you define a word by a measure, the agent can check it, and so can you.

Formula: word = a test + a number + a condition.

Example: "fast" = "the page loads in under 2 seconds, on a phone with a slow connection".

Words that need this: fast, simple, clean, easy, secure, good, modern, professional.

How to do it:

  1. Find the vague words in your request.
  2. For each one, ask: "How would I check this?"
  3. Write the check, with a number.

Example:

  • ❌ "Make the quiz page fast and simple."
  • ✅ "Fast = the first question appears within 2 seconds on a slow mobile connection. Simple = a student can start a quiz in 2 taps from the home page."

Say this:

"By '[word]' I mean: [something I can measure or check]."

Careful: Acceptance criteria (12.4) check a whole feature. An operational definition fixes the meaning of one word. You can use that word inside your criteria. If you are exploring and "will know it when you see it", do not force a number. Use examples instead (4.4).


4.4 Example and counter-example#

In one line: Show one thing that IS what you mean. Also show one thing that is NOT.

The idea. An example shows the middle of your idea. A counter-example (something that looks close, but does not fit) shows the edge. Together, they draw the border. With only one example, the agent copies it too closely, or guesses where the border is. This works very well for style, tone, and design.

How to do it:

  1. Give 1 or 2 examples of what you want.
  2. Give 1 or 2 examples that are close, but wrong.
  3. Say why each wrong example is wrong.

Example:

  • ❌ "Write the answer explanations in a friendly style."
  • ✅ "Friendly style. Like this: 'Not quite! Look again at the word EXCEPT in the question.' Not like this: 'Incorrect. The answer is B.' (too cold). Not like this: 'Oops!!! So close!!! 😂😂' (too playful)."

Say this:

"Example of what I mean: [...]. Example of what I do NOT mean: [...], because [...]."

Careful: When you want original ideas, the agent may copy your example. Then add: "Match the style only. Do not copy the words." This is different from Example-driven spec (12.6), which uses input → output pairs for rules and code.


4.5 One name per thing#

In one line: Use the same word for the same thing, every time.

The idea. For people, different words for one thing are fine. For an agent, a new word can look like a new thing. If you say "quiz", "test", "exam", and "paper" for the same thing, the agent may build a Quiz component and a Test component that do the same job. The opposite problem also exists: one word used for two different things.

How to do it:

  1. Choose one name for each important thing.
  2. Use it everywhere: in prompts, code, database, and on the screen.
  3. Ask the agent to tell you when the code uses two names for one thing.

Example:

  • ❌ "Add a timer to the test. Save the exam score. Show the paper result." (One thing or three?)
  • ✅ "I always call this an 'attempt'. Add a timer to the attempt. Save the attempt's score. Show the attempt's result. If you think these are different things, tell me."

Say this:

"I will always call this '[name]'. If the code uses two names for one thing, tell me."

Careful: The glossary (4.2) defines your words. This move is the habit of using them the same way every time. You need both. This rule is for instructions and code, not for marketing text, where variety sounds natural.


✏️ Practice: Subject 4#

  1. Write a glossary for your PPSC platform with 5 words (for example: student, attempt, score, question, paper).
  2. Add one operational definition for "fast" or "simple".
  3. Write one example and one counter-example for the tone of your answer explanations.

Part 3: Finding solutions#

Now you know the real problem. Part 3 helps you find many possible solutions, design the right one from the ground up, and see how it affects everything around it.


Subject 5: Generating ideas#

Creating many good options before you choose one.

Your first idea usually comes from habit. The agent's first idea is usually the most common one (2.9). This subject helps you find options you would never see otherwise.

The golden rule: first collect ideas, then choose (Part 4). Do not judge ideas while you are still creating them.

6 moves: Expanding the solution space · Inversion · Reframing · Removing a constraint · The boring solution · Borrow from another field


5.1 Expanding the solution space#

In one line: Before you choose, list many different ways to solve the problem, not only the first one.

The idea. The solution space = all the possible answers. Expanding = making that space bigger. If you ask for very different options, you see answers you did not know about. Sometimes the best answer was not on your first list at all.

How to do it:

  1. Describe the goal, not your solution (3.1).
  2. Ask for 4 to 6 options that are really different, not small variations.
  3. Ask for at least one unusual option.
  4. Do not choose yet.

Example:

  • ❌ "How do I build a quiz page for PPSC students?" (This already decides "quiz page".)
  • ✅ "Students need to practice PPSC past-paper MCQs. Give me 5 very different ways to deliver this. A web page can be one, but not all. Do not pick one yet."

Say this:

"Give me [5] really different approaches, including unusual ones. Do not recommend one yet."

Careful: Expanding adds options. Choosing (Part 4) removes them. Do them in this order. Skip this move when a hard constraint already decides the way.


5.2 Inversion#

In one line: Turn the question upside down. Ask "How could I make sure I fail?" Then avoid those things.

The idea. Invert = flip to the opposite. For our mind, failure is easier to imagine than success. When we think negatively on purpose, we find hidden risks and bad habits that "How do I succeed?" never shows.

How to do it:

  1. Write your goal.
  2. Write the opposite goal.
  3. List ways to reach the opposite goal.
  4. Turn each one into a rule: "Never do this."

Example:

  • ❌ "How do I make students love my PPSC platform?"
  • ✅ "List 10 ways I could guarantee that students quit my PPSC platform in the first week. Then turn each one into a rule I must follow."

Say this:

"Invert this: how could I guarantee failure? List the ways, then turn each one into a rule to avoid."

Careful: Not the same as Falsification (8.3). Falsification tests one idea to prove it wrong. Inversion flips the whole goal to find what to avoid. Avoid this move when you feel stressed. A long list of failures can feel heavy.


5.3 Reframing#

In one line: Describe the same problem in a different way, so you see new solutions.

The idea. Frame = the window you look through. Reframe = change the window. Every problem sentence already points toward a type of solution. "How do I get more students to buy?" points to marketing. "How do I make students come back every day?" points to product design. A new frame gives new answers.

Common ways to reframe:

  • Change who the problem is for (student → parent → teacher).
  • Change the real goal behind it (sell more → help students pass).
  • Change the time (today → in one year).
  • Change the size (all students → only the most serious 10%).

How to do it:

  1. Write the problem as one question.
  2. Ask for 3 different frames.
  3. For each frame, find one solution the original question would not show.

Example:

  • ❌ "How do I get more students to buy my PPSC subscription?"
  • ✅ "Reframe this problem 3 ways: 'How do I get more students to buy my PPSC subscription?' For each reframe, give one new idea the original question would not show."

Say this:

"Reframe this problem 3 different ways. For each one, give a solution the original question would not show."

Careful: Not the same as Restate (12.1). Restating keeps the same meaning, to check understanding. Reframing changes the angle on purpose. Skip it for clear bugs.


5.4 Removing a constraint#

In one line: Pick one limit and pretend it does not exist. See what solution appears. Then bring back what you can.

The idea. Many "constraints" are really assumptions or soft wishes. You treat them as walls, but they are not. Also, a solution with no limits shows you the ideal direction. Often you can reach 70% of the ideal in a cheaper way.

How to do it:

  1. Pick one constraint.
  2. Imagine it is gone (only for thinking).
  3. Ask for the ideal solution.
  4. Ask: "Was this really a hard constraint? Which part of the ideal can I still keep?"

Example:

  • ❌ "I have no money for a big server. How do I support 5,000 students?"
  • ✅ "Constraint: almost no server budget. Pretend I have unlimited budget. What is the best design? Then tell me which parts I can still get with free plans or simple tools."

Say this:

"Ignore the constraint [X] for a moment. What is the ideal solution? Then tell me which part I can still keep."

Careful: This is only a thinking step. At the end, your real hard constraints still apply. Never "imagine away" law, payment rules, or security.


5.5 The boring solution#

In one line: The simplest, most common, proven way to solve the problem. The opposite of a clever idea.

The idea. Boring here is a good thing: well known, well tested, easy to understand, easy to fix later. Agents love to over-engineer (build something more complex than needed). More code = more bugs = more work for you. The boring solution is your baseline (starting line). Any clever option must be clearly better than it.

How to do it:

  1. Ask for the boring solution first.
  2. Ask what you lose by not choosing a smarter one.
  3. Choose the clever option only if the loss is big.

Example:

  • ❌ "Build a smart AI system that recommends questions to each student."
  • ✅ "What is the boring solution for helping students practice weak topics? Use only tools I already use. For example: a list of questions they got wrong most often. Then tell me what we lose by not building something smarter."

Say this:

"What is the boring solution here? Use simple, proven tools. Tell me what we lose by not going fancier."

Careful: Not the same as Minimal change (13.5). Boring solution = a simple approach. Minimal change = a small edit to code. Skip this move when you are building something to learn a new tool.


5.6 Borrow from another field (analogy)#

In one line: Ask how a different field or industry already solved a similar problem.

The idea. Most problems were already solved somewhere else. Language-learning apps solved "remembering facts for a long time" with spaced repetition (showing something again just before you forget it). That idea can help MCQ practice. Banks solved "avoid mistakes before something important" with a confirmation step. That can help quiz submission. Copying a proven idea is faster and safer than inventing a new one.

How to do it:

  1. Describe your problem in general words, without your project details. Example: "Help people remember facts for many weeks."
  2. Ask which fields or products solved this.
  3. Bring the idea back to your project.

Example:

  • ❌ "How can I make students remember answers?"
  • ✅ "My problem in general: students forget what they practiced. Which other fields solved 'remembering over time'? How could I apply their ideas to MCQ practice?"

Say this:

"Describe my problem in general terms. Which other fields or products solved something similar? How could I borrow their solution?"

Careful: An analogy is a starting point, not proof. Check that your situation is really similar before you copy.


✏️ Practice: Subject 5#

Pick one problem in your work (for example: "clients send website content late").

  1. Ask for the boring solution and 4 really different approaches (5.1, 5.5).
  2. Invert it: "How could I make clients send content even later?" (5.2)
  3. Ask which other industry solved "people send things late" (5.6).

Subject 6: Designing from scratch#

Building things the way they should be, not only fixing what already exists.

This is the subject for your main question. When a solution turned out bad, there are two dangers:

  1. Patching forever. You keep fixing the same broken design (anchoring, sunk cost).
  2. Throwing everything away. You rebuild and lose the good parts, and the hidden reasons behind them.

This subject gives a balanced method: think from the ground up, respect what was there for a reason, keep what is good, and grow the new design step by step.

7 moves: First principles · Chesterton's fence · Essential vs. accidental complexity · Gall's law · Salvage audit · Clean-slate comparison · Patch vs. rebuild


6.1 First principles#

In one line: Break the problem down to the basic truths that must be true. Then build up from there, ignoring how it is done today.

The idea. Most thinking is by copying: "Others do it this way" or "My current code does it this way." First principles asks: "What is really necessary here?"

A famous story: someone was told "batteries are expensive, so electric cars will always be expensive." A first-principles thinker asked instead: "What materials are inside a battery, and what do those materials cost?" The answer was much cheaper. The "expensive" belief came from habit, not from basic truths.

For software, the basic truths are questions like:

  • What must the system do for the user?
  • What data must exist?
  • What must never happen? (See Invariant, 13.3.)
  • What are the hard constraints? (3.5)

How to do it:

  1. State the goal, not the solution (3.1).
  2. List the basic truths: needs, facts, hard constraints.
  3. For each part of the current solution, ask: "Is this necessary, or only habit?"
  4. Design the simplest thing that satisfies the truths.
  5. Only then look at the existing solution and compare (6.6).

Example:

  • ❌ "Here is my topics system. Improve it."
  • ✅ "Use first principles. Ignore my current topics system. Goal: every PPSC question appears under the right topic, and students can practice by topic. What must be true for this to work? Design from those truths. After that, we compare with my current system."

Say this:

"Use first principles: ignore the existing solution, find the real goal and the basic truths, and design up from there."

Careful: It is slow and takes effort. Use it for important designs, not for every bug. After first principles, still check Chesterton's fence (6.2). Some old parts may exist for reasons you forgot.


6.2 Chesterton's fence#

In one line: Before you remove something, find out why it was put there.

The idea. A story by the writer G.K. Chesterton. A man finds a fence across a road. He says: "I see no use for this. Remove it." A wiser man answers: "First, go and find out why it was built. When you know the reason, then you may remove it."

Old code often has strange parts that handle a real problem: an edge case, a past bug, a client request. Agents love to delete "unnecessary" code. This move protects you.

How to do it:

  1. For each part you want to remove, ask: "Why might this exist?"
  2. Check: git history, code comments, old messages, the person who wrote it.
  3. If the reason is still valid: keep it, or replace it with something that handles the same problem.
  4. If there is no reason any more: remove it.

Example:

  • ❌ "This check in the score function looks useless. Delete it."
  • ✅ "Before you remove this extra check in the score function, explain why it might exist. What would break without it?"

Say this:

"Before removing anything, explain why it might exist and what could break without it."

Careful: Do not use this to protect everything. If you checked and found no reason, remove it with confidence.


6.3 Essential vs. accidental complexity#

In one line: Some difficulty comes from the problem itself (essential). Some comes from how we built it (accidental). Remove the accidental kind.

The idea. A computer scientist, Fred Brooks, made this famous in 1986.

  • Essential: negative marking of −0.25 for wrong answers. The PPSC exam rules require it. You cannot remove it.
  • Accidental: three different places in the code that each calculate the score. Nobody needed that. We created it.

When you rebuild, you cannot remove essential complexity. But you can remove almost all of the accidental kind. This is often the biggest win of a redesign.

How to do it:

  1. List everything that makes the system hard to work with.
  2. Mark each item E (essential) or A (accidental).
  3. Plan how to remove the A items.

Example:

  • ❌ "My quiz code is too complicated. Simplify it."
  • ✅ "List what makes my quiz system complex. Mark each item as essential (comes from the PPSC rules or real user needs) or accidental (comes from how we built it). How do I remove the accidental parts?"

Say this:

"Separate essential complexity from accidental complexity. Help me remove the accidental parts."

Careful: People often call things accidental when they are essential. For example: "Why do we handle so many edge cases?" Because users really do those things. Check with Chesterton's fence (6.2).


6.4 Gall's law (start simple, then grow)#

In one line: A complex system that works almost always grew from a simple system that worked.

The idea. John Gall studied why big systems fail. He found that a large, complex system designed all at once usually does not work, and is very hard to fix. Working complex systems start small and grow.

This protects your first-principles redesign from becoming a giant rewrite that never finishes.

How to do it:

  1. Find the smallest version that works from start to end (end-to-end).
  2. Make that work.
  3. Add one piece at a time. Keep it working after every piece.

Example:

  • ❌ "Build the full new topics system with all subjects, filters, statistics, and AI tagging."
  • ✅ "Do not build the full redesign. What is the smallest version of the new topics system that works end-to-end, for one subject only? Start there."

Say this:

"What is the simplest version that works end-to-end? Build that first, then we grow it."

Careful: Not the same as Boring solution (5.5): boring = a proven approach. Gall's law = start small and grow. Not the same as Task breakdown (12.7): breakdown is about steps of work; Gall's law is about how the system itself grows.


6.5 Salvage audit#

In one line: Before rebuilding, list which parts of the old solution are worth keeping.

The idea. Salvage = save useful things from a wreck. A failed solution is almost never 100% bad. Usually some parts are good: the data, a component, a design idea, and the lessons you learned. Rebuilding everything wastes good work. Keeping everything keeps the problems.

How to do it:

  1. Sort each part of the old solution into three groups:
    • Keep = works well.
    • Fix = good idea, bad execution.
    • Drop = wrong idea.
  2. Give one reason for each.
  3. Also write a list of lessons learned.

Example:

  • ❌ "My quiz system is bad. Start over."
  • ✅ "Do a salvage audit of my quiz system. Sort each part into Keep, Fix, or Drop, with one reason each. Also list what we learned from it."

Say this:

"Do a salvage audit: sort each part into Keep, Fix, or Drop, with a reason. Then list the lessons learned."

Careful: Do this after you know the new direction (6.1). Otherwise you judge the parts against nothing.


6.6 Clean-slate comparison#

In one line: Design the ideal version fresh, then put it next to the current version and compare.

The idea. Clean slate = an empty board. This move connects first principles with reality. The gap between "ideal" and "current" shows exactly what is wrong and what to change. Without the comparison, first principles stays a dream.

How to do it:

  1. The agent designs the ideal version without seeing your current version.
  2. Then you show the current version.
  3. Compare in a table: part · ideal · current · gap · effort to close the gap.

Example:

  • ❌ "Here is my design. What would the ideal version look like?" (Anchored.)
  • ✅ "Step 1: design a topics system from scratch. Do not ask to see mine. Step 2: I will paste my current design. Step 3: compare in a table: ideal, current, gap, and effort to close each gap."

Say this:

"Design it fresh without seeing my version. Then compare yours with mine in a table: ideal, current, gap, effort."

Careful: Make sure the agent really has not seen your current version in step 1. If it is already in the chat, use a new chat (11.6). Otherwise anchoring (2.1) ruins the comparison.


6.7 Patch vs. rebuild#

In one line: A clear decision: fix the current solution, or rebuild it, based on reasons, not feelings.

The idea. Two common mistakes: patching forever ("just one more fix") and rebuilding too fast ("it's all bad"). Look at the signals:

Signals for rebuild Signals for patch
The problem is in the foundation. The problems are local (in a few places).
Every fix creates new bugs. The foundation is solid.
The core idea or assumption was wrong. The idea is right; only some code is bad.
Nobody understands the code any more. A rewrite would touch too much (big blast radius, 13.1).

The key question: Is the idea wrong, or only the execution (how it was built)?

  • Wrong idea → rebuild.
  • Bad execution → patch or fix.

How to do it:

  1. Check the signals in the table.
  2. Answer the key question with evidence.
  3. Consider a middle path: replace one part at a time.

Example:

  • ❌ "Should I rewrite everything?"
  • ✅ "Should I patch or rebuild my topics system? Check: is the problem in the foundation or in local parts? Did fixes create new bugs? Was the core assumption wrong? Recommend one, with evidence."

Say this:

"Patch or rebuild? Tell me if the core idea is wrong or only the execution, with evidence."

Careful: Rebuilding has hidden costs (2.7 Planning fallacy). A partial rebuild (one part at a time, keeping the system working) is often the best answer.


✏️ Practice: Subject 6#

Pick one solution you built that did not turn out well.

  1. Write the goal and 3 basic truths (6.1).
  2. Do a salvage audit: Keep, Fix, Drop (6.5).
  3. Decide: patch or rebuild? Answer the key question: idea or execution? (6.7)

For the full sequence, use Playbook P1 in Part 7.


Subject 7: Systems thinking#

Seeing how parts connect, so one change does not surprise you somewhere else.

A system = parts that are connected and affect each other. Your app is a system. Your business is a system. A client's marketing is a system. When you change one part, other parts move too. Systems thinking helps you see those connections before they surprise you.

4 moves: Second-order effects · Feedback loops · Bottleneck · Leverage point

(Code-level connections, like coupling and blast radius, are in Subject 13.)


7.1 Second-order effects#

In one line: Ask "and then what?" The first result of a decision may be good, but the next results can be bad.

The idea.

  • First-order effect: you offer a free trial → more signups.
  • Second-order effect: more free users → more server cost, more support messages.
  • Third-order effect: many people get used to "free" → fewer people ever pay.

Most people stop at the first effect. Good thinkers ask "and then what?" two or three times.

How to do it:

  1. Write the decision.
  2. Write the first effect.
  3. Ask "and then what?" 2 or 3 times.
  4. Look at different people: users, you, clients, and future you.

Example:

  • ❌ "Should I make all PPSC papers free?"
  • ✅ "I plan to make all PPSC papers free. List the first-order effects, then the second- and third-order effects. Ask 'and then what?' each time. Include effects on me, on students, and on my income."

Say this:

"And then what? List the second- and third-order effects of this decision."

Careful: Do not go 10 levels deep. 2 or 3 levels are enough. Effects far away are only guesses.


7.2 Feedback loops#

In one line: A loop where a result comes back and causes more (or less) of itself.

The idea. There are two kinds:

  • Reinforcing loop (grows): more students → more reviews → more students. This can also grow bad things: slow site → users leave → less income → no time to improve → site gets worse.
  • Balancing loop (keeps stable): price goes up → fewer buyers → price comes down.

Loops show you where a small action can grow very big, good or bad.

How to do it:

  1. Draw the circle: A → B → C → back to A.
  2. Mark each arrow: more causes more (+) or more causes less (−).
  3. Ask the agent to find the loops you missed.

Example:

  • ❌ "How do I grow my PPSC app?"
  • ✅ "Map the feedback loops in my PPSC app's growth. Which loops push growth, and which slow it down? Where can a small change have a big effect?"

Say this:

"Find the feedback loops in this system. Which ones grow things? Which ones balance them?"

Careful: Loops take time to show their effect. Do not expect results in one day.


7.3 Bottleneck#

In one line: The slowest part of a system limits the whole system. Improving any other part is wasted effort.

The idea. A bottle's neck controls how fast water comes out. A wider bottle does not help. This idea comes from Eliyahu Goldratt's Theory of Constraints.

  • If your website projects wait for clients to send content, coding faster does not deliver projects faster.
  • If a database query takes 3 seconds, making the images smaller does not make the page fast.

How to do it:

  1. List all the steps.
  2. Find where work waits the longest. Measure if you can.
  3. Improve only that step.
  4. Then find the new bottleneck. It moves.

Example:

  • ❌ "How do I deliver client websites faster?"
  • ✅ "My website projects take 6 weeks. Steps: brief, design, content from client, build, review, launch. Where is the bottleneck? Suggest how to improve only that step."

Say this:

"What is the bottleneck here? Focus only on improving that."

Careful: Measure, do not guess (see 2.6 Availability trap). After you fix one bottleneck, a different step becomes the slowest.


7.4 Leverage point#

In one line: A place in a system where a small change creates a big result.

The idea. A lever lets you lift something heavy with a small force. The systems thinker Donella Meadows wrote about leverage points in systems.

  • In code: a shared component, a good default, a project template.
  • In business: the first 5 seconds of a homepage.
  • In your agent work: a good project instructions file improves every future chat.

How to do it:

  1. Ask: "Where does one change affect many things?"
  2. List the options.
  3. Rank them by effect ÷ effort.

Example:

  • ❌ "How can I work better?"
  • ✅ "What are the leverage points in how I build client websites? Where would one change improve every future project?"

Say this:

"Where is the leverage point: one small change with the biggest effect?"

Careful: High leverage often means high risk. A change to a shared part affects many places (see 13.1 Blast radius). Change it carefully.


✏️ Practice: Subject 7#

Think about how you deliver a client website, from first message to launch.

  1. Find the bottleneck (7.3).
  2. Find one leverage point (7.4).
  3. For one improvement idea, ask "and then what?" two times (7.1).

Part 4: Choosing#

You have options. Part 4 helps you test them honestly, choose well even when you are not sure, and use simple rules that are right most of the time.


Subject 8: Testing your thinking#

Attacking your own plan before reality does.

Every plan feels good to the person who made it (2.5 IKEA effect). This subject gives you ways to find the weak points while they are still cheap to fix.

4 moves: Weakest assumption · Steelman · Falsification · Pre-mortem


8.1 Weakest assumption#

In one line: Of all the things you believe but have not checked, this is the one most likely to be wrong. And if it is wrong, the whole plan fails.

The idea. A plan usually stands on many assumptions (3.8). Checking all of them takes too long. Checking none is a big risk. This move finds the one that matters most. Judge each assumption on two things:

  • How unsure am I?
  • How big is the damage if I am wrong?

The weakest assumption is high on both.

How to do it:

  1. List the assumptions in the plan.
  2. Rate each one: how unsure, how much damage.
  3. Pick the weakest.
  4. Find a cheap way to test it before you build.

Example:

  • ❌ "I will build a paid monthly plan for my PPSC platform. Is it a good plan?"
  • ✅ "I will build a paid monthly plan for my PPSC platform. List the assumptions in this plan. Rank them by risk. Tell me the weakest assumption and a cheap way to test it before I build."

Say this:

"What is the weakest assumption in this plan? How can I test it cheaply?"

Careful: A risk is anything that could go wrong. The weakest assumption is the hidden belief your plan stands on. Skip this for small tasks that are easy to undo. If a mistake costs 10 minutes, just try.


8.2 Steelman#

In one line: Build the strongest, fairest version of an idea, especially one you disagree with.

The idea. Steel = strong. It is the opposite of a straw man, a weak, fake version of an idea that is easy to knock down and teaches you nothing. We usually describe our own idea well and the other idea badly. So we choose our own too fast. When the agent builds the best case for the other side, you see real reasons you missed.

How to do it:

  1. Pick the option you do not like or did not choose.
  2. Ask for the best reasons why smart people would choose it.
  3. Ask the agent to be fair, not weak.

Example:

  • ❌ "Should I build my own login system?" (The agent may simply agree with you.)
  • ✅ "I plan to build my own login system for the PPSC platform. Steelman the opposite: the strongest case for using a ready-made login service. Be fair. Do not make it weak."

Say this:

"Steelman the option I did not choose. Give the strongest honest case for it."

Careful: A devil's advocate argues against you just to test you. A steelman is about being fair to the other idea and really understanding it. A steelman is one input, not your final answer. Skip it when the decision is already final.


8.3 Falsification#

In one line: Try to prove an idea wrong, instead of trying to prove it right.

The idea. Falsify = show that something is false. The key question is: "What result would show that I am wrong?" If no result could ever show you are wrong, your idea is too vague. Make it more exact first.

This is the cure for confirmation bias (2.2). One test that fails teaches you more than ten tests that pass.

How to do it:

  1. Write your idea clearly.
  2. Ask: "What would I see if this idea is wrong?"
  3. Run that test first, or ask the agent to run it.

Example:

  • ❌ "I think the slow page is caused by the cache. Can you confirm?"
  • ✅ "I think the slow page is caused by the cache. What test would show I am wrong? Run that test first. If my idea fails, tell me clearly."

Say this:

"What result would prove my idea wrong? Test that first."

Careful: Verifying (Subject 15) checks that something works. Falsification looks for the "no" that breaks your idea. They work together. Do not use falsification while brainstorming. It kills ideas too early.


8.4 Pre-mortem#

In one line: Imagine your project has already failed. Then explain why it failed.

The idea. A post-mortem is a study done after something failed (the word comes from the doctor's exam after death). A pre-mortem is the same study, done before you start. When failure is treated as a fact, the mind tells a real, specific story of what went wrong. That is easier than guessing "what might go wrong". The agent also becomes more direct. It does not need to be polite about a plan that "already failed".

How to do it:

  1. Say: "It is 6 months later, and it failed."
  2. List the reasons.
  3. Rank them by how likely they are.
  4. Write one prevention step for each of the top reasons.

Example:

  • ❌ "What risks does my PPSC platform have?" (You get a generic list.)
  • ✅ "Imagine it is 6 months from now. My PPSC platform launched, but almost nobody uses it. Write the 5 most likely reasons, ranked. For each, give one thing I can do now to prevent it."

Say this:

"Imagine this project failed 6 months from now. What are the most likely reasons? Rank them and give one prevention step each."

Careful: Close to Inversion (5.2). Inversion asks "how could I cause failure?" and gives you rules. A pre-mortem pretends failure already happened and tells a specific story about one project. After the project is finished, do a real post-mortem instead (14.8).


✏️ Practice: Subject 8#

Pick a plan you have now (for example, how you will get your first paying students).

  1. Do a pre-mortem (8.4).
  2. Find the weakest assumption (8.1) and a cheap test for it.
  3. Steelman one option you did not choose (8.2).

Subject 9: Decisions under uncertainty#

Choosing well, even when you cannot know the future.

Uncertainty = not knowing for sure. Almost every real decision is uncertain. You cannot remove the uncertainty. But you can decide in a smart way: clear criteria, honest costs, the right speed, and the right amount of searching.

8 moves: Criteria first · Trade-off · Opportunity cost · Reversible vs. irreversible · Base rate · Expected value · Satisficing vs. maximizing · Regret minimization


9.1 Criteria first#

In one line: Decide how you will judge the options before you look at the options.

The idea. Criteria (say: kry-TEER-ee-uh) = the points you use to judge. One point is a criterion. Examples: cost, build time, ease of fixing, risk.

If you choose criteria after you see the options, you often pick criteria that make your favorite win. If you give no criteria at all, the agent compares on random points and gives a long list of pros and cons. With criteria first, the answer is short, fair, and easy to compare.

How to do it:

  1. Write 3 to 5 criteria.
  2. Put them in order of importance.
  3. Ask the agent to compare only on these, in a table.

Example:

  • ❌ "Which database should I use?"
  • ✅ "I need to store PPSC questions and student results. My criteria, most important first: 1) easy for me to learn and fix alone, 2) free or very cheap for 200 students, 3) works well with Next.js on Vercel, 4) can grow to 5,000 students. Compare 3 options only on these, in a table. Then recommend one."

Say this:

"My criteria, in order of importance: [...]. Compare the options only on these. Show a table, then recommend one."

Careful: A hard constraint (3.5) is pass/fail. It removes an option completely. A criterion gives a score to the options that passed.


9.2 Trade-off#

In one line: When you get more of one good thing, you get less of another. Every option gives something and takes something.

The idea. You give up X to get Y. Agents often call one option "best" and hide its cost. Asking for trade-offs brings the cost into view. There is no perfect option. If an answer shows no downside, be careful.

Three questions:

  • What do I gain?
  • What do I lose?
  • Who pays the cost: me now, me later, or my users?

How to do it:

  1. For each option, list what you gain and what you lose.
  2. Ask: "Which loss hurts me most, in my situation?"

Example:

  • ❌ "Is server rendering better for my PPSC pages?"
  • ✅ "For my PPSC question pages, compare server rendering and client rendering. For each, what do I gain and what do I give up? Which loss hurts me more? I work alone, and I want good Google ranking."

Say this:

"For each option, what do I gain and what do I give up? Which loss hurts me most?"

Careful: A trade-off is not a flat pros-and-cons list. In a trade-off, the good part often exists because of the bad part. Example: a simple tool has fewer features. Simple because it has fewer features.


9.3 Opportunity cost#

In one line: The real cost of a choice is the best other thing you can no longer do.

The idea. It is not only the money you pay. For a solo developer, the biggest cost is usually time. Two weeks on feature A means two weeks not on feature B. Agents judge ideas one at a time, and every idea looks good alone. The real question is: "Is this better than the other ways I could use the same time?"

How to do it:

  1. List your real alternatives for the same time or money.
  2. Ask: "If I choose this, what is the best thing I give up?"
  3. Decide if it is still worth it.

Example:

  • ❌ "Should I add a leaderboard?"
  • ✅ "I have 2 weeks. Options: a leaderboard, adding more past papers, or making mobile pages faster. If I build the leaderboard, what do I lose by not doing the other two? Which gives students the most value?"

Say this:

"If I choose this, what is the best thing I give up? Is it still worth it?"

Careful: A trade-off is inside one option (what it gives and takes). Opportunity cost is between your choices (what else you could do with the same time or money).


9.4 Reversible vs. irreversible decisions#

In one line: A reversible decision is easy to undo. An irreversible decision is hard or impossible to undo.

The idea. Reverse = go back. It is a scale, not two boxes:

  • Changing button text = very easy to undo.
  • Deleting real student data = very hard to undo.
  • Sending an email to 5,000 students = cannot undo.

For reversible decisions: decide fast, try, and learn. For irreversible ones: slow down, check more, make a backup, and plan a way back. Agents often act with the same confidence on everything. When you name the type, the agent uses the right level of care.

Test: "If I am wrong, how much time, money, and trust do I lose to go back?"

How to do it:

  1. Ask the test question.
  2. If it is irreversible: backup, plan, check, then act.
  3. If it is reversible: try it.

Example:

  • ❌ "Rename the student ID field in the database."
  • ✅ "I want to rename the student ID field. This is hard to undo, because real student data exists. Before you change anything, tell me what could break, how to make a backup, and how to go back."

Say this:

"Is this reversible? If not, tell me the risks and a safe way back before we start."

Careful: Do not treat everything as irreversible, or you will become slow. If your code is saved in Git (a tool that keeps old versions of your code), small code edits are easy to undo. Blast radius (13.1) = how much breaks. Reversibility = how hard it is to undo. They are different.


9.5 Base rate (the outside view)#

In one line: Before you judge your specific case, ask: how often does this usually happen in general?

The idea. Your plan feels special, because you know its details. That is the inside view. The outside view asks: "What happened to other projects like mine?" That general number is the base rate. For example: most new apps get very few users in their first year. Start from the base rate, then adjust a little for your real advantages. The psychologist Daniel Kahneman showed that this makes predictions much better.

How to do it:

  1. Find the group: "projects like mine".
  2. Ask: "What usually happens to them?"
  3. Start from that number.
  4. Adjust a little for your real (not hoped) advantages.

Example:

  • ❌ "I think 30% of my free users will pay."
  • ✅ "Before I estimate how many students will pay: what percentage of free users usually pay for education apps? Start from that number, then adjust for my situation. Give a range, not one number."

Say this:

"What is the base rate for things like this? Start there, then adjust for my situation."

Careful: The agent's numbers may be wrong or old. Ask for a range and for sources, and check important numbers yourself.


9.6 Expected value#

In one line: The value of an option = how good the result is × how likely it is. Compare options this way.

The idea.

  • A 10% chance to earn 100,000 → expected value 10,000.
  • A 90% chance to earn 20,000 → expected value 18,000.

The second option looks smaller but is better on average. Also, always look at the worst case. Never take a risk you cannot recover from, even if the expected value is good.

How to do it:

  1. For each option, list the possible results.
  2. Give each result a rough chance and a rough value.
  3. Multiply and add.
  4. Check the worst case of each option.

Example:

  • ❌ "Should I build a mobile app or improve the website?"
  • ✅ "Option A: build a mobile app (about 3 months). Option B: improve the website. For each, estimate the likely results, with rough chances and value. Compare the expected value and the worst case."

Say this:

"Compare expected value: for each option, the likely results × their chance. Also show the worst case."

Careful: The numbers are rough guesses. Use this to think clearly, not to pretend you are precise.


9.7 Satisficing vs. maximizing#

In one line: Maximizing = searching for the best option. Satisficing = taking the first option that is good enough.

The idea. Satisficing is a word made by the economist Herbert Simon: satisfy + suffice. For small, reversible choices (an icon library), searching for the best wastes time. For big, irreversible choices (the database for real student data), search more. The agent will keep giving you more options. You decide when to stop.

How to do it:

  1. Before searching, write what "good enough" means (your must-haves).
  2. Take the first option that meets all of them.
  3. Stop searching.

Example:

  • ❌ "Compare all chart libraries for React."
  • ✅ "I need a chart library for my dashboard. Good enough = free, works with React, has bar and line charts. Give me the first option that meets this. Do not compare 10."

Say this:

"Good enough means [...]. Pick the first option that meets this. Do not search for perfect."

Careful: Combine with 9.4. Satisfice on reversible choices. Maximize on irreversible ones.


9.8 Regret minimization#

In one line: For a big decision, imagine your future self: which choice will you regret less?

The idea. Jeff Bezos used this idea when he decided to leave a safe job and start Amazon. He imagined himself at 80 years old. He knew he would not regret trying and failing. But he would regret never trying. Short-term fear is loud. Long-term regret is quiet. For big choices, the long view helps you hear the quiet voice.

How to do it:

  1. Imagine yourself in 5 years (or at 80).
  2. Ask: "Which choice would I regret not making?"
  3. Then check the practical risks too (9.6 worst case).

Example:

  • ❌ "Should I focus on my own product?"
  • ✅ "I am deciding whether to spend more time on my PPSC app or only do client work. Help me think: in 5 years, which choice am I more likely to regret, and why? Also list the practical risks of each."

Say this:

"In 5 years, which choice would I regret more? Help me think it through, with the practical risks."

Careful: Use this only for big life or business decisions. Not for technical choices. Always combine it with real numbers and risks.


✏️ Practice: Subject 9#

Pick a real choice you face (a tool, a feature, or how to spend next month).

  1. Write criteria first (9.1).
  2. Is it reversible? (9.4) Then decide: satisfice or maximize? (9.7)
  3. Ask for trade-offs (9.2) and the opportunity cost (9.3).

Subject 10: Rules of thumb (heuristics)#

Short rules that are right most of the time.

A heuristic (say: hyoo-RIS-tik) is a quick rule that gives a good answer most of the time, without long thinking. Heuristics are not laws of nature. They are shortcuts that experienced people use. Knowing their names lets you use them, and lets the agent understand you in one word.

6 moves: The 80/20 rule · Occam's razor · YAGNI · Goodhart's law · Hofstadter's law · Lindy effect


10.1 The 80/20 rule (Pareto principle)#

In one line: Often, about 80% of the results come from about 20% of the causes.

The idea. The economist Vilfredo Pareto noticed this pattern. It is not exact, but it appears everywhere:

  • A few clients bring most of your income.
  • A few pages get most of the visits.
  • A few bugs cause most of the complaints.
  • A few features give most of the value.

So find the important 20% and focus there first.

How to do it:

  1. List the items (pages, features, clients, bugs).
  2. Find the small group that gives most of the result.
  3. Work on that group first.

Example:

  • ❌ "Improve SEO on all 40 pages of the dental clinic site."
  • ✅ "Which 20% of the dental clinic site's pages bring most of the visits and bookings? Improve those first. Show me the list and the reason."

Say this:

"Which 20% of this gives 80% of the result? Let's focus there first."

Careful: The numbers 80 and 20 are not exact. It is a direction, not a law. Some work (security, legal) must be done 100%.


10.2 Occam's razor#

In one line: When there are several explanations, the simplest one is usually right. Check it first.

The idea. William of Ockham was a thinker in the 1300s. The "razor" cuts away extra ideas you do not need. If the site broke right after you changed an environment variable, the simplest explanation is the variable, not a strange bug in Next.js. Agents sometimes jump to complex theories. This rule brings them back.

How to do it:

  1. List the possible explanations.
  2. Order them from simplest to most complex.
  3. Check the simplest first.

Example:

  • ❌ "Why is my build failing? Maybe a deep problem with the framework?"
  • ✅ "The build started failing today. List possible causes from simplest to most complex. Check the simplest first, like a recent change or a missing environment variable."

Say this:

"List explanations from simplest to most complex. Check the simplest one first."

Careful: "Simplest" does not mean "always right". It means "check first". If the simple explanation fails the test, move to the next one.


10.3 YAGNI (You Aren't Gonna Need It)#

In one line: Do not build something now because you might need it later.

The idea. YAGNI comes from a software method called Extreme Programming. Agents love to add "future-proof" features: settings nobody uses, layers "in case we change the database", support for 10 languages when you need one. Each extra piece costs time, adds bugs, and makes changes harder. Usually, the future need never comes, or it comes in a different shape.

How to do it:

  1. For each part, ask: "Do I need this today, for a real user?"
  2. If not, remove it from the plan.
  3. Build it later, when the need is real.

Example:

  • ❌ "Build the quiz system so it can support any exam in the world later."
  • ✅ "Build the quiz system for PPSC only. YAGNI: do not add support for other exams, other languages, or settings I did not ask for. Keep it easy to change later."

Say this:

"YAGNI: build only what is needed now. List anything you were going to add 'for the future' and leave it out."

Careful: YAGNI is about features. It does not mean "write messy code". Clean, simple code that is easy to change is still important. Also, some things are very hard to add later (security, data structure). Think about those early.


10.4 Goodhart's law#

In one line: When a number becomes the target, it stops being a good measure.

The idea. The economist Charles Goodhart noticed this. People (and agents) find ways to make the number look good without improving the real thing.

  • Target: "more pages indexed by Google". Result: many thin, useless pages.
  • Target: "students answer more questions". Result: they click randomly to finish fast.
  • Target: "all tests pass". An agent may change the tests instead of fixing the code.

How to do it:

  1. For every number you track, write the real goal behind it.
  2. Ask: "How could someone hit this number without reaching the real goal?"
  3. Watch for that, or track a second number.

Example:

  • ❌ "Make all the tests pass."
  • ✅ "Make the tests pass by fixing the code. Do not change or delete tests to make them pass. If a test is wrong, tell me first."

Say this:

"The real goal behind this number is [...]. How could this number improve without the real goal improving? Avoid that."

Careful: Numbers are still useful. The problem is only when the number becomes more important than the goal it measures.


10.5 Hofstadter's law#

In one line: It always takes longer than you expect, even when you take Hofstadter's law into account.

The idea. The writer Douglas Hofstadter made this funny rule. It means: even when you add extra time, you are still too optimistic. It is a short name for the planning fallacy (2.7). Use it when you promise dates to clients, or when the agent says "this will be quick".

How to do it:

  1. Make your estimate.
  2. Add a buffer.
  3. Promise the client a date after your buffered estimate.

Example:

  • ❌ "Tell the client the site will be ready in 2 weeks." (Your raw estimate.)
  • ✅ "My estimate is 2 weeks. Using Hofstadter's law, what risks could make it longer? What date is safe to promise the client?"

Say this:

"Remember Hofstadter's law. What could make this take longer, and what is a safe date to promise?"

Careful: This is a reminder, not an exact formula. For a better estimate, use Base rate (9.5): how long did similar projects really take?


10.6 Lindy effect#

In one line: For things that do not die naturally (tools, ideas, technologies), the longer it has existed, the longer it will probably continue to exist.

The idea. The writer Nassim Taleb made this idea popular. A tool that has been used for 20 years (like SQL databases) will probably still be used in 20 years. A tool that appeared 6 months ago may disappear next year. For a solo developer, choosing long-living tools means less rewriting and fewer surprises.

How to do it:

  1. When choosing a tool or library, check how old and widely used it is.
  2. For important, long-term parts (data, core logic), prefer older, proven tools.
  3. Use new tools for small, replaceable parts, or for learning.

Example:

  • ❌ "Use the newest database library that came out last month."
  • ✅ "For storing real student data, I prefer proven tools that have existed for years (Lindy effect). Suggest options that are mature and widely used, and tell me how long each has existed."

Say this:

"Prefer mature tools that have existed for years for this part. Tell me how long each option has been around."

Careful: Old does not always mean good. Sometimes an old tool is dying. Check if it is still maintained (updated). And sometimes the new tool is clearly better. Use the Lindy effect as one criterion (9.1), not the only one.


✏️ Practice: Subject 10#

For your PPSC platform or a client site:

  1. Find the 20% that gives 80% of the value (10.1).
  2. List 3 things you planned "for the future". Apply YAGNI (10.3).
  3. Pick one number you track. How could it go up without the real goal improving? (10.4)

Part 5: Doing the work#

You know what to build. Part 5 is about building it with the agent: choosing the right way of working together, giving clear tasks, and changing code without breaking things.


Subject 11: Working with your agent#

Choosing the right way of working together for each moment.

An agent can be many things: a builder, a critic, a teacher, an interviewer, a planner. If you do not say which one you need, it usually becomes a builder, and starts building at once. This subject teaches you to choose the mode (the way of working) on purpose.

6 moves: Thinking mode vs. doing mode · Diverge, then converge · Socratic mode · Give the agent a role · Think first, answer second · Fresh start


11.1 Thinking mode vs. doing mode#

In one line: Tell the agent if you want it to think with you (no code, no changes) or to do the work.

The idea. Agents are built to act. If you share a problem, they often start writing code immediately, even when you only wanted to talk. Code written before the thinking is finished is usually the wrong code. Separating the two modes protects you.

  • Thinking mode: discuss, question, compare, plan. No files changed.
  • Doing mode: build, edit, run. Only after the thinking is done.

How to do it:

  1. Start with: "We are in thinking mode. Do not write or change code."
  2. Think together until the plan is clear.
  3. Then say: "Now switch to doing mode."

Example:

  • ❌ "I'm not sure how the topics feature should work..." (The agent starts writing code.)
  • ✅ "Thinking mode only. Do not write code or change files. I want to discuss how the topics feature should work. When we agree on a plan, I will tell you to start building."

Say this:

"Thinking mode: do not write code or change anything yet. Let's discuss first. I will tell you when to build."

Careful: Not the same as Level of detail (12.3). Level of detail is about how zoomed in the answer is. Mode is about whether the agent acts or only talks. Skip thinking mode for small, clear tasks.


11.2 Diverge, then converge#

In one line: First open up (many ideas, no judging). Then close down (judge and choose). Never both at once.

The idea. Diverge = move apart, spread out. Converge = come together. Designers draw this as a diamond shape: wide in the middle, narrow at the end. When you judge ideas while you create them, good ideas die early. When you never judge, you never decide. Tell the agent which phase you are in.

How to do it:

  1. Diverge: "Give me many options. Do not judge them." (Subject 5)
  2. Pause. Read them.
  3. Converge: "Now judge them on these criteria and choose." (Subject 9)

Example:

  • ❌ "Give me some ideas and tell me which is best." (Both at once. The agent gives 3 safe ideas and picks the first.)
  • ✅ "Diverge first: give me 8 ideas to help students revise before the exam. No judging. Then I will pick a few, and we converge using my criteria."

Say this:

"We are in the diverge phase: many ideas, no judging. We will converge later."

Careful: Divergence without a time limit never ends. Decide in advance how many ideas you need.


11.3 Socratic mode#

In one line: The agent does not give the answer. It asks questions that help you find the answer and see the holes in your thinking.

The idea. Socrates was a teacher in ancient Greece. He taught by asking questions, not by giving answers. This mode is very good for learning and for testing your reasoning, because you do the thinking and the agent guides you.

Difference from Interview me (1.5):

  • Interview me = the agent collects your idea to understand it.
  • Socratic mode = the agent challenges your thinking, so you find the problems yourself.

How to do it:

  1. Explain your idea or your reasoning.
  2. Ask the agent to question it, one question at a time, without giving answers.
  3. Answer honestly. If you cannot answer, you found a weak spot.

Example:

  • ❌ "Is my database design good?"
  • ✅ "Use Socratic mode. Do not tell me the answer. Ask me questions, one at a time, that make me find the problems in my database design myself."

Say this:

"Socratic mode: don't give me answers. Ask me one question at a time that helps me find the weak points myself."

Careful: It is slower. Use it when you want to learn or deeply understand, not when you need a fast result.


11.4 Give the agent a role#

In one line: Tell the agent who to be: a strict reviewer, a senior developer, a first-time user, a client.

The idea. A role changes what the agent looks for and how it speaks. "Review my homepage" gives a general answer. "Review my homepage as a busy dental patient on a phone" gives a specific, useful answer. Roles are also one of the best tricks against sycophancy (2.8).

Useful roles:

  • Strict senior developer: finds code problems.
  • First-time user: finds confusing parts.
  • The client: checks if it matches what they asked for.
  • A competitor: finds weak points in your offer.
  • A teacher: explains simply.

How to do it:

  1. Choose a role that fits what you want found.
  2. Describe the role in one sentence, with what it cares about.
  3. Ask for the specific output you want.

Example:

  • ❌ "Review the dental clinic homepage."
  • ✅ "You are a busy patient with tooth pain, using a phone. Look at this homepage. What stops you from booking in the first 10 seconds? List the problems in order."

Say this:

"Act as [role], who cares about [...]. From that view, tell me [...]."

Careful: A role does not give the agent real experience. It changes the viewpoint, not the knowledge. For real users, real feedback is still better.


11.5 Think first, answer second#

In one line: Ask the agent to reason step by step, or to think about several possibilities, before it gives its final answer.

The idea. When an agent answers at once, it often takes the first path that looks right. When it first lists what it knows, considers options, and checks its reasoning, the final answer is usually better, especially for difficult questions.

How to do it:

  1. Ask the agent to think through the problem before answering.
  2. Ask it to consider at least 2 possible answers.
  3. Ask for the final answer and the main reason.

Example:

  • ❌ "What is causing the wrong scores?"
  • ✅ "Before you answer: think step by step. List what you know, consider at least 3 possible causes, and check each one against the facts. Then give your best answer and your main reason."

Say this:

"Before you answer, think it through step by step and consider at least 2 possibilities. Then give your answer and the main reason."

Careful: For simple questions, this only makes answers longer. Use it for hard problems, decisions, and diagnosis.


11.6 Fresh start#

In one line: Start a new chat when the current one is full of old ideas, mistakes, or confusion.

The idea. A long chat collects everything: wrong ideas you dropped, old code, corrections. The agent keeps being influenced by all of it (2.1 Anchoring, 2.10 Context drift). A new chat with a clean summary often works much better than "trying again" in the old one.

When to start fresh:

  • The agent goes in circles.
  • It repeats mistakes you corrected.
  • You changed direction completely.
  • You want an honest review of work done in this chat (15.5).

How to do it:

  1. In the old chat, ask for a summary: goal, decisions, constraints, open questions.
  2. Check the summary. Remove anything wrong.
  3. Paste it into a new chat.

Example:

  • ❌ Trying the same fix for the fifth time in a 2-hour chat.
  • ✅ "Write a short summary of this chat for a new chat: the goal, what we decided, what failed and why, the constraints, and the open questions. I will start fresh with it."

Say this:

"Write a summary I can paste into a new chat: goal, decisions, what failed and why, constraints, open questions."

Careful: Do not start fresh too often. You lose useful context. Start fresh when the chat hurts more than it helps.


✏️ Practice: Subject 11#

Next time you have an unclear problem:

  1. Start in thinking mode (11.1).
  2. Diverge, then converge (11.2).
  3. Before building, give the agent a strict reviewer role (11.4) and ask it to attack the plan.

Subject 12: Giving clear tasks#

Telling the agent exactly what to do, what "finished" means, and when to stop.

Once the thinking is done, you give a task. A clear task has a clear target, clear checks, and clear limits. This subject turns your thinking into instructions the agent cannot misunderstand.

8 moves: Restate in your own words · What information is missing? · Level of detail · Acceptance criteria · Definition of done · Example-driven spec · Task breakdown · Stop condition


12.1 Restate in your own words#

In one line: Ask the agent to repeat your request in its own words before it starts.

The idea. If the agent's restatement does not match your idea, you found a misunderstanding before any work was done. This is cheap. Finding it after the work is expensive.

How to do it:

  1. Write your request.
  2. Ask the agent to restate it in its own words, plus what it plans to do.
  3. Correct anything wrong. Then let it start.

Example:

  • ❌ "Build the topic filter." (The agent builds something different from your idea.)
  • ✅ "Before you start, restate in your own words what I am asking for and what you plan to do. Wait for my OK."

Say this:

"Before you start, restate my request in your own words and tell me your plan. Wait for my OK."

Careful: Not the same as Reframing (5.3). Restating keeps the same meaning, to check understanding. Reframing changes the angle on purpose. Skip this for tiny tasks.


12.2 What information is missing?#

In one line: Ask the agent: "What information are you missing that would change your answer?"

The idea. The agent usually fills gaps with guesses (habit 4). This question makes it list the gaps first. Often the missing information is something obvious to you but invisible to it: your scale, your users, your hosting, your deadline.

How to do it:

  1. Give your request.
  2. Ask the question before the agent answers.
  3. Answer the important gaps. Let it make reasonable guesses on the small ones, but ask it to say which guesses it made.

Example:

  • ❌ "What's the best way to add search to my site?"
  • ✅ "I want to add search to my PPSC site. Before you answer: what information are you missing that would change your answer? Ask me the most important questions first."

Say this:

"What information are you missing that would change your answer? Ask me the most important questions first."

Careful: Not the same as Interview me (1.5). This is one list at the start of a clear task. Interview me is a conversation for an unclear idea. Also not the same as Stop condition (12.8), which works in the middle of the work.


12.3 Level of detail (zoom level)#

In one line: Tell the agent if you want the big idea, the design, or the exact code.

The idea. Think of a map: the country, the city, the street.

  • Level 1, idea: what and why, in plain words.
  • Level 2, design: how the parts fit together (pages, data, steps).
  • Level 3, code: exact files and lines.

Two common mistakes: you ask an idea question and get 300 lines of code. Or you give a code-level order before agreeing on the idea. If the agent guesses too high, the answer is vague. Too low, and you get details you cannot use yet.

How to do it:

  1. Choose the level you need now.
  2. Tell the agent to stay at that level.
  3. Move down one level at a time.

Example:

  • ❌ "Tell me about adding bookmarks."
  • ✅ "Stay at the idea level. In plain words, what does a bookmark feature involve on the PPSC platform? No code. I will ask for the design later."

Say this:

"Answer at the [idea / design / code] level. Do not go deeper until I ask."

Careful: Not the same as Task breakdown (12.7). Task breakdown cuts work into steps in order. Level of detail is how zoomed in an answer is.


12.4 Acceptance criteria#

In one line: A list of yes/no checks. If every check is "yes", the work is accepted. If one is "no", it is not finished.

The idea. Without criteria, the agent decides by itself when the task is finished. Often it stops too early, or builds extra things. With criteria, it knows the target. You also review faster: you just go down the list.

The test for a good line: can a stranger check this line and answer yes or no?

  • Weak line: "It should be fast."
  • Strong line: "The page loads in under 2 seconds."

How to do it:

  1. Write 3 to 6 checks.
  2. Make each one yes/no.
  3. Put them in the task.

Example:

  • ❌ "Add a timer to the quiz."
  • ✅ "Add a timer to the quiz. Acceptance criteria: 1) A 30-minute countdown shows at the top. 2) At 00:00, the quiz submits by itself. 3) If I refresh, the timer does not restart. 4) It looks correct on a 360px wide phone screen."

Say this:

"Acceptance criteria (each one a yes/no check): 1) [...] 2) [...] 3) [...]."

Careful: The goal says why you want the work. Acceptance criteria say how to check it is finished. Criteria first (9.1) judges options before choosing. Acceptance criteria judge work after building. Skip for brainstorming.


12.5 Definition of done#

In one line: The checklist that must be true before the agent may say "I am finished". It is the same for every task.

The idea. For an agent, "done" often means "I wrote the code". For you, "done" means "it works, and nothing else broke". The definition of done covers quality, not the feature itself. Write it once and reuse it everywhere, for example in your project instructions file.

Example definition of done:

  • All acceptance criteria pass.
  • The project builds with no errors.
  • No TypeScript errors.
  • No red errors in the browser console.
  • The agent lists every file it changed.
  • The agent says what it could not check.

How to do it:

  1. Write your definition of done once.
  2. Save it in your project notes or instructions file.
  3. Add it to every task (or let the agent read it).

Example:

  • ❌ "Add a bookmark button."
  • ✅ "Add a bookmark button. Done means: all acceptance criteria pass, the project builds with no errors, no TypeScript errors, you list every file you changed, and you tell me what you could not check."

Say this:

"Done means: [...]. Do not say 'done' until you checked each item. Tell me which ones you could not check."

Careful: Acceptance criteria belong to this feature. The definition of done is general and reusable. Use both. For quick experiments, a lighter definition is fine.


12.6 Example-driven spec (input → output)#

In one line: Do not only describe a rule in words. Show real examples: what goes in, and what must come out.

The idea. Spec = specification, a clear description of what to build. Words can be understood in more than one way. An example is exact. If the agent's result does not match your example, both of you see the mistake at once. Examples are also easy to turn into tests.

How to do it:

  1. Write the rule in words.
  2. Add at least one normal example and one edge case (13.4).
  3. Write each as: input → expected output.

Example:

  • ❌ "Calculate the quiz score with negative marking."
  • ✅ "Correct = +1. Wrong = −0.25. Skipped = 0. The score is never below 0. Example 1: 10 correct, 4 wrong, 6 skipped → 9. Example 2: 0 correct, 8 wrong → 0 (not −2)."

Say this:

"Examples (input → expected output): [...]. Include one normal case and one edge case."

Careful: Different from Example and counter-example (4.4), which is about the meaning or style of an idea, not input → output. A few examples cannot cover a complex rule. Write the rule in words and add the examples.


12.7 Task breakdown (small steps)#

In one line: Cut a big task into small steps. Each step gives a result you can check alone.

The idea. On a big task, agents lose track, forget earlier details, or hide mistakes inside a huge change. Small steps keep each change easy to read. If step 3 breaks something, you know it was step 3.

A good step:

  • is small,
  • has one clear result,
  • can be tested before the next step starts.

How to do it:

  1. Ask the agent to break the task into steps.
  2. Check the plan. Approve it.
  3. The agent does one step, then stops so you can check.

Example:

  • ❌ "Build a full student account system."
  • ✅ "I want a student account system. First, break this into small steps. Each step must give a result I can test alone. Show me the plan and wait for my OK. Then do step 1 only, and stop."

Say this:

"Break this into small steps. Each step must be testable alone. Show me the plan first. Do one step at a time and stop after each."

Careful: Minimal change (13.5) is about the size of one edit. Task breakdown is about the order of the whole work. Do not make 30 tiny steps. That is slow too.


12.8 Stop condition#

In one line: A situation where the agent must STOP and ask you, instead of guessing and continuing.

The idea. Agents want to finish the task. When something is unclear, they guess quietly and keep going. A stop condition turns a silent guess into a question for you. This is very important for risky work.

Typical stop conditions:

  • It needs to change files outside the ones you named.
  • It must delete or overwrite data.
  • Two of your requests conflict.
  • The same test fails twice.
  • One of your assumptions turns out to be wrong.

How to do it:

  1. Think: "Where would a wrong guess cost the most?"
  2. Write 3 or 4 stop conditions.
  3. Add "Do not guess."

Example:

  • ❌ "Move my PPSC questions to the new format."
  • ✅ "Move my PPSC questions to the new format. Stop and ask me if: a question has missing fields, you need to delete or overwrite data, or you need to change files outside the data folder. Do not guess."

Say this:

"Stop and ask me if [...]. Do not guess."

Careful: A non-goal (3.6) says "do not do this". A stop condition says "if you reach this point, ask me". Do not add too many, or the agent will ask you all the time.


✏️ Practice: Subject 12#

Take one feature you want to build next.

  1. Write 3 acceptance criteria (12.4).
  2. Write one input → output example (12.6).
  3. Write 2 stop conditions (12.8).
  4. Write your general definition of done (12.5) and save it in your project notes.

Subject 13: Changing code safely#

Editing real code without breaking what already works.

When an agent changes code, the risk is not only "the new thing does not work". The bigger risk is that something else breaks, quietly. This subject gives you the words to make the agent look before it touches anything.

6 moves: Blast radius · Coupling · Invariant · Edge case · Minimal change · Inspect before changing


13.1 Blast radius#

In one line: How much can break if this change goes wrong.

The idea. Blast = explosion. Radius = the distance from the center to the edge.

  • Small radius: changing one text label. Only that label is affected.
  • Big radius: changing a shared function used by 20 pages, or the database, or login.

The agent edits one file and does not always see what depends on it. When you ask for the blast radius, it must search for everything that uses the code. You see the risk before the change.

How to do it:

  1. Before the change, ask: "What uses this code?"
  2. Ask: "What breaks if it fails?"
  3. Use the answer to plan tests (15.2).

Example:

  • ❌ "Change how the quiz score is calculated."
  • ✅ "I want to change how the quiz score is calculated. Before you edit, tell me the blast radius: which pages, saved results, and features use this function?"

Say this:

"What is the blast radius of this change? List everything that uses this code."

Careful: Blast radius = how much breaks. Reversibility (9.4) = how hard it is to undo. Skip this for tiny, isolated changes like a typo.


13.2 Coupling#

In one line: How strongly two parts of the code depend on each other.

The idea. Coupling = a connection, like train cars hooked together.

  • Tight coupling: if you change A, you must also change B.
  • Loose coupling: you can change A, and B does not care.
  • Hidden coupling is the worst: parts share something you cannot see, like a global variable, shared state, or the same database field.

Coupling is the reason a "small" change breaks something far away.

How to do it:

  1. Before moving or changing a part, ask what it shares with other parts.
  2. Ask what else must change together with it.

Example:

  • ❌ "Move the timer into its own file."
  • ✅ "Before moving the timer to its own file, check how tightly it is coupled to the quiz page. What does it share (state, props, global variables)? Tell me what else must change."

Say this:

"How tightly is this coupled to the rest of the code? What else must change if I change it?"

Careful: Coupling is the cause (the connections). Blast radius is the effect (how much breaks). Do not chase zero coupling. Some connection is normal.


13.3 Invariant#

In one line: A rule that must ALWAYS stay true, no matter what you change.

The idea. In-variant = not changing. Examples:

  • A score is never below 0.
  • A student cannot have two active attempts of the same quiz.
  • Stock in a store never goes below 0.
  • An order total always equals items + shipping.

An agent can change code so it "works" but breaks a hidden rule. It does not know your rules unless you say them. When you name the invariants, it protects them, and it can write tests (small automatic checks) for them.

How to do it:

  1. Write the rules your system must never break.
  2. Add them to the task.
  3. Ask the agent to tell you if a change puts any at risk.

Example:

  • ❌ "Add a retry button to the quiz."
  • ✅ "Add a retry button to the quiz. Invariants: a finished attempt is never overwritten. Each attempt keeps its own score and time. The score is always between 0 and the number of questions."

Say this:

"These must always stay true: [...]. Do not break them. Tell me if this change puts any at risk."

Careful: A constraint (3.5) is a limit from outside (budget, tools). An invariant is a rule inside the system. If you do not know your rules yet, ask: "What rules does this code seem to protect?"


13.4 Edge case#

In one line: An unusual situation at the border of normal use, where code often breaks.

The idea. Edge = the border. The happy path is the normal flow, where everything goes well. Agents write for the happy path first. Bugs hide at the edges.

Common edge cases: an empty list, zero, exactly one item, very long text, a double click, refreshing the page in the middle, no internet, special characters in a name, two people editing at the same time.

How to do it:

  1. Ask the agent to list edge cases before writing code.
  2. Choose the important ones (likely or damaging).
  3. Ask it to handle or test them.

Example:

  • ❌ "Write a function to calculate the quiz percentage."
  • ✅ "Write a function to calculate the quiz percentage. List the edge cases first: for example 0 questions, unanswered questions, a quiz submitted twice. Then handle them and explain how."

Say this:

"What edge cases could break this? List them first. Then handle or test the important ones."

Careful: A bug is wrong code. An edge case is a situation. It becomes a bug only if the code does not handle it. Do not ask for every edge case. Ask for the top 5, ranked by likelihood and damage.


13.5 Minimal change#

In one line: The smallest edit that solves the problem. Nothing extra.

The idea. Agents like to "improve" nearby code: rename things, reformat files, rewrite working code. A bigger change means a bigger blast radius, a longer review, and more places for bugs. A minimal change is easy to read, easy to test, and easy to undo.

How to do it:

  1. Ask for the smallest possible change.
  2. Forbid renaming, reformatting, and refactoring other code.
  3. Ask the agent to tell you first if a bigger change is needed.

Example:

  • ❌ "Fix the timer bug."
  • ✅ "Fix the timer bug with the smallest possible change. Do not rename things, reformat, or refactor other files. If you think a bigger change is needed, tell me first."

Say this:

"Make the smallest change that fixes this. Do not clean up anything else. If a bigger change is needed, ask me first."

Careful: When the structure itself is the problem, small patches make it worse. Then plan a real cleanup (6.7 Patch vs. rebuild) and say: "This is a refactor. The behavior must not change."


13.6 Inspect before changing#

In one line: The agent must first read and understand the code, report what it found, and only then edit, after your OK.

The idea. Inspect = look carefully. Agents often start editing from a guess. When they read first, they find wrong assumptions, hidden coupling, and the blast radius. You also get a chance to check that the agent understands the code before it touches anything.

What the report should include:

  • Which files are involved.
  • How the code works now.
  • What uses it.
  • The plan, and why.

How to do it:

  1. Say: "Do not change any file yet."
  2. Ask for the report.
  3. Check the report. Then say OK.

Example:

  • ❌ "Add a bookmark feature to quiz questions."
  • ✅ "I want to add bookmarks to quiz questions. Do not change any file yet. First inspect the code: how are questions loaded, where is user data saved, which files are involved? Tell me what you found and your plan. Wait for my OK."

Say this:

"Inspect first. Do not change any code. Tell me what you found, what you plan to change, and why. Then wait for my OK."

Careful: Restate (12.1) checks that the agent understands your request. Inspect-first checks that it understands the code. Skip for tiny, obvious edits. In a normal chat (where the agent cannot see your files), paste the code first.


✏️ Practice: Subject 13#

Take one real change you want on your PPSC platform.

  1. Write one prompt that uses: inspect before changing (13.6), blast radius (13.1), and 2 invariants (13.3).
  2. Add "smallest possible change" (13.5).

Part 6: Checking and learning#

The work is built. Part 6 answers three questions: Is it really working? If something failed, why? And what do I learn, so it does not happen again?


Subject 14: Diagnosis#

Finding the real cause when something is broken or did not turn out well.

Diagnosis = finding the cause of a problem, like a doctor does. This subject is for two situations:

  • Something is broken (a bug).
  • Something did not turn out well (a solution, a feature, a launch).

The biggest mistake in both: fixing the first cause you think of. This subject makes you find the real cause first.

8 moves: Symptom vs. cause · Expected vs. observed · Reproduce first · What changed? · Divide and conquer · Five Whys · Root cause vs. contributing causes · Blameless post-mortem


14.1 Symptom vs. cause#

In one line: A symptom is what you see. A cause is why it happens. Fix the cause, not only the symptom.

The idea. A fever is a symptom. An infection is the cause. Medicine that only lowers the fever does not cure the infection. In software: "the page is slow" is a symptom. "The page loads all 5,000 questions at once" is a cause. If the agent only treats the symptom (adds a loading spinner), the problem stays.

How to do it:

  1. Describe what you see (the symptom). Do not say the cause yet.
  2. Ask the agent to find the cause before fixing.
  3. Check that the fix targets the cause.

Example:

  • ❌ "The results page is slow. Add a loading spinner."
  • ✅ "Symptom: the results page takes 6 seconds to load. I don't know the cause. Find the cause before suggesting a fix. A loading spinner is not a fix."

Say this:

"This is the symptom: [...]. Find the cause before you fix anything."

Careful: Sometimes you need a quick symptom fix now (for example, during a client demo), and the real fix later. That is fine, if you say so clearly and write the real cause down.


14.2 Expected vs. observed behavior#

In one line: Two sentences. Expected = what should happen. Observed = what you actually see.

The idea. The gap between the two sentences is the problem. "It doesn't work" forces the agent to guess. Two clear sentences show it where to look. This also keeps your facts (what you saw) separate from your theory (what you think the cause is).

How to do it:

  1. Write: Expected: [...]
  2. Write: Observed: [...] (facts only)
  3. Add the steps to see it: where you click, when.

Example:

  • ❌ "The timer on my quiz is broken."
  • ✅ "Expected: the timer counts down from 30:00 and submits at 00:00. Observed: it counts down, but when I refresh, it starts again at 30:00. Steps: start a quiz, wait 1 minute, refresh."

Say this:

"Expected: [...]. Observed: [...]. Steps to see it: [...]. I don't know the cause yet."

Careful: Observed behavior is a detailed symptom (14.1), not the cause. Use your goal (3.1) instead for new features, where nothing is broken.


14.3 Reproduce first#

In one line: Before you fix a bug, make it happen again on purpose, with exact steps.

The idea. Reproduce = make it happen again. Without this, the agent fixes what it thinks is wrong, and may fix the wrong thing. When it reproduces the bug first, it sees the real problem. The same steps then become your before-and-after test.

How to do it:

  1. Find the exact steps that cause the bug.
  2. Show the wrong result.
  3. Fix.
  4. Run the same steps again. The bug must be gone.

Example:

  • ❌ "Sometimes the quiz shows a wrong score. Fix it."
  • ✅ "Sometimes the quiz shows a wrong score. First reproduce it. Find the exact steps that cause it. Show me the steps and the wrong result. Only then fix it. After the fix, run the same steps again."

Say this:

"Reproduce the bug first. Show me the exact steps. After the fix, run the same steps again."

Careful: Expected vs. observed (14.2) describes the problem in words. Reproducing makes it happen. Use both. If the bug is random and cannot be reproduced, ask the agent to add logging (messages the code writes, so you can see what happens).


14.4 What changed?#

In one line: If it worked before and is broken now, first ask: what changed between then and now?

The idea. Most new problems are caused by a recent change: new code, an updated package, a changed setting, new data, a new browser version. Searching the whole system is slow. Searching the changes is fast. Also look at changes outside the code: hosting settings, environment variables, an API from another company, the client editing content.

How to do it:

  1. Find the last time it worked for sure.
  2. List everything that changed since then: code (Git history), packages, settings, data, outside services.
  3. Check the most likely change first.

Example:

  • ❌ "My site broke. Find the problem."
  • ✅ "The site worked on Monday and is broken today. What changed since Monday? Check the Git history, package updates, environment variables, and any content edits in Sanity. Start with the most likely change."

Say this:

"It worked on [date]. List everything that changed since then, inside and outside the code, and check the most likely first."

Careful: If you do not know when it last worked, start with Divide and conquer (14.5).


14.5 Divide and conquer#

In one line: Cut the problem area in half, test which half has the problem, and repeat, until you find the exact spot.

The idea. This is the fastest way to search a big space. It is like the game "guess my number between 1 and 100": you ask "bigger than 50?" and remove half the answers each time. With code, Git even has a tool for this, called git bisect: it tests versions in the middle of your history until it finds the exact change that broke things.

You can divide many things:

  • Time: which version of the code broke it?
  • Code: which half of the components causes it?
  • Data: which half of the questions has the bad data?

How to do it:

  1. Define a clear test: "broken" or "working".
  2. Cut the area in half. Test one half.
  3. Keep the half with the problem. Repeat.

Example:

  • ❌ "Some of the 2,000 imported questions break the page. Find out why."
  • ✅ "Some of the 2,000 imported questions break the page. Use divide and conquer: load the first 1,000 and test. Then halve the broken group again, until we find the exact questions that break it. Then tell me what they have in common."

Say this:

"Use divide and conquer: split the problem area in half, test, keep the broken half, and repeat until we find the exact spot."

Careful: It needs a clear, quick test. If testing is slow or unclear, define the test first (14.3).


14.6 Five Whys#

In one line: Ask "why?" about 5 times, to go from the surface problem down to the real cause.

The idea. This method comes from Toyota, the car company. The first answer to "why?" is usually only a symptom. Each "why" goes one level deeper. Example:

  1. Why did the client complain? → The site was down for 3 hours.
  2. Why was it down? → The build failed after an update.
  3. Why did the build fail? → A package update broke the image component.
  4. Why did the package update without testing? → Updates go live automatically.
  5. Why do updates go live automatically? → There is no check before deployment.

Real cause: no check before deployment. Fixing only the image component would not stop the next failure.

How to do it:

  1. Write the problem.
  2. Ask "why?" and write the answer.
  3. Ask "why?" about that answer. Repeat about 5 times.
  4. Stop when you reach a cause you can fix and that would prevent the problem in the future.

Example:

  • ❌ "The topic feature was bad. Let's fix the tags."
  • ✅ "Do a Five Whys on this: 'the topic feature gave students wrong questions'. Ask why, step by step, at least 5 levels. Stop at a cause that, if fixed, would prevent this type of problem in the future."

Say this:

"Do a Five Whys on this problem. Go at least 5 levels deep and stop at a cause we can fix to prevent it in the future."

Careful: "5" is not exact. Sometimes 3 is enough, sometimes 7. Also, a problem can have more than one cause. Then use 14.7. Avoid "why" answers that blame a person ("because I was careless"). Ask why the system allowed it (14.8).


14.7 Root cause vs. contributing causes#

In one line: The root cause is the main reason. Contributing causes are other things that made it possible or worse.

The idea. Real failures rarely have only one cause. Usually several things go wrong together. Example: a client's site went down because:

  • Root cause: no test before deployment.
  • Contributing: no uptime alert, so nobody knew for 3 hours.
  • Contributing: it happened on a Friday night.

If you only fix the root cause, the next different failure will also be found late. Fixing a contributing cause (the alert) helps with many future problems.

A simple map (a "fishbone" in a list): check these areas for causes:

  • People and process: steps, habits, missing checks.
  • Tools: packages, hosting, services.
  • Data and content: wrong or unexpected data.
  • Environment: settings, devices, browsers, network.
  • Requirements: unclear or changing goals.

How to do it:

  1. Find the root cause (14.6).
  2. Check each area above for contributing causes.
  3. Decide which ones to fix: the root cause, plus the cheapest contributing causes that help most.

Example:

  • ❌ "The bug was the image component. Fixed."
  • ✅ "We found the root cause. Now list the contributing causes: what made this possible, and what made it worse or slower to notice? Check process, tools, data, environment, and requirements."

Say this:

"What is the root cause, and what are the contributing causes? Check process, tools, data, environment, and requirements."

Careful: Do not try to fix every small cause. Pick the 2 or 3 that prevent the most future problems.


14.8 Blameless post-mortem#

In one line: After something went wrong, study what happened and why, without blaming any person, and write down what will change.

The idea. Companies like Google use this method. Blameless = without blame. If people are blamed, they hide mistakes, and nobody learns. If the question is "what in our system allowed this?", people share honestly. This includes you, when you review your own failed solution. "I was stupid" teaches you nothing. "My process had no check for X" teaches you a lot.

Simple post-mortem template:

  1. Summary: what happened, in 2 sentences.
  2. Timeline: what happened, in order.
  3. Expected vs. what happened.
  4. Root cause and contributing causes (14.6, 14.7).
  5. What went well (yes, also this).
  6. What we will change (specific actions).
  7. Lessons to save (16.5).

How to do it:

  1. Collect the facts: messages, logs, code changes, dates.
  2. Fill in the template with the agent.
  3. Turn "what we will change" into real tasks.

Example:

  • ❌ "My topics feature was a failure. I made bad decisions. What now?"
  • ✅ "Help me write a blameless post-mortem of my topics feature. Use this structure: summary, timeline, expected vs. what happened, root and contributing causes, what went well, what we will change, and lessons. Focus on the process, not on blame."

Say this:

"Help me write a blameless post-mortem: summary, timeline, expected vs. what happened, causes, what went well, what we will change, lessons."

Careful: Blameless does not mean "nobody is responsible". It means the goal is learning and fixing, not punishment. After the post-mortem, someone must still do the changes.


✏️ Practice: Subject 14#

Pick a solution or feature that did not turn out well.

  1. Write expected vs. what happened (14.2).
  2. Do a Five Whys (14.6).
  3. Write one blameless post-mortem (14.8) with at least 2 changes you will make.

Subject 15: Verifying work#

Checking that the work is really done, really correct, and did not break anything else.

Verify = check that something is true. The agent's report is a claim. This subject turns claims into proof.

5 moves: Evidence (not claims) · Regression check · Diff review · Smoke test · Fresh-eyes review


15.1 Evidence (not claims)#

In one line: A claim is "it works". Evidence is proof you can see: a test result, an output, a screenshot, the exact file and line.

The idea. Agents sound sure even when they are wrong. They can say "Fixed!" when the code never ran. When you ask for evidence, the agent must check its work, or admit it could not.

Good evidence includes:

  • What the agent ran.
  • The output it got.
  • Where in the code the change is.
  • What it could not check.

How to do it:

  1. In the task, say: "Show evidence."
  2. When the agent reports, look for the evidence, not the summary.
  3. For risky changes, check the evidence yourself.

Example:

  • ❌ "Fix the timer bug." → "Fixed! ✅" → you believe it.
  • ✅ "Fix the timer bug. When you finish, show evidence: what you ran, the result, and the file and line you changed. If you could not run it, say so. Do not say 'fixed' without proof."

Say this:

"Don't only tell me it works. Show evidence: what you ran and what the result was. Say what you could not check."

Careful: Evidence shows the work was built right. It does not show you built the right thing. A quiz timer can work perfectly, but students may not want it. For that, see Learning loops (Subject 16).


15.2 Regression check#

In one line: After a change, check that things that worked before still work.

The idea. Regress = go backwards. A regression is a feature that worked yesterday and is broken today. Agents focus on the new thing. A fix in one place often breaks a neighbor. Use your blast radius list (13.1) to know what to test.

How to do it:

  1. List the features the change could touch (blast radius).
  2. Check each one after the change.
  3. Report the result for each.

Example:

  • ❌ "Change the score formula." (And nothing else is checked.)
  • ✅ "Change the score formula. Then do a regression check: first list the features that use the score (results page, history page). Then check that each still works. Tell me what you checked."

Say this:

"Do a regression check: what worked before that this change could break? Check each one and list the results."

Careful: Blast radius is before the change (a prediction). Regression check is after the change (a test). Do not test the whole app every time. Test only what the change could reach.


15.3 Diff review#

In one line: Read exactly which lines changed, not only the agent's summary.

The idea. Diff = difference. It is a view that shows removed lines and added lines. Git and code editors can show it. The summary tells you what the agent intended. The diff shows what it did. Extra changes sometimes hide inside: renamed variables, deleted checks, changed settings.

Three questions for every diff:

  1. Is every change needed?
  2. Did it change anything outside the task?
  3. Did it delete anything?

How to do it:

  1. Ask for the full diff.
  2. Ask for a one-sentence reason for each change.
  3. Ask the agent to mark anything outside the task, or any deletion.

Example:

  • ❌ "Fix the bug." → you accept without looking.
  • ✅ "After the fix, show me the full diff. Explain each change in one sentence. Mark any change not needed for the bug, and anything deleted."

Say this:

"Show me the full diff. For each change, say why it is needed. Mark anything outside the task, and anything deleted."

Careful: Evidence shows the code works. A diff review shows what was changed. Code can work and still contain edits you never wanted. A diff with hundreds of lines is too big to review. Go back to Task breakdown (12.7).


15.4 Smoke test#

In one line: A fast, shallow test that checks if the most important things work.

The idea. The name comes from electronics: you switch on a new machine, and if no smoke comes out, you continue testing. A smoke test checks only the main path: the app starts, the home page opens, a user can do the one main thing. Usually 3 to 5 checks, each pass or fail. "Check that everything works" is too vague. A smoke test is short and exact.

How to do it:

  1. Write the main user path in 3 to 5 steps.
  2. Ask for pass or fail on each step.
  3. Run it after every important change or deployment.

Example:

  • ❌ "Check that everything still works."
  • ✅ "Run a smoke test of my PPSC platform: the home page loads, a student can open a quiz, answer a question, submit, and see a score. Report pass or fail for each step."

Say this:

"Run a smoke test of the main user path: [steps]. Report pass or fail for each step."

Careful: A smoke test is wide and shallow (does the main path work?). A regression check is narrow and targeted (what could this change have broken?). A passing smoke test means the app is alive, not that it is fine.


15.5 Fresh-eyes review#

In one line: Ask a different AI chat, with no history of the work, to review the result.

The idea. The agent that built the work tends to defend it. It already "believes" its own plan. This is like sycophancy (2.8) and the IKEA effect (2.5), but toward itself. A new chat has no attachment, so it more easily sees what the first one missed.

How to do it:

  1. Open a new chat.
  2. Paste only the requirements and the result (code, text, plan). Do not paste the first agent's reasons for why it is right.
  3. Give it a critic role (11.4).
  4. Remove secrets (passwords, API keys) before pasting.

Example:

  • ❌ In the same chat: "Is your code correct?"
  • ✅ In a new chat: "You did not write this code. You are a strict reviewer. Here are the requirements and the code. Find bugs, missing edge cases, and anything that breaks the requirements. Order them from most to least serious. If it is good, say so."

Say this:

"You did not write this. Review it against these requirements. List problems from most serious to least serious. If it is good, say why."

Careful: Skip for tiny changes. A fresh reviewer may also be wrong. Treat its list as things to check, not as truth.


✏️ Practice: Subject 15#

Think of the last time an agent said "done" and it was not.

  1. Write the prompt you will use next time, with: evidence (15.1), a smoke test (15.4), and a diff review (15.3).
  2. Save it in your notes as your "done check" prompt.

Subject 16: Learning loops#

Making sure each project makes you smarter, so you do not repeat the same mistakes.

A loop goes around and comes back. A learning loop is: try → see the result → learn → try better. The faster and more honest your loop, the faster you improve. This subject also connects back to the start of the guide: what you learn here improves how you frame the next problem.

6 moves: Hypothesis · Small experiment · Shorten the feedback loop · Decision journal · Lessons file · Retrospective


16.1 Hypothesis#

In one line: Write your idea as a clear guess you can test: "If I do X, then Y will happen, because Z."

The idea. A hypothesis (say: hy-POTH-uh-sis) is a guess written so that reality can say yes or no. "Make the app better" cannot be tested. "If I add a weak-topics quiz, then students who use it will do 20% more quizzes per week, because they see their progress" can be tested. After testing, you learn something either way.

Template:

If [I do this], then [this will happen], because [reason]. I will know by [measure] after [time].

How to do it:

  1. Fill in the template before building.
  2. Decide the measure before you see results (otherwise you choose the measure that looks good).
  3. After the time, check: yes or no? Why?

Example:

  • ❌ "Let's add streaks to the app. Students will like it."
  • ✅ "Help me write this as a hypothesis: If I add daily streaks, then students will return more days per week, because they won't want to lose their streak. How should I measure this, and after how long?"

Say this:

"Turn my idea into a hypothesis: if [...], then [...], because [...]. How will I measure it, and when?"

Careful: A failed hypothesis is not a failure. It is learning. The only real failure is not knowing what happened. Connect this with Falsification (8.3) and Goodhart's law (10.4).


16.2 Small experiment (small bets)#

In one line: Test an idea in the smallest, cheapest way before you build the full version.

The idea. Building a full feature to test an idea is expensive. Often you can learn the same thing in a few hours. For example:

  • Add a button "Download as PDF — coming soon" and count clicks, before building PDF export.
  • Offer a new service to 3 clients by message, before building a full service page.
  • Test the new topics system on one subject, before all subjects (see 6.4 Gall's law).

How to do it:

  1. Write the hypothesis (16.1).
  2. Ask: "What is the cheapest way to test this?"
  3. Run the small test. Decide: build, change, or drop.

Example:

  • ❌ "Build a full mock-exam mode with timer, ranking, and certificates."
  • ✅ "I want to test if students want a full mock-exam mode. What is the cheapest experiment to check this, in under 2 days of work, before building the full feature?"

Say this:

"What is the smallest, cheapest experiment to test this idea before I build the full version?"

Careful: Be honest with users. A "coming soon" button is fine. Pretending a feature exists, or taking money for something that does not exist, is not.


16.3 Shorten the feedback loop#

In one line: Make the time between "I did something" and "I see the result" as short as possible.

The idea. Feedback = information about the result of your action. If you learn the result in 1 minute, you can try 50 ideas in a day. If you learn it in 1 month, you can try 12 a year. Fast feedback makes everything better: learning, coding, business.

Examples of shorter loops:

  • Code: fast local preview, automatic tests, small steps (12.7).
  • Agent work: ask for a small draft first, then improve (not one giant final answer).
  • Business: talk to 5 users this week instead of waiting for analytics in 3 months.
  • Client work: show a rough page on day 3, not a finished site in week 4.

How to do it:

  1. Find your slowest loop: where do you wait longest to see results?
  2. Ask: "How can I see this result sooner, even if roughly?"
  3. Change the process.

Example:

  • ❌ "Build the full redesign, then I'll review it."
  • ✅ "Before building the full redesign, show me a rough version of one page within this session, so I can give feedback early. Then continue."

Say this:

"How can I see the result sooner, even in a rough form? Show me an early draft before the full version."

Careful: A fast loop with bad information is useless. The feedback must still be real (real users, real tests).


16.4 Decision journal#

In one line: When you make an important decision, write down what you decided, why, and what you expect. Check it later.

The idea. Our memory changes after the result is known. This is called hindsight bias: "I knew it would fail." But you did not. A journal shows what you really thought at the time. Then you learn if the problem was a bad decision, or a good decision with bad luck. These are very different.

What to write (5 lines):

  1. Date and decision.
  2. Options I considered.
  3. Why I chose this.
  4. What I expect to happen, and how sure I am (1.2).
  5. Review date.

How to do it:

  1. Write the 5 lines (the agent can help you write them at the end of a decision chat).
  2. Save them in one file.
  3. On the review date, compare: what happened vs. what I expected.

Example:

  • ✅ "We just decided to use Sanity for the PPSC question bank. Write a decision journal entry: decision, options considered, reasons, what I expect, how sure I am, and a review date in 3 months."

Say this:

"Write a decision journal entry for this: decision, options, reasons, what I expect, confidence, and a review date."

Careful: Only for important decisions. Not for every small choice.


16.5 Lessons file (turn mistakes into rules)#

In one line: Keep one file of lessons and rules. Every time something goes wrong, add the lesson, and give the file to the agent.

The idea. A lesson you only "remember" will be forgotten. A lesson written as a rule, in a file the agent reads, works every time. Many agent tools read a project instructions file automatically (for example, a file like CLAUDE.md in your project). This is a leverage point (7.4): one line can prevent the same mistake in every future chat.

Good lesson format: a rule, plus the reason.

  • ✅ "Never change product URLs without adding redirects. Reason: a client lost Google ranking in March."
  • ❌ "Be careful with URLs." (Too vague to follow.)

How to do it:

  1. After a post-mortem (14.8) or a mistake, write 1 to 3 rules.
  2. Add them to your lessons file or project instructions file.
  3. Every few months, clean it: remove old rules, merge duplicates.

Example:

  • ✅ "From this post-mortem, write 3 short rules for my project instructions file. Each rule: what to always or never do, and a one-line reason."

Say this:

"Turn this lesson into a short rule with a one-line reason, so I can add it to my project instructions."

Careful: Too many rules = the agent ignores them, and so do you. Keep the file short. Each rule must be specific.


16.6 Retrospective (keep, stop, start)#

In one line: After a project or a period of work, ask three questions: What should I keep? What should I stop? What should I start?

The idea. Retro = looking back. A post-mortem (14.8) is for one failure. A retrospective is for any project, also the successful ones. Successful projects teach a lot too, but we rarely study them. Three simple questions make it fast.

How to do it:

  1. At the end of a project (or every month), list:
    • Keep: what worked well?
    • Stop: what wasted time or caused problems?
    • Start: what should I try next time?
  2. Move important items to your lessons file (16.5).
  3. Choose one "start" item and actually do it on the next project.

Example:

  • ✅ "I just delivered the dental clinic website. Help me do a retrospective: what should I keep, stop, and start in how I work with clients and with my AI agent? Ask me questions first."

Say this:

"Help me do a retrospective on this project: keep, stop, start. Ask me questions first."

Careful: Do not make 15 "start" items. You will do none of them. Pick one or two.


✏️ Practice: Subject 16#

  1. Create a lessons file today, with 3 rules from your past projects (16.5).
  2. Write one hypothesis (16.1) for a feature you are planning, and design a small experiment (16.2) to test it.
  3. Put a monthly retrospective (16.6) in your calendar.

Part 7: Playbooks#

A field is not only a list of moves. It is knowing which moves to use, in which order, for a real situation. Each playbook gives you that order, plus a ready prompt.

How to use a playbook:

  1. Find your situation.
  2. Follow the moves in order. You can skip a step if it clearly does not apply.
  3. Copy the ready prompt. Replace the parts in [brackets].
# Situation
P1 My solution did not turn out well
P2 I have an idea, but I cannot explain it
P3 I want to build something new, "the way it should be"
P4 Something is broken (a bug)
P5 I must choose between options (tools, approaches)
P6 I want to test a plan before I build it
P7 I am about to make a big or risky code change
P8 The agent says "done"
P9 The agent is going in circles
P10 A project is finished: learn from it

Playbook P1: My solution did not turn out well#

Use when: you built something, and it works badly, or it does not solve the real problem.

The danger: you say "this was bad, fix it", and the agent patches your bad design (anchoring), or you throw everything away and lose the good parts.

Moves in order:

Step Move Why
1 14.2 Expected vs. observed Say clearly what you wanted and what you got.
2 14.6 Five Whys + 14.7 Root & contributing causes Find why it failed: wrong idea, or wrong execution?
3 2.3 Sunk cost + 2.5 IKEA effect Make sure your effort and pride do not decide for you.
4 11.6 Fresh start Open a new chat, so the agent is not anchored on the old solution.
5 6.1 First principles Design the ideal from the real goal.
6 6.6 Clean-slate comparison Compare the ideal with your current solution.
7 6.2 Chesterton's fence + 6.5 Salvage audit Keep what is good, and what exists for a reason.
8 6.7 Patch vs. rebuild Decide with reasons.
9 6.4 Gall's law Start the new version small.
10 16.5 Lessons file Save the lesson as a rule.

Ready prompt, part A (in the old chat, or with your notes):

My solution for [problem] did not turn out well. We are in thinking mode: do not write code. Goal: [what I wanted to achieve]. Expected: [what should have happened]. Observed: [what actually happened]. Do a Five Whys to find the root cause, and list contributing causes. Tell me clearly: was the core idea wrong, or only the execution? Ignore the time I already spent on it.

Ready prompt, part B (in a new chat):

I need to design [feature] well. We are in thinking mode: no code yet. Goal: [goal]. Hard constraints: [...]. Scale: [...]. Non-goals: [...]. Lessons from a previous attempt that failed: [root cause from part A].

  1. Use first principles: design the ideal solution from the goal and basic truths. Do not ask to see my old version yet.
  2. When I paste my old version, do a clean-slate comparison in a table: ideal, current, gap, effort.
  3. Then do a salvage audit (Keep / Fix / Drop). Before dropping anything, explain why it might exist (Chesterton's fence).
  4. Recommend patch or rebuild, with evidence, and the smallest first version that works end-to-end.

Playbook P2: I have an idea, but I cannot explain it#

Use when: you feel the idea clearly, but your words come out vague.

Moves in order:

Step Move Why
1 1.4 Thinking by writing Get everything out of your head, in any order.
2 1.5 Interview me Let the agent pull the idea out with questions.
3 1.3 Explain it simply Find the parts that are still unclear.
4 1.1 Know / think / don't know Separate facts from guesses.
5 3.3 Problem statement Turn it into a clear foundation.
6 12.1 Restate Check that the agent got it right.

Ready prompt:

I have an idea that is still fuzzy in my head, and I cannot explain it well. Here is a messy brain dump: [brain dump]. Do not solve anything. Interview me: ask one question at a time until you understand the idea. Then:

  1. Write a summary of my idea in simple words.
  2. Sort what I said into: what I know, what I think, and what I don't know.
  3. Write a short problem statement: who, what, why, today, and how we know it's solved. I will correct your summary before we do anything else.

Playbook P3: I want to build something new, "the way it should be"#

Use when: you are starting a new feature, product, or project, and you want a strong foundation.

Moves in order:

Step Move Why
1 3.3 Problem statement + 3.4 Job to be done Know the real problem and the user's real job.
2 3.5 Constraints + 3.6 Non-goals + 3.7 Scale Set the borders.
3 11.1 Thinking mode No code until the plan is right.
4 11.2 Diverge: 5.1 Expanding + 5.5 Boring solution See many options, including the simple one.
5 6.1 First principles Design from what must be true.
6 8.4 Pre-mortem Find how it could fail, before building.
7 11.2 Converge: 9.1 Criteria first + 9.2 Trade-offs Choose with clear reasons.
8 6.4 Gall's law + 10.3 YAGNI Start with the smallest version that works.
9 12.4 Acceptance criteria + 12.7 Task breakdown Turn the plan into clear, small tasks.

Ready prompt:

I want to build [feature] for [project]. Thinking mode: no code yet. Problem: [who] needs [what] because [why]. Job to be done: when [situation], they want to [motivation], so they can [result]. Hard constraints: [...]. Soft constraints: [...]. Scale: now [n], in 12 months [n]. Non-goals: [...].

  1. Give me the boring solution and 3 really different alternatives. Do not choose yet.
  2. Then use first principles to describe what the ideal design must include.
  3. Do a pre-mortem: imagine it failed in 6 months. Top 5 reasons.
  4. Compare the options on my criteria: [criteria, in order]. Show trade-offs. Recommend one.
  5. Describe the smallest version that works end-to-end. Leave out anything I don't need now (YAGNI).

Playbook P4: Something is broken (a bug)#

Use when: something does not work the way it should.

Moves in order:

Step Move Why
1 14.2 Expected vs. observed Describe the gap with facts.
2 14.3 Reproduce first Make the bug happen on purpose.
3 14.4 What changed? Most bugs come from a recent change.
4 10.2 Occam's razor Check the simplest cause first.
5 14.5 Divide and conquer If still not found, cut the area in half.
6 14.1 Symptom vs. cause Make sure the fix targets the cause.
7 13.5 Minimal change Fix with the smallest edit.
8 15.1 Evidence + 15.2 Regression check Prove it is fixed, and nothing else broke.

Ready prompt:

Something is broken. Expected: [...]. Observed: [...]. Steps: [...]. It last worked on [date, if known]. Do not change code yet.

  1. Reproduce the bug and show me the steps and the wrong result.
  2. Check what changed since it last worked. Check the simplest causes first.
  3. Tell me the cause (not only the symptom) and your evidence.
  4. After my OK, fix it with the smallest possible change.
  5. Show evidence that it is fixed, run the same steps again, and do a regression check on: [related features].

Playbook P5: I must choose between options#

Use when: you are choosing a tool, a library, an approach, a supplier, or how to spend your time.

Moves in order:

Step Move Why
1 3.5 Hard constraints Remove options that cannot work.
2 9.4 Reversible vs. irreversible Decide how careful to be.
3 9.7 Satisficing vs. maximizing Decide how long to search.
4 9.1 Criteria first Decide how to judge, before seeing options.
5 9.2 Trade-off + 9.3 Opportunity cost See the real costs.
6 10.6 Lindy effect For long-term parts, prefer proven tools.
7 8.2 Steelman Give the losing option a fair chance.

Ready prompt:

I need to choose [what]. Hard constraints: [...]. This decision is [easy / hard] to undo. My criteria, most important first: 1) [...] 2) [...] 3) [...]. Compare [2–4] options only on these criteria, in a table. For each, tell me what I gain and what I give up. Say how long each tool has existed and if it is still maintained. Recommend one. Then steelman the best option you did not recommend.

(For an easy-to-undo choice, add: "Good enough means [...]. Give me the first option that meets this.")


Playbook P6: I want to test a plan before I build it#

Use when: you have a business or product plan (for example, a paid plan, a new service, a new feature), and you want to know if it is good before spending time.

Moves in order:

Step Move Why
1 2.8 Sycophancy (hide your opinion) Get an honest review.
2 1.1 Know / think / don't know Separate facts and guesses.
3 9.5 Base rate Compare with what usually happens.
4 8.4 Pre-mortem Imagine it failed. Why?
5 8.1 Weakest assumption Find the belief most likely to break the plan.
6 7.1 Second-order effects See the effects after the first effect.
7 16.1 Hypothesis + 16.2 Small experiment Test cheaply before building.

Ready prompt:

A colleague proposed this plan: [plan]. Review it honestly, as a strict and experienced advisor. If it is good, say why.

  1. What is the base rate: what usually happens to plans like this?
  2. Do a pre-mortem: it failed after 6 months. Give the 5 most likely reasons.
  3. What is the weakest assumption?
  4. List the second-order effects.
  5. Write the plan as a hypothesis, and design the cheapest experiment to test the weakest assumption in under one week.

Playbook P7: I am about to make a big or risky code change#

Use when: the change touches shared code, the database, login, payments, or real user data.

Moves in order:

Step Move Why
1 13.6 Inspect before changing The agent must understand the code first.
2 13.1 Blast radius + 13.2 Coupling Know what could break.
3 13.3 Invariants Name the rules that must never break.
4 9.4 Reversible vs. irreversible Plan a backup and a way back.
5 12.7 Task breakdown Small, testable steps.
6 12.8 Stop conditions Where the agent must ask, not guess.
7 12.5 Definition of done What "finished" means.

Ready prompt:

I want to [change]. This is a risky change. Do not change any file yet.

  1. Inspect the code. Tell me which files are involved and how they work now.
  2. Tell me the blast radius and any coupling: what uses this code, and what else must change.
  3. Invariants that must always stay true: [...].
  4. Is this reversible? Plan a backup and a way back.
  5. Break the work into small steps, each testable alone. Wait for my OK, then do one step at a time. Stop and ask me if: you need to delete or overwrite data, change files outside [area], or a test fails twice. Done means: [your definition of done].

Playbook P8: The agent says "done"#

Use when: the agent reports that the work is finished.

Moves in order:

Step Move Why
1 15.1 Evidence Proof, not claims.
2 15.3 Diff review See what really changed.
3 15.4 Smoke test The main path still works.
4 15.2 Regression check Nothing nearby broke.
5 15.5 Fresh-eyes review For important work: a new chat reviews it.

Ready prompt:

Before I accept this:

  1. Show evidence: what you ran and the results. List what you could not check.
  2. Show the full diff, with one reason per change. Mark anything outside the task and anything deleted.
  3. Run a smoke test: [main path steps]. Pass or fail for each.
  4. Do a regression check on: [features near the change].
  5. Check each acceptance criterion: yes or no.

Playbook P9: The agent is going in circles#

Use when: the agent repeats mistakes, tries the same fix again and again, or the quality drops.

Moves in order:

Step Move Why
1 2.10 Context drift Check if the chat is too long or messy.
2 1.6 Notice confusion What exactly keeps repeating?
3 3.2 XY problem Maybe the approach itself is wrong.
4 11.6 Fresh start Start clean with a summary.
5 2.1 Anchoring In the new chat, give the goal first, not the failed attempts.
6 11.5 Think first, answer second Make the agent reason before acting.

Ready prompt, in the old chat:

Stop. We are going in circles. Write a summary for a new chat: the goal, what we tried, why each attempt failed, the constraints, and the open questions. Also tell me: is it possible that our whole approach is wrong?

Ready prompt, in the new chat:

Goal: [...]. Constraints: [...]. Attempts that failed, and why: [list from the summary]. Do not repeat these. Before you answer, think step by step: consider at least 3 different approaches, including one completely different from the failed ones. Then recommend one, with your reason. Do not write code until I agree.


Playbook P10: A project is finished: learn from it#

Use when: you delivered a project, launched a feature, or finished a month of work. Successful or not.

Moves in order:

Step Move Why
1 16.6 Retrospective Keep, stop, start.
2 14.8 Blameless post-mortem Only if something went wrong.
3 16.4 Decision journal Compare what you expected with what happened.
4 16.5 Lessons file Turn lessons into rules.
5 7.4 Leverage point Update your project instructions, so every future chat improves.

Ready prompt:

I just finished [project]. Help me learn from it. Ask me questions first, one at a time. Then:

  1. Do a retrospective: what should I keep, stop, and start?
  2. If something went wrong, write a short blameless post-mortem.
  3. Compare with my decision journal: [paste entries, if any]. Were my expectations right?
  4. Write at most 3 rules for my lessons file, each with a one-line reason.

Part 8: Cheat sheets#

Master cheat sheet: all 103 moves#

Part 1: Your own mind#

# Move In one line
1.1 Know / think / don't know Sort beliefs into: I know, I think, I don't know.
1.2 Confidence level Say how sure you are. Ask the agent too.
1.3 Explain it simply (Feynman test) Where simple words fail, your understanding is weak.
1.4 Thinking by writing Write messy thoughts down before you ask.
1.5 Interview me The agent asks you questions until the idea is clear.
1.6 Notice confusion A surprise is a signal. Stop and look.
2.1 Anchoring The first idea pulls all later thinking toward it.
2.2 Confirmation bias You see proof that agrees with you, and miss the rest.
2.3 Sunk cost trap Continuing only because of past effort.
2.4 Status quo bias Preferring no change only because change feels risky.
2.5 IKEA effect You value what you built more than it deserves.
2.6 Availability trap Easy to remember is not the same as common.
2.7 Planning fallacy Tasks take longer than planned.
2.8 Sycophancy The agent agrees to please you, not because you are right.
2.9 Typical-answer default The agent gives the common answer, not the best one for you.
2.10 Context drift In long chats, the agent forgets earlier rules.

Part 2: Understanding the problem#

# Move In one line
3.1 Goal vs. proposed solution Separate what you want from how you planned to do it.
3.2 XY problem You ask about your attempt (Y), not your real problem (X).
3.3 Problem statement Who, what, why, today, and how we know it is solved.
3.4 Job to be done What progress does the user "hire" this for?
3.5 Constraint (hard vs. soft) A limit. Hard = cannot break. Soft = can bend.
3.6 Non-goal What NOT to do in this task.
3.7 Scale The size of the problem, in numbers.
3.8 Assumption A belief you have not checked.
4.1 Ambiguity A word with more than one meaning.
4.2 Glossary Your key words and their exact meaning.
4.3 Operational definition A vague word turned into a measurable check.
4.4 Example and counter-example One thing that fits, one that does not.
4.5 One name per thing One word for one thing, always.

Part 3: Finding solutions#

# Move In one line
5.1 Expanding the solution space Collect many different options before choosing.
5.2 Inversion Ask how to guarantee failure, then avoid it.
5.3 Reframing The same problem, from a new angle.
5.4 Removing a constraint Imagine a limit is gone, then keep what you can.
5.5 The boring solution The simplest, proven way. Your baseline.
5.6 Borrow from another field How did another field solve this already?
6.1 First principles Build up from basic truths, ignoring how it is done today.
6.2 Chesterton's fence Know why something exists before removing it.
6.3 Essential vs. accidental complexity Keep the problem's difficulty. Remove the difficulty we created.
6.4 Gall's law Start with a simple system that works, then grow.
6.5 Salvage audit Sort old parts into Keep, Fix, Drop.
6.6 Clean-slate comparison Design fresh, then compare with the current version.
6.7 Patch vs. rebuild Wrong idea → rebuild. Bad execution → patch.
7.1 Second-order effects Ask "and then what?"
7.2 Feedback loops Results that cause more (or less) of themselves.
7.3 Bottleneck The slowest part limits everything. Fix only that.
7.4 Leverage point A small change with a big effect.

Part 4: Choosing#

# Move In one line
8.1 Weakest assumption The unchecked belief most likely wrong and most damaging.
8.2 Steelman The strongest, fairest case for the option you did not choose.
8.3 Falsification Try to prove your idea wrong.
8.4 Pre-mortem Imagine it already failed. Why?
9.1 Criteria first Decide how to judge before you see the options.
9.2 Trade-off What each option gives and takes.
9.3 Opportunity cost The best other thing you give up.
9.4 Reversible vs. irreversible Easy to undo vs. hard to undo.
9.5 Base rate What usually happens to cases like this?
9.6 Expected value How good × how likely. Also check the worst case.
9.7 Satisficing vs. maximizing Good enough vs. the very best.
9.8 Regret minimization Which choice will future you regret less?
10.1 The 80/20 rule A few causes give most of the results.
10.2 Occam's razor Check the simplest explanation first.
10.3 YAGNI Don't build it until you really need it.
10.4 Goodhart's law When a number becomes the target, it stops measuring well.
10.5 Hofstadter's law It always takes longer than you expect.
10.6 Lindy effect Tools that lasted long will probably last longer.

Part 5: Doing the work#

# Move In one line
11.1 Thinking mode vs. doing mode Talk first. Build only when you say so.
11.2 Diverge, then converge First many ideas, then choose. Never both at once.
11.3 Socratic mode The agent asks questions so you find the answer.
11.4 Give the agent a role Tell it who to be: reviewer, user, client.
11.5 Think first, answer second Reason step by step before the final answer.
11.6 Fresh start A new chat with a clean summary.
12.1 Restate in your own words The agent repeats your request before starting.
12.2 What information is missing? The agent lists what it does not know.
12.3 Level of detail Idea, design, or code.
12.4 Acceptance criteria Yes/no checks that decide if the work is accepted.
12.5 Definition of done The general checklist before "finished".
12.6 Example-driven spec Input → output examples that show the rule.
12.7 Task breakdown Small steps, each testable alone.
12.8 Stop condition When the agent must stop and ask.
13.1 Blast radius How much breaks if this goes wrong.
13.2 Coupling How strongly parts depend on each other.
13.3 Invariant A rule that must always stay true.
13.4 Edge case An unusual situation where code breaks.
13.5 Minimal change The smallest edit that solves it.
13.6 Inspect before changing Read and report first. Edit after your OK.

Part 6: Checking and learning#

# Move In one line
14.1 Symptom vs. cause Fix why it happens, not only what you see.
14.2 Expected vs. observed What should happen vs. what happens.
14.3 Reproduce first Make the bug happen again, with exact steps.
14.4 What changed? It worked before. What is different now?
14.5 Divide and conquer Cut the area in half, test, repeat.
14.6 Five Whys Ask "why?" about 5 times to reach the real cause.
14.7 Root vs. contributing causes The main cause, and what made it possible or worse.
14.8 Blameless post-mortem Study what went wrong, without blame.
15.1 Evidence (not claims) Proof you can see, not "it works".
15.2 Regression check Old things still work.
15.3 Diff review Read exactly which lines changed.
15.4 Smoke test A fast check of the main path.
15.5 Fresh-eyes review A new chat reviews the work.
16.1 Hypothesis If X, then Y, because Z. Measured by M.
16.2 Small experiment Test the idea cheaply before building fully.
16.3 Shorten the feedback loop See results sooner.
16.4 Decision journal Write what you decided and expected. Check later.
16.5 Lessons file Turn mistakes into written rules the agent reads.
16.6 Retrospective Keep, stop, start.

Which move should I use?#

My situation Moves to try Playbook
My idea is not clear in my head 1.4 · 1.5 · 1.3 · 1.1 P2
My prompt is vague 3.1 · 3.5 · 3.6 · 4.3 · 4.2 —
My solution did not turn out well 14.6 · 2.3 · 6.1 · 6.5 · 6.7 P1
I want to build something "the right way" 3.3 · 6.1 · 6.4 · 8.4 P3
Something is broken 14.2 · 14.3 · 14.4 · 14.5 P4
I must choose between options 9.1 · 9.2 · 9.3 · 9.4 P5
I am not sure my plan is good 8.1 · 8.4 · 9.5 · 16.2 P6
I want to change real code 13.6 · 13.1 · 13.3 · 12.7 P7
The agent says "done" 15.1 · 15.3 · 15.4 · 15.2 P8
The agent goes in circles 2.10 · 11.6 · 3.2 · 11.5 P9
A project is finished 16.6 · 14.8 · 16.5 P10
The agent always agrees with me 2.8 · 11.4 · 15.5 · 8.2 —
The agent improves my bad idea instead of questioning it 2.1 · 6.1 · 6.6 · 11.6 —
The agent does extra things 3.6 · 13.5 · 12.8 · 10.3 —
The answer is too complex 5.5 · 3.7 · 10.3 · 6.4 —
The answer is too generic 2.9 · 3.7 · 3.5 · 3.4 —
I need new ideas 5.1 · 5.3 · 5.2 · 5.6 —
I am afraid to change something 2.4 · 9.4 · 16.2 —
I keep making the same mistake 14.8 · 16.5 · 16.6 —
Words keep meaning different things 4.1 · 4.2 · 4.5 —
The answer is too long or too deep 12.3 · 11.1 —
My time estimates are always wrong 2.7 · 10.5 · 9.5 —
A change could affect many things 7.1 · 13.1 · 13.2 —

Pairs that are easy to confuse#

These two... ...are different because
Goal (3.1) vs. Constraint (3.5) A goal is what you want to reach. A constraint limits how you may reach it.
Constraint (3.5) vs. Non-goal (3.6) A constraint limits HOW. A non-goal limits WHAT.
Constraint (3.5) vs. Invariant (13.3) A constraint is a limit from outside. An invariant is a rule inside the system.
Interview me (1.5) vs. Missing information (12.2) vs. Socratic mode (11.3) Interview me pulls out an unclear idea. Missing information is one list at the start of a clear task. Socratic mode challenges your thinking so you find the holes yourself.
Goal vs. solution (3.1) vs. XY problem (3.2) 3.1 is for planning. XY is for when you are already stuck on your approach.
Restate (12.1) vs. Reframe (5.3) Restating keeps the same meaning. Reframing changes the angle.
Inversion (5.2) vs. Pre-mortem (8.4) Inversion gives rules to avoid. A pre-mortem tells the story of one project's failure.
Pre-mortem (8.4) vs. Post-mortem (14.8) Before you build vs. after it failed.
Falsification (8.3) vs. Verifying (Subject 15) Falsification looks for the "no" that breaks an idea. Verifying checks that work is correct.
Boring solution (5.5) vs. Gall's law (6.4) vs. Minimal change (13.5) Boring = a proven approach. Gall's law = start small and grow. Minimal change = a small code edit.
Sunk cost (2.3) vs. Status quo bias (2.4) Sunk cost looks at past effort. Status quo bias is fear of change.
Trade-off (9.2) vs. Opportunity cost (9.3) A trade-off is inside one option. Opportunity cost is between options.
Blast radius (13.1) vs. Reversibility (9.4) How much breaks vs. how hard it is to undo.
Coupling (13.2) vs. Blast radius (13.1) Coupling is the cause (connections). Blast radius is the effect (what breaks).
Blast radius (13.1) vs. Regression check (15.2) A prediction before the change vs. a test after it.
Smoke test (15.4) vs. Regression check (15.2) Wide and shallow vs. narrow and targeted.
Acceptance criteria (12.4) vs. Definition of done (12.5) For this feature vs. for every task.
Example-driven spec (12.6) vs. Example and counter-example (4.4) Input → output for rules vs. examples of meaning or style.
Ambiguous (4.1) vs. Vague (4.3) Two exact meanings (needs a choice) vs. not exact enough (needs a number).
Glossary (4.2) vs. One name per thing (4.5) The definitions vs. the habit of using them.
Level of detail (12.3) vs. Thinking mode (11.1) How zoomed in the answer is vs. whether the agent acts or only talks.
Symptom (14.1) vs. Root cause (14.7) What you see vs. the main reason it happens.
Post-mortem (14.8) vs. Retrospective (16.6) One failure vs. any project, also successful ones.

Your daily habit (one minute before every important chat)#

Before you send an important prompt, ask yourself four questions:

  1. Is my idea clear in my own head? If not → Subject 1 (Interview me).
  2. Did I give the goal, not only my solution? → 3.1
  3. Am I showing the agent something that will anchor it? → 2.1
  4. How will I know the work is really done? → 12.4, 15.1

End of guide. This is your primary source. Come back to any subject, any time. Learn a few moves, use them in real chats, and add your own lessons to your lessons file (16.5). That is how a toolkit becomes a skill. 📚