kandev/docs/specs/tasks/requirements/task-priority-visibility.md

status, system, created, owners

status	system	created	owners
active	tasks	2026-09-03	kandev

Task priority visibility Requirements

Overview

Kanban tasks use four priority tokens: critical, high, medium, and low. People can see non-medium priorities on task cards and can set the priority when they create or triage a task. Existing task storage, APIs, and events already carry the value. This capability makes that value visible and usable on the kanban board without changing the task model or priority vocabulary.

The tasks system owns this capability because priority is part of the durable task record. The board and task switcher are presentation and interaction surfaces for that record.

Terminology

• Priority token: one of the four persisted values critical, high, medium, low. A wire and storage value, never translated.
• Priority label: the localized, human-readable rendering of a token.
• Default priority: medium. Applied by the backend when a create request omits priority.
• Priority indicator: the card element that conveys a task's priority.
• Card menu: the task card's action menu. It has two triggers that render from one shared entry list: a desktop-only right-click context menu, and a dots-button dropdown available at every breakpoint.
• Task switcher: the shared task tree rendered in the desktop sidebar and in the phone or tablet task-navigation surface.
• Board order: the order cards appear within a workflow step, driven by the task's position and controlled by drag and drop.

Prior art

The Office task surface already uses a priority picker and localized labels. It has a separate vocabulary that includes none and supports workspace-defined labels. Kanban keeps its own four-token vocabulary and localized labels, so the two surfaces remain independent while following the same token-versus-label convention.

Requirements

REQ-TASKS-PRIORITY-VISIBILITY-001: A task's priority is visible on its card

Intent: Let a person scanning the board see which tasks are elevated or deprioritized without opening anything, while keeping the common case silent so the indicator reads as an exception rather than as decoration on every card.

User story: As someone picking up work from the board, I want to see at a glance which tasks are urgent, so that I choose what to start without opening each card in turn.

Acceptance criteria

• AC-TASKS-PRIORITY-VISIBILITY-001.1: When a task's priority token is critical, high or low, the system shall render a priority indicator on that task's card.
• AC-TASKS-PRIORITY-VISIBILITY-001.2: When a task's priority token is medium, the system shall render no priority indicator on that task's card. medium is the default and the majority case, so its indicator would carry no information.
• AC-TASKS-PRIORITY-VISIBILITY-001.3: When a task's priority is absent, empty or is not one of the four priority tokens, the system shall render no priority indicator and shall not render the raw value as text. An unrecognized value shall not produce an error, a blank indicator or a broken card.
• AC-TASKS-PRIORITY-VISIBILITY-001.4: The system shall render a visually distinct indicator for each of critical, high and low, distinguishable from each other by more than color alone.
• AC-TASKS-PRIORITY-VISIBILITY-001.5: The system shall give the priority indicator an accessible name that includes the localized priority label, so a screen reader conveys the priority without relying on the visual treatment.
• AC-TASKS-PRIORITY-VISIBILITY-001.6: The presence, absence or value of the priority indicator shall not change board order. Rendering priority shall not reorder, regroup or re-position any card.
• AC-TASKS-PRIORITY-VISIBILITY-001.7: The indicator shall be correct on the first render of the board after a full page load, without waiting for a subsequent event, refetch or user action. Whatever payload hydrates the board initially shall carry each task's priority. A task that was already critical before the page was opened shall render as critical on first paint.
• AC-TASKS-PRIORITY-VISIBILITY-001.8: When a task's priority changes from any source, including another browser client, the Office task UI or a REST API caller, the card shall reflect the new value without a page reload. That list is illustrative: the card shall follow the stored value regardless of which writer produced it. Agents cannot currently set priority, because the MCP task tools do not accept the field.
• AC-TASKS-PRIORITY-VISIBILITY-001.9: A message that refreshes the board without carrying priority shall not clear, blank or alter the priority already displayed for a task. A client shall either receive priority in such a message or preserve the value it already holds. No board refresh, workflow switch or reconnect shall silently drop the indicator from a card whose priority has not changed.
• AC-TASKS-PRIORITY-VISIBILITY-001.10: The indicator shall be rendered at every breakpoint at which the card is rendered. There shall be no breakpoint at which a critical, high or low task appears identical to a medium one.

REQ-TASKS-PRIORITY-VISIBILITY-002: A person can set priority when creating a task

Intent: Let the person who knows the urgency record it at the moment they create the work, rather than creating the task and then correcting it.

User story: As someone filing a task I already know is urgent, I want to set its priority while creating it, so that it is visible to everyone from the moment it appears on the board.

Acceptance criteria

• AC-TASKS-PRIORITY-VISIBILITY-002.1: The primary task creation dialog shall offer a priority control inside its Advanced settings section, which is collapsed by default. The control shall present exactly the four priority tokens, each shown by its localized label. This is the shared dialog component, so the control shall appear no matter which entry point opened it (the board, the sidebar's new-task action, or an integration's task launcher). Subtask creation is a separate flow and is excluded; see ## Out of scope.
• AC-TASKS-PRIORITY-VISIBILITY-002.2: The control shall default to medium. A person who ignores it shall create a medium task, which is the behavior before this capability.
• AC-TASKS-PRIORITY-VISIBILITY-002.3: When a task is created, the system shall submit the selected priority token, and the created task shall carry it. The created card shall then satisfy REQ-TASKS-PRIORITY-VISIBILITY-001.
• AC-TASKS-PRIORITY-VISIBILITY-002.4: The priority control shall be reachable and operable at every breakpoint at which the primary task creation dialog is available.
• AC-TASKS-PRIORITY-VISIBILITY-002.5: Selecting a priority shall not change any other field of the creation request, and shall not block, gate or reorder any other step of task creation.
• AC-TASKS-PRIORITY-VISIBILITY-002.6: On wide layouts, the dialog shall show the dependency selector before the priority selector. The priority selector shall start at the leading edge of the second column. The priority label shall provide contextual help on hover or focus, with an equivalent touch-friendly disclosure for coarse pointers.

REQ-TASKS-PRIORITY-VISIBILITY-003: A person can change an existing task's priority

Intent: Let priority be corrected as work is triaged, from the board, without navigating away from it.

User story: As someone triaging the board, I want to raise or lower a task's priority in place, so that the board reflects the current plan without my leaving it.

Acceptance criteria

• AC-TASKS-PRIORITY-VISIBILITY-003.1: The card menu shall offer a priority action presenting exactly the four priority tokens, each shown by its localized label.
• AC-TASKS-PRIORITY-VISIBILITY-003.2: The priority action shall indicate which token is the task's current priority, so a person can read the current value without changing it. When the task's priority is absent, empty or is not one of the four priority tokens, the action shall indicate no token as current, and shall not indicate medium or any other token in its place. Indicating a token the client does not hold would assert a current value that may be wrong, so indicating none is the honest rendering; all four tokens shall remain selectable in that state.
• AC-TASKS-PRIORITY-VISIBILITY-003.3: The priority action shall be available from both card-menu triggers. Because the right-click context menu is rendered only at desktop breakpoints, the dots-button dropdown shall carry the same priority action, so the capability is reachable on touch devices.
• AC-TASKS-PRIORITY-VISIBILITY-003.4: When a person selects a priority, the system shall persist that token against the task and shall change no other field of the task. It shall not change the task's title, description, state, workflow step, parent or position.
• AC-TASKS-PRIORITY-VISIBILITY-003.5: When a person selects the token that is already the task's priority, the system shall complete without error and leave the task's priority unchanged. Repeating the same selection any number of times shall leave the task in the same state as applying it once.
• AC-TASKS-PRIORITY-VISIBILITY-003.6: When two clients set different priorities on the same task, the system shall accept both writes in arrival order and the last write shall determine the stored value. Each client shall converge on the stored value from the resulting task event. No client shall merge, re-apply or resurrect its own pending value after receiving an event carrying a different one.
• AC-TASKS-PRIORITY-VISIBILITY-003.7: When persisting the priority fails, the system shall surface the failure to the person and the card shall continue to display the task's last known stored priority. A failed change shall not be presented as having succeeded.
• AC-TASKS-PRIORITY-VISIBILITY-003.8: Changing a task's priority shall not change board order, shall not move the card between workflow steps, and shall not start, stop or otherwise disturb any session on that task.

REQ-TASKS-PRIORITY-VISIBILITY-004: Priority tokens are persisted and priority labels are localized

Intent: Keep the machine-readable token and the human-readable label separate, so that translating the interface can never change what is stored, compared or sent.

Acceptance criteria

• AC-TASKS-PRIORITY-VISIBILITY-004.1: The system shall treat critical, high, medium and low as the complete priority vocabulary for kanban tasks, and shall persist and transmit them verbatim in lower case.

• AC-TASKS-PRIORITY-VISIBILITY-004.2: The system shall never store, transmit or compare a translated priority string. Every comparison, selection and request shall use the token.

• AC-TASKS-PRIORITY-VISIBILITY-004.3: The system shall resolve every priority label at render time, so that changing the active locale re-renders every priority label without a reload.

• AC-TASKS-PRIORITY-VISIBILITY-004.4: The system shall provide priority labels in every supported locale. The labels shall be:

  Token	en	pt-pt	zh-cn	zh-hk	zh-tw
  (field name)	Priority	Prioridade	优先级	優先級	優先順序
  critical	Critical	Crítica	紧急	緊急	緊急
  high	High	Alta	高	高	高
  medium	Medium	Média	中	中	中
  low	Low	Baixa	低	低	低

  These are the strings already carried in the office namespace in all five locales, reused here so this capability introduces no untranslated copy.

• AC-TASKS-PRIORITY-VISIBILITY-004.5: No priority label or related copy shall contain a Unicode em dash (U+2014).

REQ-TASKS-PRIORITY-VISIBILITY-005: Priority is visible and editable in the task switcher

Intent: Let a person scan and triage tasks from task detail without returning to the board.

User story: As someone working from a task detail, I want to see and change another task's priority in the task switcher, so that I can triage work without leaving my current task.

Acceptance criteria

• AC-TASKS-PRIORITY-VISIBILITY-005.1: When a live task in the desktop sidebar or phone or tablet task switcher has priority critical, high or low, the system shall show the same priority indicator immediately after the task title in its inline badge area. Task titles shall start at the same horizontal position whether or not an indicator is present.
• AC-TASKS-PRIORITY-VISIBILITY-005.2: When the task priority is medium, absent, empty or not one of the four priority tokens, the task switcher shall show no priority indicator and shall not show the raw value.
• AC-TASKS-PRIORITY-VISIBILITY-005.3: The task-switcher indicator shall use the same shape, color and localized accessible name as the corresponding card indicator. Priority shall remain distinguishable by more than color alone.
• AC-TASKS-PRIORITY-VISIBILITY-005.4: The single-task action menu shall show a Priority submenu with a leading flag icon, the four localized priority labels and a visible current-value marker. An absent, empty or unrecognized value shall mark no option as current.
• AC-TASKS-PRIORITY-VISIBILITY-005.5: Desktop users shall reach the Priority submenu from the task row's right-click menu. Phone and tablet users shall reach the same submenu from the visible task-actions control. On coarse pointers, the task-actions control and menu rows shall have a hit area of at least 44 CSS pixels in the active dimensions.
• AC-TASKS-PRIORITY-VISIBILITY-005.6: When a person selects a priority from the task switcher, the system shall persist only that task's priority and shall surface a failure without replacing the last known stored value. Reselecting the current priority shall complete without error.
• AC-TASKS-PRIORITY-VISIBILITY-005.7: When the stored priority changes from any source, every visible desktop, phone and tablet task-switcher row shall converge on the stored value without a page reload. A snapshot or refresh that omits priority shall not clear an existing value.
• AC-TASKS-PRIORITY-VISIBILITY-005.8: The Priority submenu shall not be available for an archived row or a multi-task selection. Showing or changing priority shall not reorder, regroup, select or navigate any task.

Out of scope

Each exclusion below is a decision, not an omission.

• Sorting or filtering the board by priority. The board remains manually ordered. Priority sorting or filtering needs its own product decision about how it interacts with that order and its own requirement.
• Setting priority while creating a subtask. Subtasks keep their existing creation flow and receive the default medium priority. A person can change a subtask's priority later from its card.
• Server-side rejection of an invalid priority token. This capability adds fixed four-option controls, so its user-facing writers cannot emit an invalid token. Consistent validation for every API writer is a separate hardening task.
• MCP priority write support. The MCP task contract is unchanged. Adding a priority argument to MCP tools is a separate contract change.
• The Office task UI. Office already surfaces priority, over a different five-token vocabulary that includes none and supports workspace-supplied labels. Nothing here changes it, and the two vocabularies are deliberately not merged.
• A none priority, or any change to the vocabulary. The four tokens are fixed by the database CHECK constraint. Adding a fifth would need a migration and is a different capability.
• Any schema or migration work. The column, its type, its default and its constraint already exist and are not touched.
• Labels and tags. Priority remains a task field. It is not modelled as a label or tag.
• Changing priority from other surfaces. A control on the task detail page outside the task switcher, or in a command palette, is additive and is not required by this capability.
• Bulk priority changes. Setting priority across a multi-selection is a separate interaction with its own partial-failure semantics.
• Priority on ephemeral tasks. Quick-chat and other ephemeral tasks are filtered out before the board renders, so they have no card to carry an indicator.
• Task-creation retry and idempotency semantics. Adding a priority field to the creation request does not change how a repeated create is deduplicated. A deduplicated create returns the existing task and does not re-apply the submitted priority.
• Priority as an input to scheduling. Nothing here changes which task an agent, a WIP-queue pull or any automation selects. The existing pull-query ordering is unchanged.
• A default priority per workflow, step or workspace. The default stays the single backend value medium.