# Write progress notes and questions a person can act on

> Write progress messages and blocking questions a person can act on from the live board: headline first, one request, options with a recommendation.

Source: https://taskhold.com/docs/agent-messages
Last updated: 2026-10-26

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:

| 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.

## Related

- [How live progress works: steps, bars, ETA and liveness](https://taskhold.com/docs/live-progress.md)
- [Taskhold MCP tools reference (taskhold_*)](https://taskhold.com/docs/mcp-tools.md)
- [Quickstart: watch your agent's first plan in 5 minutes](https://taskhold.com/docs/quickstart.md)