task-state-updates

name	Task State Updates
description	Focused child skill for safely mapping user progress language to BuildOS task state updates without losing required IDs or emitting description-only writes.
skill_type	procedure
altitude	task
activation	progressive
preserve_markdown	true
parent_id	task_management
depth	1
legacy_paths	["onto.task.state.skill","task.state.skill"]
path	apps/web/src/lib/services/agentic-chat/tools/skills/definitions/task_state_updates/SKILL.md

Task State Updates

Identity

Focused child skill for safely mapping user progress language to BuildOS task state updates without losing required IDs or emitting description-only writes. This is a procedure skill at task altitude, operating as a child of the task_management root skill.

Activation

Use this child skill when the user reports progress, completion, or blocking on an existing task and the main risk is choosing the correct state_key and update payload.

• The user says a task started, finished, got blocked, or needs to move back to todo
• A previous update would change only task description even though task status also changed
• The exact task is likely known, but state mapping still needs care
• The agent needs to update task state and preserve or add a short progress note

Do not use this child skill for general task creation, task organization, or broad task planning. Use the task_management root skill for those.

Procedure

1. Confirm whether the request targets an existing task. If the exact task_id is not already in loaded context or prior tool results, search or list tasks before any write.
2. Map the user's progress language to one of the valid task states: todo, in_progress, blocked, or done.
3. Include state_key in the same update_onto_task call as any description, priority, assignee, or date change when progress actually changed.
4. If adding progress detail, preserve important existing description context unless the user explicitly asks to replace it.
5. Do not create a new task just because the user reported progress on an existing one.

Contract

After the write succeeds, summarize the state change and any note that was added.

Policy

• Do not emit update_onto_task without an exact task_id.
• Do not use invalid states such as open, complete, started, or waiting.
• Do not update only description when the user's message clearly means the task became in_progress, blocked, or done.
• Do not infer completion from weak language like "made progress" unless the user says the task is done, complete, shipped, sent, or finished.