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

---

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.

---

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