reporting-governance-plugin/skills/long-task-governor/SKILL.md

name, description

name	description
long-task-governor	Use when a request is not ordinary single-turn chat and needs task governance, checkpoint discipline, state management, or anti-stall rules

Long-Task Governor

Use this skill whenever work is not ordinary general chat.

Core Rule

If the request cannot be fully completed within a single conversational reply without follow-up work, external waiting, task state, staged execution, or owner-visible progress tracking, treat it as a long task.

In short:

• ordinary general chat → answer directly
• everything else → enter long-task governance

What this skill governs

This skill provides the workflow layer for:

• decision split: general_chat vs long_task
• long-task state machine
• checkpoint structure
• no-fake-progress enforcement
• stop-clock / anti-stall handling

This skill is intentionally implemented as a maintainable external workflow layer, not a core OpenClaw runtime patch.

---

1. General chat vs long task

general_chat

Only classify as ordinary chat when all are true:

• can be fully answered now
• no follow-up work
• no external waiting
• no repo / file / logs / system inspection needed
• no task state needed
• no checkpoint needed
• no subagent needed
• no "half-done" intermediate state

long_task

If any condition above is false, treat the work as long_task.

Examples:

• inspect logs and report back
• compare two implementations after reading files
• modify code or config
• deploy or verify
• delegate to subagents
• anything that needs checkpointing or future follow-up

---

2. Required state machine

A governed long task may only be in one of these states:

• active
• waiting_user
• blocked
• paused
• pending_verification

Do not use vague state words like:

• ongoing
• still working
• processing
• in progress

Meaning

active

• there is a real concrete next action happening now
• not just waiting for time to pass
• not just waiting for the next reminder

waiting_user

• the task cannot reasonably continue until the user answers or decides something

blocked

• a concrete blocker prevents progress
• the blocker and unblock condition must be explicit

paused

• the task is intentionally not advancing
• stop pretending it is still actively moving

pending_verification

• implementation or investigation reached a meaningful checkpoint
• not complete by assistant authority
• waiting for verification / owner judgement

---

3. Minimal long-task record

When entering long-task governance, create or update a record with at least:

• task_name
• status
• current_step
• next_step
• last_milestone_at
• next_report_condition
• waiting_on
• blocker
• evidence_count

Use the template file task-record-template.md in this skill directory.

---

4. Checkpoint protocol

Every long-task checkpoint must contain exactly these five sections:

• 目前狀態
• 本段完成
• 下一步
• 下次回報條件
• 是否需要您介入

Checkpoint is not completion. After any checkpoint, the task must clearly remain in one of:

• active
• waiting_user
• blocked
• paused
• pending_verification

Never send a checkpoint and then silently stall.

Use checkpoint-template.md in this skill directory.

---

5. No-fake-progress rule

Only count as real progress if there is at least one of:

• new file change
• new verification output
• new decision or conclusion
• blocker state changed
• new external result / reply

The following are not progress:

• only updating timestamps
• only responding to reminders
• repeating "still working"
• status sync without new facts

If you only have status sync, say it is status sync. Do not dress it up as progress.

---

6. Stop-clock gate

If repeated checkpoints show no new evidence, do not keep the task cosmetically active. You must choose one:

• paused
• blocked
• explicit request for new direction
• stop periodic progress claims

active requires a concrete ongoing action. Without that, default to paused.

---

7. How to use this skill in practice

When this skill applies:

1. decide if the request is ordinary chat or long task
2. if long task, create/update a task record
3. choose one of the five valid states
4. if reporting progress, use the 5-part checkpoint structure
5. before claiming progress, check for real evidence
6. if no evidence and no concrete action, stop the clock
7. if the run is clearly heading toward a user pass/fail or accept/reject judgement on Telegram, prepare a button-path before the final handoff
8. if the entire test itself exists to validate Telegram decision closure, run it as a button-driven flow rather than a normal long plain-text report

---

8. Integration guidance

This skill should be paired with:

• the current session WORKFLOW.md
• optional kanban sync
• optional Lobby record
• subagent use when needed

But this skill itself is the governance layer and should remain independently maintainable.

Telegram interaction guard

When operating under long-task governance on Telegram:

• do not end checkpoints, test progress, or next-step decisions with plain-text menus like 1 / 2 / 3 or A / B / C
• if a choice is genuinely required, use Telegram inline buttons
• if buttons are required, send them first via the message tool rather than first producing a normal text reply
• if the workflow can already predict the final handoff is a user judgement, move to a button-path before the final closing paragraph
• if the test's whole point is to validate button closure, prefer a button-driven flow from the outset
• if no real choice is needed, execute the most reasonable next step directly
• if the assistant accidentally emits a plain-text choice menu, or says buttons will be used without actually sending them first, treat that as a workflow violation and convert the lesson into a permanent rule

This prevents governed long-task flows from degrading back into ambiguous text-only decision gates.

---

9. Success criteria

This skill is working correctly when:

• non-chat work always enters a governed state
• checkpoints no longer cause silent stalls
• no-evidence updates are not mislabeled as progress
• stalled work becomes paused / blocked instead of fake-active
• owner can always tell the real state of the work