Tutorial 4 Prompting and Reviewing

Tutorial 4 · Prompting and Reviewing

Goal: the meta-skill. You can now build a feature with an agent — this chapter is about doing it smoothly and repeatably: writing prompts that land the first time, reviewing diffs efficiently, iterating when things go sideways, and keeping momentum across sessions.

← Prev: Tutorial 3 Your First Agent Task · Next: Tutorial 5 Localization

---

Prompt like a lead, not a search box

The agent is a fast, literal, eager junior engineer. Lead it the way you'd lead a good one:

• State the goal and the constraints. "Add endorse" is weak. "Add endorse following the connect pattern, seeded RNG only, with tests, gate stays green" is strong. Constraints are how you get code that fits.
• Point at examples. "Follow the pattern used by renderConnect" beats a paragraph of description. Existing code is the best spec.
• Ask for a plan before edits on anything non-trivial. Cheap to redirect a plan; expensive to unwind ten edited files.
• One task per prompt. Bundling "add endorse, also refactor the RNG, also update the README" produces a tangled diff that's hard to review.
• Give it the test gate. "Run npm test and don't consider it done until it's green" turns the agent into something that checks its own work.

Review the diff every time

Speed is the whole point of an agent — but unread speed is how bugs ship. Build a quick, consistent review reflex:

1. Scope: did it change only what it should? Unrelated moved lines are a smell.
2. Patterns: does it match the surrounding code, with no new dependencies and no I/O inside src/?
3. The project's rules: for this repo, that's seeded RNG only (grep the diff for Math.random), user-visible text in the language bundles (not hardcoded), and card lines never exceed the width the layout pads to.
4. Accessibility: does new output survive --accessible? Run lockedin --accessible <your command> and check it reads as clean plain text — no new decorative glyphs sneaking past a11yFilter.
5. Tests: is there a new test, and would it actually fail if the feature broke? Ask: "What line would I change to make this new test fail?"
6. Run it: npm test, then run the command and look at the output.

You don't need to understand every character — but you must understand every decision. If you can't explain a change, ask the agent to explain it before you accept it.

Iterate when it's not green

A red gate is a normal step, not a failure. The fix is precise feedback:

"npm test fails with: [paste the exact error]. The renderEndorse width test expects every card line ≤ 60 visible columns. Fix it without weakening the test."

Paste the actual error text. "It's broken" makes the agent guess; the stack trace makes it fix. And prefer to continue the same conversation rather than starting fresh — the agent already has the context of what it just wrote. If two or three iterations don't converge, step back and re-scope: the task may be too big for one prompt.

Keep momentum across sessions

Real work spans more than one sitting. Two habits keep an agent effective over time:

• Memory / conventions. If your agent supports durable memory or a project instructions file, record the rules it should always follow here (e.g. "all randomness must use pick/shuffle", "run npm test before declaring done"). You state a convention once instead of every prompt.
• A handoff note. This repo keeps a short, sanitized status doc at docs/HANDOFF.md: what the project is, how it's built, how it's tested, and what's next. When you return (or hand off to a teammate — or another agent), that note rebuilds context in seconds. Ask your agent to keep it up to date as part of a change.

Guardrails worth keeping

• The gate is non-negotiable. Green tests before anything ships. It's what lets you move fast and trust the output.
• You are the reviewer of record. The agent writes; you decide. Accepting a diff means you vouch for it.
• Small, verifiable steps beat one giant leap. Each accepted change should leave the app working.

---

✅ Try it with your agent

1. Write a one-paragraph spec for a mentor command ("dispenses unsolicited advice"), including constraints, and have the agent build it test-first — plan, tests, code, gate — reviewing at each step.
2. Ask the agent to update docs/HANDOFF.md to mention the new command.
3. Deliberately break something (e.g. delete a pool entry), run npm test, and practice feeding the agent the exact failure to fix.

---

Where to go next

• Skim the real code in src/lockedin.js — you now know the shape of it.
• Read docs/HANDOFF.md for the project's own status and architecture notes.
• Enjoy the jokes in the Command Reference.

That's the tutorial. You can now direct an AI agent to build and change real software behind a test gate — using the most over-confident example imaginable. Agree? 👇