pal-e-docs

Ticket Template

template-ticket Template

active template
Project

Ticket Template

A ticket is a board item on the kanban — the card you see and move through columns. It is the bridge between planning (pal-e-docs) and execution (Forgejo). Every ticket answers three questions at a glance:
  • Why are we doing this? → User story
  • What part of the system does it touch? → Architecture diagram
  • How is it scoped? → Plan phase
This is the traceability triangle. When any leg changes, the other two need to be checked for alignment. The ticket is where these three things meet.

What a Ticket Is

Field What it does Convention
<code>title</code> What shows on the kanban card Short, action-oriented. "Add Postgres sidecar", not "Phase 3".
<code>item_type</code> Categorization <code>issue</code> for Forgejo issues, <code>incident</code> for incident remediation, <code>repo</code> for repo onboarding
<code>forgejo_issue_url</code> Links to the Forgejo issue (dev agent spec) Required. The Forgejo issue IS the spec. Added when Betty Sue creates the issue.
<code>labels</code> Structured metadata for traceability and filtering See Label Conventions below.
<code>column</code> Where the ticket sits on the board Per <code>sop-board-workflow</code> column semantics.

Label Conventions

Labels are comma-separated key:value pairs. They carry the traceability triangle at a glance — you should be able to read a ticket's labels and know which user story it serves, which architecture component it touches, and what workflow track it belongs to.
Category Format Purpose Examples
<strong>story</strong> <code>story:{key}</code> References a user-story note's Key field. <code>story:{key}</code> where key matches the Key field of a user-story note (e.g., <code>story:roster-view</code> references <code>story-westside-roster-view</code>) <code>story:log-code</code>, <code>story:slots-remaining</code>, <code>story:admin-stats</code>
<strong>arch</strong> <code>arch:{component}</code> References an architecture note (note_type: architecture). <code>arch:{component}</code> where component matches an architecture note slug (e.g., <code>arch:deployment</code> references <code>arch-deployment-westside</code>). See <code>convention-architecture-ids</code> for naming patterns. <code>arch:board-api</code>, <code>arch:postgres</code>, <code>arch:ci-pipeline</code>
<strong>track</strong> <code>track:{workflow}</code> Which development workflow track (for multi-track projects) <code>track:devops</code>, <code>track:backend</code>, <code>track:frontend</code>, <code>track:mobile</code>
<strong>type</strong> <code>type:{kind}</code> Nature of the work <code>type:feature</code>, <code>type:bug</code>, <code>type:infra</code>, <code>type:docs</code>
<strong>scope</strong> <code>scope:{origin}</code> How this work originated <code>scope:planned</code>, <code>scope:unplanned</code>, <code>scope:nit</code>, <code>scope:epilogue</code>
<strong>consumer</strong> <code>consumer:{project}</code> Which downstream project consumes or depends on this work. Used for cross-repo dependencies where one project's ticket blocks or enables another project. <code>consumer:westside</code>, <code>consumer:mcd-tracker</code>, <code>consumer:pal-e-app</code>
<strong>blocker</strong> <code>blocker:{type}</code> Marks a ticket that cannot progress. <code>blocker:external</code> = blocked by something outside the team (vendor, upstream). <code>blocker:internal</code> = blocked by another ticket, PR, or decision within the platform. See <code>convention-blocker-labels</code> for full rules. <code>blocker:external</code>, <code>blocker:internal</code>
Not every ticket needs every label. A devops infra ticket might have arch:deployment,track:devops,type:infra but no story: because it's foundational work that enables stories without being one. A bug fix might have type:bug,scope:unplanned and inherit the story/arch from the phase it interrupted.

User Story Keys

Each project's user stories are now their own notes (type: user-story, slug: story-{project}-{key}). The Key field on each user-story note is what ticket labels reference. Keys are defined per-project, not globally. Example for mcd-tracker:
Key Story
<code>log-code</code> I want to log a coupon code when I get a receipt
<code>slots-remaining</code> I want to see how many codes I have left at each location
<code>reopen-countdown</code> I want to know when my next slot reopens
<code>redeem</code> I want to mark a code as redeemed
<code>history</code> I want to browse my history of codes and redemptions
<code>admin-stats</code> I want to see aggregate usage stats
Add a "Key" column to the User Stories table on the project page so the mapping is always visible.

The Traceability Triangle

When to check alignment:
  • Creating a ticket — Does the Forgejo issue serve a user story? Does it touch an architecture diagram?
  • Issue scope changes — Does the user story still match? Does the diagram still reflect reality?
  • A user story changes — Which tickets are affected? Which diagrams need updating?
  • After merge — If the work changed the architecture, update the diagram. This should surface in /update-docs.
The triangle doesn't create overhead — it creates conversations. When Betty Sue creates a ticket and can't fill in a story or arch label, that's a signal: either the work is foundational (fine, leave it blank) or the planning is incomplete (stop and scope).

Ticket Lifecycle

Example: Board Item for mcd-tracker

Note: story: label is optional for foundational infra work. The absence of the label communicates that clearly. All board items are backed by Forgejo issues — the issue is the spec.

What This Template Does NOT Cover

  • Forgejo issue format → see template-issue. That's the dev agent spec, downstream of the ticket.
  • Phase note structure → see template-phase. That's the planning detail, upstream of the ticket.
  • Column semantics → see sop-board-workflow. This template defines what's ON the card, not which column it's in.
  • template-user-story — user story note format (story: label source)
  • template-board — board structure where tickets live as items
  • note-conventions — canonical reference for note types, slugs, tags, and linking
  • sop-board-workflow — column semantics + flow rules
  • template-issue — Forgejo issue format (created from ticket at next_up)
  • template-phase — phase note structure (ticket links to this via note_slug)
  • template-plan — plan structure (phases become tickets via sync_board)
  • template-project-page — user stories table lives here
  • convention-architecture-ids — canonical arch: component ID naming and examples