pal-e-docs

Convention: Blocker Labels

convention-blocker-labels Convention

active convention
Project

Convention: Blocker Labels

Blocker labels mark tickets that cannot progress until a dependency is resolved. Two patterns: blocker:external and blocker:internal.

Rule

When a ticket is blocked, apply exactly one blocker label: blocker:external for dependencies outside the team's control, or blocker:internal for dependencies on other tickets, PRs, or decisions within the platform. Document the specific blocker in the ticket description. Remove the label when unblocked.

Rationale

Without blocker labels, blocked work is invisible. Tickets sit in columns with no signal about why they are not progressing. Betty Sue cannot distinguish "not started" from "cannot start" during board reviews. The external/internal split matters because external blockers require waiting while internal blockers require prioritization of the blocking work.

Label Patterns

Label Meaning When to Use
<code>blocker:external</code> Blocked by something outside the team's control — upstream dependency, third-party service, vendor response, infrastructure provider. Waiting on Apple review, DNS propagation, third-party API fix, hardware delivery.
<code>blocker:internal</code> Blocked by another ticket, PR, or decision within the platform. The team can unblock it. Depends on another PR being merged; requires architecture decision; waiting on another service deployment; needs Lucas approval on design.

Examples

Correct Incorrect Why
<code>blocker:external</code> with description "Waiting on Apple App Store review (submitted 2026-03-25)" <code>blocker:external</code> with no description The label says blocked; the description must say by what and since when.
<code>blocker:internal</code> referencing "Blocked by pal-e-platform #225" <code>blocked</code> Must use the <code>blocker:{type}</code> format, not a bare "blocked" label.
Remove <code>blocker:internal</code> after the blocking PR merges Leave stale blocker label after dependency clears Blocker labels are transient. Stale labels corrupt board signal.
Ticket stays in <code>next_up</code> with <code>blocker:internal</code> Move blocked ticket to a special "blocked" column No blocked column exists. The label is the signal, not the column.
Apply <code>blocker:external</code> when both external and internal blockers exist Apply both <code>blocker:external</code> and <code>blocker:internal</code> One blocker label per ticket. External dominates because it is harder to resolve.

Board Item Integration

When applying blocker labels to pal-e-docs board items, add them as comma-separated labels alongside the traceability labels:
arch:ci-pipeline,track:devops,type:infra,blocker:internal
The blocker: prefix makes them filterable and auditable.

Enforcement

Convention only. Agents apply blocker labels when creating or updating tickets that have known dependencies. Betty Sue audits boards for blocked items during status reviews. Future hook enforcement may validate that blocker: labels include a description in the ticket body.
  • template-ticket — label conventions table (includes blocker row)
  • convention-kanban-over-plans — kanban flow rules (never skip columns)
  • convention-todo-lifecycle — ticket lifecycle and column flow
  • convention-pipeline-stages — pipeline stages that blockers can gate