Levels of detail

when one line is enough and when you need a mini-spec

What it is

A detailed prompt is not always better than a short one. On a small change a mini-spec costs ten minutes instead of one; on a large task one short line turns into an hour of rework.

The level is chosen not by the size of the task but by the cost of being wrong: what it costs to get the wrong thing. This article gives a rule that picks the level in a couple of seconds.

What it looks like in code

Three levels, short to detailed.

Level 1. One line

For changes you can see with your eyes and roll back easily.

Rename get_data to fetch_weather throughout the file.

Add logging at the start of every handler.

Checking takes seconds: look at the diff, accept or roll back. There is nothing to spell out.

Level 2. A paragraph

The workhorse. An ordinary feature that has to fit into existing code.

In handlers/weather.py add a 10-minute cache of weather replies
so we don't hit the API on every request. Keep it in memory,
a dict keyed by city name. Don't add new dependencies.

All four parts of a prompt are already here, just compressed into three lines. This is enough in most cases.

Level 3. A mini-spec

For tasks that touch several files, change the shape of the data, or are hard to roll back.

Task: move subscription storage from a JSON file to SQLite.

Context: subscriptions currently live in data/subs.json and are read
by load_subs() in storage.py. There are five calls to load_subs and
save_subs in the project, all in handlers/.

What is needed:
- a subscriptions table: user_id, city, created_at
- the same load_subs/save_subs functions, signatures unchanged,
  so the handlers don't have to be touched
- migration: on first start, move the data out of the JSON and
  rename the file to subs.json.bak

Constraints:
- plain sqlite3 only, no ORM
- don't change the handlers at all

Done when: the bot starts on an empty database, subscriptions from
the old JSON are visible after a restart, and all five calls work
as before.

Long — and it pays for itself. A task like this, started from one line, gets redone three times.

What to tell the AI

The rule for choosing: look not at the size of the task but at what happens if it comes out wrong.

Two questions that settle any doubt:

1. Can I check the result without reading the code? If not, you need a higher level — and first of all a definition of done.
2. Is it easy to roll back? One commit rolls back easily. A database migration does not.

What to look for

A mini-spec on a small change does harm. The more text there is, the more the AI "helps": rewriting neighbouring functions, adding handling for cases nobody asked about. A short task gets a short prompt.

Length is not the same as detail. Three lines with the framework version, the file name and a definition of done beat twenty lines of musing about how nice it would be.

The level goes up as you work. You started with a line and got the wrong thing — don't append to that same turn; restate it one level higher. Rewriting is cheaper than patching.

Cheat sheet