W02: Asking Well: Requests, Context, Pi's Memory

A carpenter who gets a note saying "make a table" will make a table. Maybe round, maybe too tall, maybe in the wrong wood. A good work order says what it is for, how big, and how you will check it: "a table for four, 75 cm high, it must not wobble". Your requests to Pi are work orders. This lesson makes them sharp, shows what Pi can see when it reads them, and gives Pi a notebook of standing instructions.

One Request, One Job

Each message you send in a project's chat becomes one request. The harness gives each request its own task file and, when it is verified, its own snapshot (W03). So keep one job per request:

Small requests are easier for Pi to finish, easier for the harness to verify, and easier for you to undo.

The Four Levers, for an App

A03 taught four levers: task, audience, format, constraints. For an app, they become:

If you are unsure what you want, ask for options first: "Give me three ways to show the date, and do not change any code yet."

What Pi Sees

Pi only knows what is in front of it (A04). With each request, the harness picks a small set of files for Pi: the plan (ROADMAP.md and the open tasks), the file you have open, files you mention by name, and a few related ones. It keeps this small on purpose, about 4,000 tokens, so Pi stays focused.

You can see the list before you send. Under the chat box, the line "Pi sees:" names each file. After an answer, "Also read:" lists the files Pi opened by itself.

So the best trick is simple: name the file.

When Pi gets something wrong because it "did not know", look at the "Pi sees:" line first. The missing fact was probably not there.

Comments: Asking About One Passage

You do not have to ask everything in the chat. In the Work view, select some text in a file and choose Comment (⇧⌘M). Write your question and choose Ask Pi. The answer appears in that comment's thread, attached to the file, and it does not use up the project chat. Ask Pi about this whole file, at the bottom of Review, does the same for the entire page.

This is great for "what does this line do?" and "explain this file to a beginner".

Pi's Memory: AGENTS.md

A05 introduced AGENTS.md: a plain text file of standing instructions the assistant reads every time. Pi Workbench keeps a shared one at ~/pi-local-harness-data/AGENTS.md. The harness reloads it before every request, so a change applies to your next message.

Good things to put there:

# About me
I am new to programming. Explain each change in two plain sentences.
When you change a page, tell me which address to open to see it.
Answer in Japanese, but keep code and file names in English.

Pi also adds short lessons to it after a confirmed mistake, so the same mistake is less likely next time. Read it now and then, and delete anything wrong. Keep it short: every line costs Pi attention on every request.

Never put secrets there. It is sent to the model with every request.

Keep the Conversation Clean

Each project has one chat, and Pi remembers it. That is useful, but a long chat full of abandoned ideas confuses a small model. When you change topic completely, say so: "New topic: forget the date idea." And when a request goes badly, a fresh, better request often beats five corrections.

Pi Workbench will soon show the right KakkoiSchool lesson under Pi's answer the first time you meet an idea, like "New to git? Lesson T19, 10 minutes". Until then, this course links them for you.

This Week's Exercise

  1. Take one thing you want from an app. Write the lazy one-line version.
  2. Rewrite it with the four levers: what, how you will know, where, what not to change.
  3. In your hello project, open ROADMAP.md, type a request in the chat, and read the "Pi sees:" line before sending. Is the right file there?
  4. Open ~/pi-local-harness-data/AGENTS.md in a text editor and add two lines about how you like answers.

Key Takeaways

  • Each message is one request with its own task and snapshot: one job per request
  • Say what it should do, how you will know it works, where, and what not to change
  • Pi sees only a small set of files: check the "Pi sees:" line, and name the file when you can
  • Comments ask Pi about one passage without using up the chat
  • AGENTS.md holds standing instructions, reloaded before every request. Keep it short, and never put secrets in it