pal-e-docs

Review: Branch naming convention — {ticket}-{purpose}

review-198-2026-03-27 Review

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Template Completeness

  • [ ] ### Type — MISSING. Should be "Task" (convention documentation work, no code features).
  • [x] ### Lineage — Present.
  • [x] ### Repo — Present.
  • [x] ### User Story — Present.
  • [x] ### Context — Present and thorough.
  • [x] ### File Targets — Present. (Note: for Task type, template says to use "### Scope" instead of File Targets. However, since the targets are doc notes, not code files, this is acceptable.)
  • [x] ### Acceptance Criteria — Present.
  • [x] ### Test Expectations — Present.
  • [x] ### Constraints — Present.
  • [x] ### Checklist — Present.
  • [x] ### Related — Present.

Traceability

  • [x] story:dev-execute label — Present on board item #198.
  • [ ] arch:X label — MISSING. Recommend arch:conventions or arch:hooks. This is process infrastructure work; it should map to an architecture component.
  • [x] Forgejo issue — forgejo_admin/claude-custom#129, open.

File Targets

  • [x] ~/claude-custom/hooks/ — verified: directory exists, label-on-branch.sh exists. Issue correctly identifies this as location for a possible future validation hook. Currently hooks already parse {issue-num}-{desc} branch names (forgejo-helper.sh:219, board-item-on-merge.sh:8, check-issue.sh:133-145, label-on-pr.sh:45).
  • [x] skill-create-issue in pal-e-docs — verified: exists. Currently has NO mention of branch naming. Valid update target.
  • [x] agent-spawn-conventions in pal-e-docs — verified: exists. Currently has NO explicit branch naming instruction in the minimal prompt pattern or pre-spawn checklist. Valid update target.
  • [x] convention-agent-design in pal-e-docs — verified: exists. No branch naming mentioned. Valid but low-priority target — this note is about agent specialization philosophy, not operational conventions.

Repo Placement

OK. Issue is filed on forgejo_admin/claude-custom which owns the hooks directory. Doc updates go to pal-e-docs via MCP tools, which is the correct pattern for Dottie-executed convention work.

Dependencies

None. No items on the board block or are blocked by this ticket. The convention is already silently enforced by existing hooks — this ticket formalizes the documentation.

Acceptance Criteria

All three criteria are testable and specific:
  • "Convention documented in pal-e-docs" — verifiable by checking for a convention note.
  • "Agent dispatch prompts include branch name instruction" — verifiable by reading agent-spawn-conventions.
  • "Branch name traceable to board item or Forgejo issue number" — already true in practice; this formalizes it.
Observation: The acceptance criteria could be more precise. "Convention documented" could specify whether this is a new convention note (e.g., convention-branch-naming) or an update to an existing note. The issue's File Targets suggest updates to existing notes, but the checklist says "Convention note created or updated" — the agent should know which.

Blast Radius

LOW. This is documentation-only work per the "document first, enforce later" constraint. No hook code changes required.
Important finding: The convention already exists in practice across 6+ locations in code and docs:
  • forgejo-helper.sh line 219: # Convention: branch names are "{issue-num}-{description}"
  • board-item-on-merge.sh line 8: # Parses the issue number from the branch name (convention: {issue-num}-{slug})
  • check-issue.sh lines 133-145: extracts issue numbers from branch names
  • label-on-pr.sh line 6: extracts issue number from PR head branch
  • skill-implement-phase step 5: Branch name: {issue-number}-{short-description}
  • skill-review-pr + QA agent: check "Branch named after issue"
The agent executing this ticket should reference these existing usages rather than inventing a new convention from scratch. The work is consolidation and formalization, not invention.

Recommendation

Two items to fix before READY:
  • Add ### Type header to the Forgejo issue — Should be "Task" per template-issue.
  • Add arch: label to board item #198 — Recommend arch:conventions to complete the traceability triangle.
Optional improvement: Clarify in the issue body whether the deliverable is a new standalone convention note (convention-branch-naming) or updates to existing notes only. The current wording is ambiguous.