--- 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: Goal: Context / background: Acceptance criteria: - - ``` 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.