How to write a mini-spec

for a task you would hate to redo

What it is

A mini-spec is the third level of detail from article 3.3, written out in full. You need it where a task touches several files, changes the shape of the data, or rolls back badly.

It is the same four parts of a prompt (article 3.2), simply unfolded. There is nothing new to learn — you just carefully write down what is usually kept in your head.

What it looks like in code

The structure

Task          one sentence: what should come into being
Why           which problem we are solving
Context       how it works now, what already exists
What to do    point by point, in execution order
Constraints   what not to do, what not to touch
Done when     checkable conditions, as a list
Out of scope  what we deliberately are not doing now

Two of the seven sections are usually skipped, and they are the most useful.

"Why" gives the AI room to propose something better than your idea. If it only knows what to do, it does it literally; if it knows why, it can say "there is a simpler way to get that".

"Out of scope" reins in the appetite. Without it the AI builds the task up into the "proper" one: you asked for a cache and got a cache with invalidation, metrics and config-driven tuning.

A complete example

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

Why: with 300+ subscriptions the whole file is rewritten on every
change and the bot stalls for a second. Also, a failure during the
write corrupts the file.

Context: subscriptions are in data/subs.json, shape
{user_id: [city, ...]}. Read by load_subs(), written by save_subs(),
both in storage.py. Five call sites, all in handlers/.
SQLite is already used in the project for logs, connection via
get_conn() in db.py.

What to do:
1. A subscriptions table: user_id INTEGER, city TEXT,
   created_at TEXT. Unique on the pair (user_id, city).
2. Rewrite load_subs/save_subs on SQLite.
   Don't change the signatures or the return types.
3. Migration on startup: if data/subs.json exists and the table
   is empty, move the data and rename the file to subs.json.bak.

Constraints:
- the sqlite3/aiosqlite module only, no ORM
- don't touch the handlers at all
- don't change the log format

Done when:
- on an empty database the bot starts without errors
- subscriptions from the old JSON are visible after a restart
- all five call sites work without edits
- a second start does not duplicate the data

Out of scope: indexes, query optimisation, moving the logs,
admin commands for viewing subscriptions.

Twenty-five lines — and a task that would otherwise be redone three times gets done on the first attempt.

What to tell the AI

How long it takes

Ten to fifteen minutes. It pays for itself at the first fork the AI would otherwise have closed on its own.

If a mini-spec takes an hour, the task is too big. Split it in two and write the spec for the first half.

A good combination

Mini-spec + plan (article 3.10) is the most reliable pairing for a large task:

<mini-spec>

Don't write code yet. Lay out a plan for how you will do this,
and tell me where my spec is missing information.

The second sentence is the valuable one: the AI points at the holes in your spec before they turn into wrong code.

When a mini-spec isn't needed

For anything that rolls back with one command. A mini-spec for adding a function is bureaucracy, not care.

What to look for

"Done when" written in adjectives. "Works reliably", "fast", "convenient" are not criteria. A condition you cannot check constrains nothing (article 3.2).

The "Context" section retelling the code. There is no need to copy functions in — saying where to look is enough. The AI will read it itself if it has access to the project.

A spec that was never compared against the result. The main value of a spec shows at the end: walk the "Done when" list and tick every line. That is two minutes and the only way to know whether it is done.

The task grew along the way. New points appeared that were not there — that is not a reason to extend the spec on the fly. Finish the current one, then state a second task.

Cheat sheet