Subtasks

Subtasks are the checklist beneath a task. They share most fields with their parent (title, assignee, due_date, done) but stay one level deep. The parent task auto-completes the moment every subtask is checked. Below are the questions people ask once they’ve used subtasks for an hour.

How deep can subtasks go?

One level. A task can have subtasks. A subtask can’t have its own subtasks. The product enforces this in the UI (no Add subtask button on a subtask) and in the API (POST /tasks/:id/subtasks returns 422 if :id is itself a subtask). This is a deliberate constraint. Two levels become a project plan and we want you to use a separate onboarding for that.

When should I use a subtask instead of a separate task?

Use a subtask when the work is one logical chunk that you want to split into steps, and you want the parent’s done flag to track the whole thing. Three common patterns:

• Checklist: “Provision sandbox” with subtasks for each system to provision. The parent closes when the sandbox is fully up.
• Acceptance criteria: “UAT sign-off” with subtasks for each test case the customer needs to verify.
• Handoff: “Engineering handoff complete” with subtasks for code merge, docs updated, on-call briefed.

Use separate tasks when the items have different assignees who need their own due dates and notifications, or when they belong in different phases.

Can subtasks be assigned to different people?

Yes. Every subtask carries its own assignee and due_date. The parent task’s assignee receives notifications when subtasks are completed, and each subtask’s assignee receives their own notifications. The parent doesn’t auto-reassign based on subtask owners.

Do subtasks have to live in the same phase as the parent?

Yes. Subtasks inherit phase from the parent. Moving the parent task to another phase moves all subtasks with it. You can’t have a parent in Integration and subtasks in UAT.

What happens when the parent task is completed manually with open subtasks?

You’re prompted to either complete the open subtasks or leave them open. Leaving them open is unusual but allowed. The parent closes with done: true and the open subtasks stick around as orphan checklist items. They still appear on the task detail panel and Pi flags them. To clean them up, reopen the parent, finish or delete the subtasks, then re-complete the parent.

Can a phase template include subtasks?

Yes. Each task in a template can declare a subtasks[] array with the same fields. The subtasks land pre-populated when you apply the template. Templates are the right place to encode your standard acceptance criteria so they don’t drift across customers.

How do subtasks show in the customer portal?

Subtasks inherit the parent task’s customer_facing flag. A customer-facing task shows its subtasks as a nested checklist. An internal task hides them. You can’t override the flag per subtask; flip it on the parent.

Related

• Task completion
• Phase templates
• Comments and attachments