A discrete unit of work within a user story
A task is the smallest unit of tracked work a team commits to: a concrete, finishable step like "add the export endpoint" or "write the migration script". It carries no user and no benefit of its own, which is what keeps it small and unambiguous.
The task as a planning primitivePrimitiveFoundationsA canonical reusable building block defined by a specificationView reference → comes out of the iterative-planning tradition, formalised in Scrum. The Scrum Guide, written by Ken Schwaber and Jeff Sutherland, does not actually use the word "task". It speaks of Product Backlog Items and of the Sprint Backlog being decomposed by the developers, "often to units of one day or less". Teams supplied the word "task" for those day-sized units, and it stuck.
The useful distinction the practice settled on is between the what and the how. A Product Backlog Item, often written as a story statement, expresses what value is wanted. The tasks beneath it express how the developers intend to build it. Mike Cohn made the same split explicit in agile estimating and planning: stories are owned by the whole team and estimated in relative points, while tasks are an implementation breakdown the developers create during planning, sized in hours. Ownership matters here. Decomposition into tasks is the development team's jobJobUserJob To Be Done: what the user is trying to accomplishView reference →, not the product owner's, because the how is an engineering decisionDecisionStrategyA recorded decision with context, rationale, and consequencesView reference →.
The riskRiskComplianceA risk to the product or businessView reference → the field learned the hard way is task-shaped thinking. A backlog of two hundred tasks with no visible parent value reads as motion. Bill Wake's SMART tasks (Specific, Measurable, Achievable, Relevant, Time-boxed) were proposed in 2003 as the task-level counterpart to INVEST, a reminder that a task still has to earn its place against the story it serves.
A team picks up the statement "As a finance admin, I want to export transactions as CSV". During sprint planning the developers break it into tasks: build the export endpoint, write the CSV serialiser, add a column-mapping config, handle the 200,000-row pagination case, write the integration test. Each is a few hours. Each is owned by whoever picks it up.
The breakdown does real work. The 200,000-row task surfaces a performance question that would otherwise have ambushed the team mid-sprint. The integration test task makes the acceptance criteria executable. None of the five tasks is independently shippable; the finance admin gets nothing from the serialiser alone. The increment becomes valuable only when the parent statement is complete, which is the line that separates a task from a story.
In the Unified Product Graph, TaskProduct SpecificationA unit of work within a story or epic lives in the product specificationSpecificationFoundationsA canonical open standard or specification that primitives and products conform toView reference → region as the leaf of the delivery hierarchy. Its edges keep it tethered to purpose. tasktask_implements_story_statement ties each task back to the value it serves, so a task that implements no statement is a queryable orphan. Featuredecomposes intoTaskhierarchy lets larger capabilities break down directly into work, and feature_decomposes_into_taskTaskhas subtaskTaskhierarchy allows finer splitting when a unit grows past a day. The fourth edge, task_has_subtaskResearch QuestiongeneratesTaskcausal, captures the case where investigationInvestigationEngineeringAn investigation into an issue or incidentView reference →, not a feature, is the origin of work: a study raises a question, and answering it spawns tasks. Modelling tasks this way makes the backlog auditable, because every unit of work can be traced upward to the user value or the open question that justifies it.research_question_generates_task
Worked example: Trellis
Rendering the per-record impact preview that a director reviews before approving a change is a concrete task within the Safe Change epicEpicProduct SpecificationA large body of work that can be broken into storiesView reference →. Tasks at this level are the smallest tracked units of delivery work, sitting below the user storyUser StoryProduct SpecificationA user's goal and the value they expect, in the "As a… I want… So that…" format. Now also a first-class plannable unit (priority, effort, assignee, due_date) that schedules into a planning_cycle, and it round-trips an external board's column via workflow_state.View reference → and above a commit, and they are what a team pulls into a sprint from an epic to make a roadmap itemRoadmap ItemProduct SpecificationAn item on the product roadmapView reference → move.
High Important; address in the current sprint or planning cycle.
Type-specific fields on BaseNode
assigneestringAssigned person. Promote to a `node_owned_by_person` edge if ownership must be queryable.
effortstringEffort estimate (e.g. "2h", "1d", "3 points"). Use a consistent unit within your team.
priorityenumRelative importance against other tasks
due_datestringISO date due. Typically bounded by the containing story's due date.
labelsstring[]Free-form classification tags. Applied uniformly across work item types.
workflow_statestringThe source tool's raw custom workflow state, verbatim and opaque (e.g. "In Review", "QA", "Needs Triage"). Non-canonical and never reasoned over: it exists to round-trip an import losslessly. Map it onto a canonical bucket with `workflow_state_category`; canonical `status` stays the sole reasoning axis.
workflow_state_categorystringCanonical bucket the raw `workflow_state` maps onto for reasoning (a source "In Review" and "QA" might both map to a verification phase). Optional companion to `workflow_state`: it lets a graph reason over an imported custom workflow without promoting the raw label to `status`.
idstringrequiredUnique identifier (UUID)
typeNodeTyperequiredDiscriminator for the entity type
titlestringrequiredDisplay name
descriptionstringOptional detailed description
statusstringLifecycle status
tagsstring[]Freeform tags for filtering
4 phases, initial: todo · template: WORK_ITEM
5 edge types connected to this entity.
task_has_subtasktask_implements_user_storyresearch_question_generates_task1 framework use this entity type.