Docs / Live progress / How-to

Write progress notes and questions a person can act on

The person reads your messages on a phone or in a corner of the screen, between other things. Put the point first and make any request specific enough to answer in one line.

Progress messages

Say what is happening now, in under 80 characters: "Running the test suite (412 tests)".
Name the thing, not the activity: "Migrating invoices table" beats "Working on database stuff".
Use current and total when you're counting; the numbers go in the bar, not the message.

Blocking questions

A blocked task asks for one of four things. Say which in the first words, then give what the person needs to answer without opening the code:

Blocking questions
Request	Shape	Example
Decide	Options, your recommendation, what each costs	Decide: keep the old /v1 route for 30 days (safer) or remove it now (simpler)? I recommend 30 days.
Answer	A question with a short answer	Answer: which Stripe account should test checkouts use, the shared one or acct_...?
Approve	What you'll do and how to undo it	Approve: drop the unused sessions_old table (8 MB). Backup at backups/sessions_old.sql.
Access	Exactly what is missing and where it goes	Access: I need STAGING_DB_URL in .env.local to run the migration.

Block the step that's stuck rather than the whole task when only one step needs the person, and keep working on other steps while you wait.

When the reply doesn't settle it

Read the reply with taskhold_updates. If it answers, unblock and say what you'll do in one line.
If it's unclear, ask one follow-up on the same task, quoting their reply: "You said 'the shared one'. Do you mean acct_live_shared or acct_test_shared?"
After two unclear rounds, stop asking. Leave the task blocked, move to other work, and write what you'd do by default and why.
Never pick an answer you weren't given for anything you can't undo. If the reply doesn't settle it, block again with a narrower question; don't guess.

Always ask first

Deleting data, spending money, changing billing or prices, touching secrets or access, and deploying to production. Block with an Approve request even when you're fairly sure.

Give them the context

Put what you tried and what you found in the question, so the person can answer without opening the code: "Tests fail only on Node 20 (passes on 22). Pin Node 22 in CI, or fix the polyfill? I recommend pinning."

Don't fake it

If you don't know, say so and block. A blocked task costs the person a minute; a confident guess can cost them the afternoon.

Completion summaries

First line: the outcome. "CSV export works for all three report types."
Then what changed (files or areas), how you checked it, and anything left over, filed as new tasks.