pal-e-docs

Review: Convention updates — kanban alignment from Capacitor dogfood

review-403-2026-03-27 Review

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Template Completeness

Issue type: Feature. Checked against template-issue-feature.
  • [x] Type
  • [x] Lineage
  • [x] Repo
  • [x] User Story
  • [x] Context
  • [x] File Targets
  • [x] Acceptance Criteria
  • [x] Test Expectations
  • [x] Constraints
  • [x] Checklist
  • [x] Related
All required sections present. Template is complete.

Traceability

  • [x] story:pm-scope label — Betty Sue PM scoping story
  • [x] arch:board-api label — board API component
  • [x] Forgejo issue — forgejo_admin/pal-e-platform#183, open
Traceability triangle complete.

File Targets

  • [x] template-ticket — verified: "assigns points" still present in Ticket Lifecycle section (both PATH 1 and PATH 2). The "What a Ticket Is" table already has points removed, so only the lifecycle code block needs updating.
  • [x] sop-board-workflow — verified: triage step 3 still says "add labels, assign points." Needs "assign points" removed and WIP limit guidance added.
  • [x] convention-kanban-over-plans — verified: note exists, has no cross-repo board section. Addition is valid.
  • [x] convention-architecture-ids — verified: deployment components table exists, has no arch:tailscale-subnet. Row addition is valid.
  • [x] sop-capacitor-mobile-lifecycle — verified: currently ends at Stage 4 (Production Deploy). Stages 5-6 and Gates 3-5 are valid additions.
  • [x] NEW: convention-pipeline-stages — verified: does not exist yet. Creation is valid.
  • [x] NEW: convention-blocker-labels — verified: does not exist yet. Creation is valid.
All file targets verified. No invalid paths or stale references.

Repo Placement

Issue filed on forgejo_admin/pal-e-platform but all changes are pal-e-docs note updates via MCP tools. The issue acknowledges this: "conventions live in pal-e-docs, but tracked here as platform scope." This is acceptable — the conventions are organizational scope owned by platform governance, even though the writes go through pal-e-docs API.

Dependencies

  • No blocking dependencies found in in_progress column.
  • Board item #397 ("Update 11 SOPs/conventions for kanban-over-plans") is in done — that prior work already removed points from the template-ticket field table. This ticket covers the remaining "assigns points" references in lifecycle diagrams. No conflict.
  • Board item #398 ("Board hygiene — label unlabeled items") is in done — label conventions are stable.

Acceptance Criteria

6 acceptance criteria. Each is verifiable by reading the relevant note after update:
  • [x] "Points removed from template-ticket and sop-board-workflow" — verifiable via get_note + search for "points"
  • [x] "Cross-repo board pattern documented" — verifiable via get_section on convention-kanban-over-plans
  • [x] "consumer:X label pattern documented" — verifiable via get_section
  • [x] "Pipeline stages convention created" — verifiable via get_note(slug=convention-pipeline-stages)
  • [x] "Blocker label convention created" — verifiable via get_note(slug=convention-blocker-labels)
  • [x] "Capacitor SOP expanded with Stages 5-6" — verifiable via get_note_toc showing Stage 5 and Stage 6 headings
All criteria are agent-verifiable. However, the 6 criteria map to 7 distinct note operations, which exceeds the 5-minute rule.
Test Expectations are weak: "QA agent reviewing a new ticket no longer flags missing points" is behavioral and depends on hook logic in claude-custom, not just note content. "New board items follow the updated conventions" is aspirational. Neither is machine-testable from note content alone.

Blast Radius

  • Points references: Only 2 notes contain "assign points" (template-ticket lifecycle, sop-board-workflow triage step 3). No other notes affected.
  • Hook downstream: claude-custom/hooks/session-start-context.sh line 291 still says "with points and labels" in its board item creation prompt. This is a downstream artifact not covered by this ticket — needs a separate follow-up issue in claude-custom.
  • Hook status: claude-custom/hooks/check-board-item.sh already treats points as optional (line 10: "points are optional"). No hook change needed for the convention update itself.
  • Label conventions: Adding consumer:X and blocker:X patterns to template-ticket Label Conventions table should also be considered. The issue does not mention updating that table — potential gap.
  • Existing board items: Some board items in backlog/todo still have points values (items #322, #360, etc.). The issue says "additive changes only" — removing the points convention from docs while legacy items still carry points is fine. The API field remains, conventions just stop requiring it.

Decomposition

Triggers hit:
  • 7 file targets (exceeds 3-target threshold)
  • 6 acceptance criteria (exceeds 5-criteria threshold)
  • Estimated agent work: 10-15 minutes (exceeds 5-minute threshold)
NEEDS DECOMPOSITION — recommend template-board with 3 sub-tickets:
  • Points cleanup (2 targets, ~2 min): Remove "assigns points" from template-ticket lifecycle + sop-board-workflow triage step 3.
  • Convention updates (3 targets, ~5 min): Add cross-repo board section to convention-kanban-over-plans, add arch:tailscale-subnet to convention-architecture-ids, expand sop-capacitor-mobile-lifecycle with Stages 5-6.
  • New conventions (2 targets, ~5 min): Create convention-pipeline-stages and convention-blocker-labels.

Recommendation

  • [DECOMPOSE] 7 targets across 6 AC, split into 3 tickets via template-board. Each sub-ticket fits the 5-minute rule.
  • [BODY] Add consumer:X and blocker:X to the template-ticket Label Conventions table in the appropriate sub-ticket (likely ticket 1 or 3).
  • [BODY] Downstream blast radius: note that session-start-context.sh line 291 ("with points and labels") needs a separate follow-up ticket in claude-custom.
  • [BODY] Test Expectations are weak — suggest replacing with verifiable checks: "Read each updated note via MCP and confirm section/field changes are present."
  • [BODY] Ticket Lifecycle in template-ticket still references "Plan-driven" PATH 1 with phase notes and sync_board. Per feedback_kanban_over_plans.md, plans are obsolete. Out of scope for this ticket — track as discovered scope.