/task-progress

task-progress

Sends mid-task progress updates to the channel a task came from (Slack, Discord, Telegram, or an s.space room).

Critical rule — if you notify, notify BEFORE any work begins

For tasks that need a progress update, **call notify.py as the FIRST action after reading the task — before transcription, web searches, code reads, or any other tool call.** The user's first signal that you received a long-running task must be the notification, not silence followed by a result minutes later.

Critical rule — progress only, never final answers

`notify.py` is only for short progress/status updates. Do **not** use it to send the answer, findings, recommendations, completed list, PR summary, or any other final result. Final task delivery must go through the authoritative task result file (`results/task-<id>.txt`, or the channel-specific result path named in the task).

Keep notify bodies short: at most 280 characters and 4 non-empty lines. The script rejects longer messages so a final answer cannot accidentally be sent directly and then duplicated by the bridge when it delivers the result file.

If you already sent the final answer through another approved path, write `[REPLIED]` to the task result file so the bridge archives the task without sending a duplicate.

Voice message tasks (most common failure case)

When a task contains a voice attachment (`[File attached: ...]`), notify BEFORE calling the transcription script. Transcription takes 10–30 seconds — the user should not wait in silence.

Wrong order: 1. Read task (sees voice attachment) 2. Call transcribe.py ← 20s of silence 3. Process transcript 4. Return result ← user waited 60+ seconds with no signal

Correct order: 1. Read task (sees voice attachment) 2. **Notify: "Got your voice message, give me a moment."** ← user knows within seconds 3. Call transcribe.py 4. Process — if research needed, notify again before starting 5. Return result

All other long-running tasks

Wrong order: 1. Read task 2. Do research (WebSearch, WebFetch, file reads, analysis...) 3. ← user waits 2 min with no signal 4. Notify "on it" 5. Return result

Correct order: 1. Read task 2. **Notify immediately** ← user knows you got it within seconds 3. Do research / work 4. Notify at key checkpoints 5. Return result

When to notify

Notify at task-start when any of these apply:

• Research questions (web search, reading files, looking things up)
• Code changes (editing, writing, testing)
• PRs (opening, reviewing, updating)
• Multi-step analysis (GTM strategy, architecture review, brainstorming)
• Anything that will take more than ~60 seconds before the result appears

No notification needed for:

• A factual answer you can give immediately from memory
• A one-sentence reply

**When in doubt, notify.** A false positive (notifying for a 30-second task) is far less annoying than silence for 2 minutes on a research task.

How to use

**Pass `--task-file <path>`.** It derives `--source`, `--channel-id`/`--chat-id`, `--thread-root` (from `thread_root:` only — threading is a decision the ask already made, not this script's default), `--reply-to` (from `source_message_id:`, the asking message — never `reply_to_event:`, the post the sender quoted; cites the ask without nesting it in a thread the user never started) and `--thread-ts` (from Slack's `reply_thread_ts:`) straight from that task file's own headers, so there is nothing left to extract or remember by hand. When the ask was already in a thread, both fields are sent together: `thread_root` nests the post, `reply_to` is its citation fallback for a client that doesn't render threads. A task sends when its source is `slack`/`discord`/`telegram`, or — for ANY other source, known or not — when its channel is a valid Matrix room id: strict `!opaque:server`, or a server-less room v12 id (e.g. s.space, or a docked voice task). Everything else — undocked `voice` (`local-voice`), `chat`, `cron`, `runtime-api`, `onboarding-wizard`, any non-room channel — sends nothing and exits 3 (no delivery path; not a failure of the task), whatever channel config exists. Accepted trade-off: gateway provider labels are install-configured, so routing keys on the room id, not the source — a future writer that carries a real room id will send. The verdict is `src/progress_route.py`. Call **immediately after reading the task**:

python3 $CLAUDE_CONFIG_DIR/skills/task-progress/scripts/notify.py \
  --task-file "$WORKSPACE/tasks/task-<id>.txt" \
  --message "On it — looking into that now. Back in a minute."

For research tasks, be specific about what you're doing:

  --message "Researching Trigify setup time now — back in a minute."

Mid-task checkpoint update — same `--task-file`, new message:

python3 $CLAUDE_CONFIG_DIR/skills/task-progress/scripts/notify.py \
  --task-file "$WORKSPACE/tasks/task-<id>.txt" \
  --message "Done with the research — writing up the summary now."

Any of `--source` / `--channel-id` / `--chat-id` / `--thread-root` / `--reply-to` / `--thread-ts` given explicitly alongside `--task-file` still wins over what the file carries (e.g. to post a checkpoint with no citation at all, pass `--reply-to ''`).

When there is no task file to point at

Pass the fields by hand — same flags, same meaning:

python3 $CLAUDE_CONFIG_DIR/skills/task-progress/scripts/notify.py \
  --source slack \
  --channel-id D0B5L7X2TK2 \
  --message "On it — looking into that now. Back in a minute."

For a Slack @mention (threaded reply), add `--thread-ts <ts>` to keep the update in-thread. For s.space, pass the task's own `thread_root:` via `--thread-root '<event id>'` only when the ask was already in a thread; otherwise pass `--reply-to '<source_message_id>'` to cite it in the main timeline instead. Single-quote the id: it starts with `$`, which double quotes would expand. An empty value opts out of that relation.

Field mapping from task files

(What `--task-file` derives a