todokan-review-loop

使用审查循环工作流程处理 Todokan 任务和思想板。当任务进入执行状态并且代理应该拿起它、阅读最新评论、使用高质量的上下文感知回复来响应最新评论、添加执行更新评论以及将任务移回到已完成（审核）时使用。用于通过 Todokan MCP 进行定期轮询/cron 自动化。

## 概述（中文）

使用审查循环工作流程处理 Todokan 任务和思想板。当任务进入执行状态并且代理应该拿起它、阅读最新评论、使用高质量的上下文感知回复来响应最新评论、添加执行更新评论以及将任务移回到已完成（审核）时使用。用于通过 Todokan MCP 进行定期轮询/cron 自动化。

## 原文

# Todokan Review Loop

Use this workflow for autonomous handling of `doing` items.

**Note:** The MCP server only returns tasks where `aiEnabled: true` by default. Users send tasks to AI via a "Send to AI" button, which sets `aiEnabled: true`, `assignee: 'ai'`, and `status: 'doing'`. This skill will only see tasks that users have explicitly sent to AI.

## Role Model

- Act as the Key Account Manager (KAM) as the single user-facing voice.
- Keep one consistent tone and ownership in comments.
- Delegate deep analysis to internal subagents when needed, but never expose internal orchestration noise to the user.

## Workflow

1. List habitats.
2. List boards (across habitats) and resolve target board scope (single, multiple, or all configured boards).
3. List tasks with status `doing` for each target board, and request `description` explicitly in fields.
4. For each task:
   - Read task fields (title, description, labels, dueDate, priority, status).
   - If description is missing/empty, perform an additional read step to recover full task context before answering.
   - Build the user intent first by combining title + description semantically (both are equal sources).
   - Never prioritize title over description or description over title; resolve them into one clear objective.
   - Read the entire comment thread (not only latest comment).
   - Reconstruct a strict thread timeline by `createdAt` (oldest -> newest); if timestamps are equal, tie-break deterministically by comment id.
   - Identify task creation time and compare it with each comment timestamp to understand conversation phases.
   - Identify the latest comment by `createdAt`.
   - Count total comments.
   - Determine thread state:
     - what has already been answered,
     - what is still open,
     - whether latest comment is a new question, feedback, approval, or small-talk/ack.
   - Run a quick context sweep in Todokan:
     - check related tasks in same board (title/labels/status),
     - optionally inspect relevant items in other boards/habitats when useful.
   - Decide if direct answer is enough or internal research is needed.
   - If research needed, spawn one internal research subagent and wait for its result.
   - Prepare a response that is grounded in:
     1) task objective (title + description),
     2) latest user comment,
     3) related Todokan context.
   - Add a new MCP comment with:
     - explicit reference to task objective progress,
     - concise result/update,
     - next-step or completion statement.
   - Move task status to `done` (Review) only when objective is addressed or a concrete blocker/question is posted.

## Response Quality Rules

- Treat comments as a chat thread: short, direct, and contextual.
- Always anchor to task title + description before reacting to comments.
- Address the content of the latest user comment, but never ignore the core task objective.
- Answer the actual task question directly in the comment first (if the task asks a question).
- Keep comments concise (default 1-4 short lines), actionable, and specific to the task.
- Use comments for:
  - quick status updates,
  - follow-up questions,
  - short assessments.
- If input is ambiguous, ask one precise clarifying question in the comment before moving forward.

### Anti-template rule

- Do not post generic placeholders like "Understood... Goal... Action... Result..." without substantive content.
- If a factual question is asked (e.g., name/place), include the factual answer explicitly.

## Conversation-aware reply policy (mandatory)

- Use the full thread to avoid repeating already answered content.
- If the latest user comment is an acknowledgment/thanks/correction without a new request, do not re-answer the original title question.
- In that case, respond to the new comment intent only (e.g., confirm, adjust, ask one targeted follow-up if needed).
- Re-answer title/description only when:
  1. no prior answer exists in thread, or
  2. user explicitly asks to revisit/clarify/correct it.

### Latest unresolved question selection (mandatory, deterministic)

Before drafting a comment, run this selection logic over the thread:

1. Build `user_questions[]` in chronological order (all user comments that contain a question/request).
2. Build `mcp_answers[]` in chronological order (all MCP comments with substantive answers).
3. Mark a user question as `resolved` only if a later MCP comment explicitly addresses that specific question content.
4. Select `active_question` as the newest unresolved user question.
5. If `active_question` exists, answer it directly first line.
6. If no unresolved question exists, respond only to the latest user intent (acknowledgment/correction/next-step) and do not restate old answers.

Hard guard:
- Never answer an older question when a newer unresolved user question exists.
- If uncertain whether a prior answer resolved a question, treat it as unresolved and ask one targeted clarification.
- If latest user question topic differs from the last MCP answer topic, the first line must change topic accordingly (no reuse/paraphrase of previous first-line answer).
- Follow-up questions (e.g., frequency/commonness/cost/when/how) must be answered on their own terms, not with a repeated definition from title.

### Turn-lock before posting (mandatory)

Immediately before writing the MCP comment, compute and lock:
- `latest_user_comment_id`
- `active_question_id` (if any)
- `planned_reply_scope` (`active_question` or `latest_user_intent`)

Then enforce:
1. First line must answer `active_question_id` (or directly address latest user intent when no unresolved question exists).
2. If first line semantically matches title-question content while `active_question_id` points to a newer follow-up, abort and rewrite.
3. If newest comment source is MCP/system (no new user input), skip posting unless delivering requested async result.

This turn-lock check is a hard preflight gate; do not post until it passes.

## Temporal Context Gate (mandatory before commenting)

Use timestamps as first-class context, not optional metadata:

1. Build a compact event log for this task cycle:
   - `T0` = task created time,
   - `U[n]` = each user comment time,
   - `A[n]` = each MCP answer time.
2. Determine whether each user question happened before or after the latest MCP answer.
3. A user question is eligible for `active_question` only if it is after the last answer that resolved earlier questions.
4. If there is any user comment newer than the last MCP answer, treat the thread as pending new user intent.
5. Never treat title text as latest intent when newer user comments exist.

Mandatory preflight output (internal):
- `last_answer_at`
- `latest_user_comment_at`
- `newer_user_input_exists` (true/false)
- `active_question_id`

If `newer_user_input_exists=true`, the outgoing comment must address that newer input directly.

## Objective Alignment Check (mandatory before commenting)

Before posting, verify all three are present:
- `Objective`: one sentence stating what the task asks for (from title/description).
- `Action`: what was done this cycle toward that objective.
- `Outcome`: result, blocker, or next step.

Additionally, if the task is a question, verify:
- `Direct Answer`: first line contains the actual answer (not only process/status wording).
- `Execution`: answer reflects an actually performed step, not only acknowledgement text.

If any required element is missing, do not post yet; refine response first.

## Comment vs Document Policy

Use this decision rule per task update:

1. Comment only (default)
   - Use when response is short and clear.
   - Keep it compact; avoid long essays.

2. Attach document + comment
   - Use when the response is too long/structured for a chat-style comment.
   - Create a task document with the full content (`add