pal-e-docs

Board Template

template-board Template

active template
Project

Board Template

When a ticket is too big for a single agent (>5 minutes), it gets decomposed into a board note — a mini project page with its own kanban. The board note is the fractal unit of work decomposition: same structure at every level.

When to Create a Board

  • Project-level: every project gets one board (via template-project-page). This template is NOT for those.
  • Ticket decomposition: when /review-ticket determines a ticket is too large for a single agent pass (>5 min rule), the ticket gets a board note. This template IS for those.
  • The signal: if you can't describe the acceptance criteria in a single Forgejo issue that an agent could finish in under 5 minutes, the ticket needs a board.

Template

Section Order

  • Parent — what triggered the decomposition (link to parent issue/board item)
  • User Stories — references user-story notes from the parent project; lists which stories this board serves with story: labels matching story note Key fields
  • Architecture — references architecture notes (note_type: architecture) from the parent project; lists arch: labels matching architecture note slugs
  • Acceptance Criteria — whole-ticket completion criteria
  • Kanban — the board itself (implicit — the note IS the board)

Naming Convention

Slug: board-{parent-issue-number}-{short-description} (e.g., board-201-app-migration)
Note type: board
Tags: active
Project: same project as the parent ticket

Linking

The decomposition creates a two-way link:
  • Parent Forgejo issue gets a ### Board section with: Decomposed into board note: board-{slug}
  • Board note has a ### Parent section linking back to the Forgejo issue
  • Each sub-ticket Forgejo issue body includes: Parent board: board-{slug}

Relationship to Project Boards

Aspect Project Board Ticket Board (this template)
Created by <code>template-project-page</code> This template, when ticket &gt;5 min
User Stories Full project stories Scoped subset referencing parent keys
Architecture Three full diagrams References parent diagrams + focused additions
Scope Entire project lifetime One parent ticket's decomposition
When done Never (permanent) Archived when parent ticket completes

The Fractal Rule

If a sub-ticket on this board is ALSO too big (>5 min), it gets its own board note. Same template, one level deeper. There is no depth limit, but more than 2 levels deep is a smell — the original ticket was probably an epic that should have been multiple project-level tickets.

Review Integration

/review-ticket checks for decomposition need:
  • If the ticket has >3 file targets across >2 repos → suggest decomposition
  • If the ticket has >5 acceptance criteria → suggest decomposition
  • If estimated agent work >5 minutes → NEEDS_REFINEMENT with recommendation to create a board note
After decomposition, each sub-ticket goes through /review-ticket independently.
  • template-ticket — board item conventions (traceability triangle)
  • template-user-story — user story note format referenced by board User Stories section
  • note-conventions — canonical reference for note types, slugs, tags, and linking
  • template-project-page — the project-level equivalent (Vision + User Stories + Architecture + Board)
  • template-issue — Forgejo issue format for sub-tickets
  • sop-board-workflow — column semantics
  • skill-review-ticket — the review process that triggers decomposition
  • convention-kanban-over-plans — "a sub-board IS a plan"
  • convention-architecture-ids — arch: label naming