reporting-governance-plugin/docs/runbooks/silent-long-task-decision-tree.md

Silent Long-Task Decision Tree

Use this decision tree before launching any long-task that may become silent.

Step 1 — Will this finish in the current turn?

If yes:

• do not make it silent
• keep it in immediate follow-up mode
• finish or report within the current conversational flow

If no:

• continue to Step 2

Step 2 — Will the task stop naturally producing user-visible output for a while?

Examples:

• research before reporting back
• debugging before a finding exists
• waiting on subagents
• background execution
• long verification or staged analysis

If no:

• keep it as ordinary long-task with immediate follow-up
• no silent-mode launch needed

If yes:

• this is a silent long-task
• continue to Step 3

Step 3 — Can an externalized checkpoint trigger be bound?

Valid options include:

• cron reminder
• forced checkpoint trigger design
• another reliable external wake path

If yes:

• define the first checkpoint trigger
• define the unfinished-task report shape
• define the no-evidence downgrade path (paused / blocked)
• define final owner handoff if needed
• then launch as silent long-task

If no:

• do not launch in silent mode
• keep it non-silent
• either stay in immediate follow-up mode or break the work into smaller visible steps

Step 4 — Does the final result require owner judgement?

Examples:

• pass / fail
• accept / reject
• rerun / stop
• approval / confirm

If yes:

• pre-plan the final handoff path
• on Telegram, prefer button-path
• do not wait until the final paragraph to think about buttons

If no:

• standard checkpoint and completion path is enough

Step 5 — What if the checkpoint fires and the task is unfinished?

Required response:

• report current status honestly
• show latest real evidence
• show next step
• show next report condition

Do not:

• pretend progress without evidence
• leave the task cosmetically active

Step 6 — What if the checkpoint fires and there is no new evidence?

Required response:

• downgrade to paused or blocked
• explain why there is no new evidence
• stop pretending continuous progress

Practical summary

Use silent long-task mode when:

• the task truly needs time between outputs
• you can bind an externalized checkpoint path
• you know how unfinished / no-evidence / final handoff states will be handled

Do not use silent long-task mode when:

• the work can finish in the current turn
• you cannot bind an externalized checkpoint path
• you are only relying on memory or intention to "remember to report back"

Coverage against known failure cases

This decision tree is meant to prevent:

• "I’ll go do this and report back" blackholes
• full tests that silently disappear between start and result
• delegated/subagent waits with no forced follow-up
• research/debug tasks that claim activity but produce no evidence