Starting Task

---
name: starting-task
description: Use when outcome-oriented engineering work may need a tracked Local Task before planning or implementation.
---

# Starting Task

Use this skill to decide if work needs a Local Task.

The SQLite-backed Local Task daemon owns task metadata and status. Pi uses the managed daemon through its configured endpoint. The daemon generates UUIDs. Imported IDs stay opaque.

## Decision Rule

Create Local Tasks for independently meaningful, outcome-oriented engineering work:

- Bug fixes
- Features
- Refactors
- Improvements to reliability, performance, UX, or maintainability
- Migrations, security work, or investigations with a durable conclusion

Before automatically creating a task, confirm all of these:

- The request is not merely an operational action or a question.
- It has a concrete, independently meaningful outcome that can be stated and verified.
- It needs durable tracking because it may span sessions or needs a plan, tests, decisions, or acceptance criteria.

Do not create a task merely because work has multiple steps or touches multiple files. Do not create one for operational requests, even when they have several steps: `git rebase`, commit, push, branch switching, checking status, running a known command, or a small one-time edit.

Routine initial reading or investigation is not a task by itself. If it reveals a distinct outcome-oriented work item, create a task then. When uncertain, do not create a task. Reuse a related active task instead of creating a duplicate.

Always create a task when the user explicitly asks to track the work.

## Start a Task

Use `task_start` with an outcome-focused title. Prefer separate `goal`, `context`, and independently checkable `acceptanceCriteria` fields for multi-step work; use `description` only when a short free-form brief is clearer. Do not provide both forms.

Use this concise creation shape when the information is known; omit sections that would be speculation:

```text
Title: <verb> <observable outcome>
Goal: <one-sentence outcome>
Context / background: <why this work matters, prior decisions, or constraints>
Acceptance criteria:
- <verifiable result>
- <verifiable result>
```

Before creating a task automatically (without explicit user direction), call `task_template_read` to read the Agent default section structure. Use those headings and their order when writing the task description. Fall back to the built-in structure (## Goal, ## Context, ## Acceptance Criteria, ## Notes) only when the tool is unavailable.

Include context/background when it is known and materially affects the work; omit it rather than inventing history. Keep detailed research logs and changing decisions out of the task description. Put them in `notes` after task creation. The user can update task metadata with `task_update` at any time.

You can set priority and tags at creation. New tasks start with new status. Do not provide an ID.

Use `workspace_list` before `task_start` to resolve the current workspace. Use `YISHAN_WORKSPACE_ID` when it is set. Otherwise, select the workspace whose `localPath` matches the current worktree path. When that workspace is non-primary, pass its ID as `workspaceId`. Do not associate a task started in the primary workspace.

For delegated work, associate the task with an existing target workspace. If no target workspace exists, use `workspace_create` first, then pass its returned workspace ID to `task_start`.

If `YISHAN_PROJECT_ID` is set, the task belongs to that project. Without it, the task is global.

## Work After Start

A tracked Local Task may contain multiple independently deliverable plan subtasks in its `plan.md`. A plan subtask is an execution unit within the tracked Local Task; its independent deliverability does not by itself require a new Local Task.

Before execution, the controller must create and freeze a brief for each plan subtask. Each brief must define its scope, non-goals, acceptance criteria or check, and a finite execution budget. Do not begin a plan subtask without its brief. The controller is the sole authority to create or replace scope-changing plan content.

Executors may record only within-brief execution detail in `plan.md`; they must not replace scope-changing plan content. When a newly discovered issue is related to the active plan subtask, a non-scope-changing clarification may stay in scope. If the discovery changes its frozen scope, requires a new decision or dependency, or changes assumptions for a later plan subtask, record it in `notes` and stop the current attempt. The controller decides whether to continue and, if so, must replace the affected scope-changing plan content with a newly frozen brief before resuming. Ask the user when the change affects unapproved behavior, commitments, or tradeoffs. For an unrelated issue, ask the user whether to create a separate Local Task.

Use `task_read` for the synthetic, read-only brief. Use `task_update` to change metadata, new, progressing, or cancelled status, priority, or tags. It cannot set done. Use `task_list` or `task_search` to find tasks.

Use `task_write` for `plan`, `notes`, or `outcome`. Use `task_append_note` for task-specific discoveries.

Use `task_finish` only when the user explicitly asks to complete the task. It writes the outcome and marks the task done.

## Boundaries

Do not create or parse task IDs. Do not bypass the daemon. Do not write the synthetic brief. Do not use `task_update` for completion.