235 lines
6.9 KiB
Markdown
235 lines
6.9 KiB
Markdown
---
|
|
name: long-task-governor
|
|
description: 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. Silent long-task governance
|
|
|
|
If a long-task will not naturally emit an immediate next user-visible message, treat it as a **silent long-task**.
|
|
|
|
A silent long-task must define at startup:
|
|
- the first forced checkpoint trigger
|
|
- what to report if not yet complete
|
|
- what status transition to use if there is no new evidence
|
|
- how final owner handoff will happen if a decision is expected
|
|
|
|
Silent long-tasks must not rely on memory, intention, or implied future follow-up.
|
|
If the user later has to ask where the update went, the flow is considered failed.
|
|
|
|
---
|
|
|
|
## 6. 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.
|
|
|
|
---
|
|
|
|
## 7. 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`.
|
|
|
|
---
|
|
|
|
## 8. 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 the task is silent, define the first forced checkpoint before proceeding
|
|
5. if reporting progress, use the 5-part checkpoint structure
|
|
6. before claiming progress, check for real evidence
|
|
7. if no evidence and no concrete action, stop the clock
|
|
8. 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
|
|
9. 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
|
|
|
|
---
|
|
|
|
## 9. 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.
|
|
|
|
---
|
|
|
|
## 10. Success criteria
|
|
|
|
This skill is working correctly when:
|
|
- non-chat work always enters a governed state
|
|
- silent long-tasks never go dark without a predeclared checkpoint
|
|
- 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
|