Skip to content
sdlc

T-UNUH-codify-task-branch-naming

Status: closed/done · Impact: low · Complexity: small

Auto-generated from a /sdlc:task-work post-mortem. Review and promote to ready before picking up.

Goal

Section titled “Goal”

The SDLC skills implicitly assume feat/<task-basename> is the only branch a task ever lives on, but in practice the T-DHGL-build-import-planning-skill flow used three distinct prefixes (docs/, feat/, chore/) for spec PR, implementation PR, and skill-runtime worktrees respectively. Codifying the convention in the relevant skills removes a recurring “which prefix do I use here?” judgment call.

Today

Section titled “Today”

From the post-mortem:

“Branch naming for the spec PR vs the implementation PR required a conscious split (docs/<basename> for the spec, feat/<basename> for the implementation, chore/import-planning for skill-runtime worktrees) to avoid future collisions. Worth codifying — task-work’s docs assume feat/<basename> is always the implementation branch but don’t speak to spec-only PRs.”

Today, neither plugin/skills/task-work/SKILL.md nor plugin/skills/task-new/SKILL.md nor plugin/skills/task-define/SKILL.md mention spec-PR branches at all. Spec PRs are produced by task-define or by ad-hoc manual edits, and the branch prefix is picked freshly each time.

Proposed

Section titled “Proposed”

Add a “Branch naming” note to:

  • plugin/skills/task-new/SKILL.md — docs/<basename> for spec-only PRs produced before code starts.
  • plugin/skills/task-define/SKILL.md — same.
  • plugin/skills/task-work/SKILL.md — feat/<basename> for implementation PRs (already used, just document it explicitly); call out the contrast with docs/ so users don’t collide branches.
  • Mention chore/<short-slug> for skill-runtime / migration worktrees in any skill that spins one up (entities-migrate, import-planning, project-cleanup).

Approach

Section titled “Approach”
  1. Draft a single shared “Branch naming conventions” block (~6 lines).
  2. Inline it into each of the four+ SKILL.md files above under a “Conventions” or “Notes” subsection.
  3. Optionally extract to plugin/entities/task/branch-naming.md and reference from each skill — but only if more than one skill ends up wanting the same prose verbatim. Inline-first is fine.

Files to touch

Section titled “Files to touch”
  • plugin/skills/task-new/SKILL.md — add Branch naming note.
  • plugin/skills/task-define/SKILL.md — add Branch naming note.
  • plugin/skills/task-work/SKILL.md — document feat/<basename> and contrast with docs/<basename>.
  • plugin/skills/entities-migrate/SKILL.md — note chore/<slug>.
  • plugin/skills/import-planning/SKILL.md — note chore/<slug>.
  • plugin/skills/project-cleanup/SKILL.md — note chore/<slug>.

Acceptance criteria

Section titled “Acceptance criteria”
  • AC-1: Each of the listed SKILL.md files has a “Branch naming” bullet citing the prefix it expects. Each bullet references the shared canonical doc at plugin/conventions/branch-naming.md.
  • AC-2: The canonical convention lives in exactly one place (plugin/conventions/branch-naming.md); per-skill bullets reference it rather than duplicating the wording. (Revised from the original “same wording across files” AC per PR #22 review feedback — shared reference is the right shape; verbatim duplication across files drifts silently when the convention evolves.)
  • AC-3: /project-check still passes after the edits.

Out of scope

Section titled “Out of scope”
  • Enforcing the convention with a git hook or pre-flight check.
  • Renaming any existing branches.

Dependencies

Section titled “Dependencies”
  • none

Discovery context

Section titled “Discovery context”

Spawned by /sdlc:task-work post-mortem of T-DHGL-build-import-planning-skill on 2026-05-19.

Post-mortem

Section titled “Post-mortem”

Captured by /sdlc:task-work on 2026-05-19. PR: #22.

Acceptance criteria coverage

Section titled “Acceptance criteria coverage”
  • AC-1: auto — grep -rn 'branch-naming.md' plugin/skills/ returns 6 hits, one per affected SKILL.md.
  • AC-2: auto — grep -rn 'feat/<basename>' plugin/skills/ returns zero hits (the convention text lives in plugin/conventions/branch-naming.md only); each SKILL.md carries a single one-line reference.
  • AC-3: auto — /project-check passes (check_entities.py clean; prose linter from PR #19 still passes against the 4 skills with invariants.yaml).

What worked

Section titled “What worked”
  • Same pattern that landed in PR #21 (plugin/conventions/commit-messages.md) applied cleanly here. Two refactors in quick succession reinforce the pattern as the right shape for skill-prose conventions.
  • Per-skill bullets are short and context-specific (each cites the prefix that skill itself uses), so the cross-reference does work beyond just “see file X” — readers in any single SKILL.md still get the answer they need without clicking through.

Friction and automation gaps

Section titled “Friction and automation gaps”
  • Original spec AC-2 mandated “same wording across files” — i.e. it explicitly endorsed duplication. Same shape mismatch as PR #21’s AC-1. Same automation gap: the prose linter from PR #19 should grow a “verbatim multi-line block in N>1 SKILL.md files” invariant to catch this pattern at PR-open time. Worth filing as a follow-up.
  • Spawn-from-post-mortem produced this AC literally from a one-line friction bullet (“document branch-naming in task-work and task-new SKILL.md”) and the sub-agent went broad (“document in all skills that touch branches”). The user’s “Can we parameterize this?” comment caught the inline-everywhere shape — a pre-promotion question on shape (“shared doc vs inline?”) would have produced the right AC from the start.

← Back to Tasks