pair-capability-publish-pr — gate + PR + tag propagation + git-workflow/conditional sections

[rucka]

Story Statement

As a developer (or an automation loop)
I want pair-capability-publish-pr: standalone-invocable PR step — quality gate → create/update PR from template → propagate story tags → ready-for-review → board state update — driven by a handoff document and the WoW git-workflow section
So that the PR phase is reliable on clean context and reusable (hotfix, automation) outside implement (R4.1)

Where: code host PR (created/updated) + PM tool board state; input from checkpoint/handoff

Epic Context

Parent Epic: Split implement: checkpoint + publish-pr #206
Status: Refined
Priority: P0 (Must-Have)

Status Workflow

• Refined: Story is detailed, estimated, and ready for development
• In Progress: Story is actively being developed
• Done: Story delivered and accepted

Acceptance Criteria

Functional Requirements

Given-When-Then Format:

1. Given a handoff document for a completed story branch
   When publish-pr runs
   Then it executes the quality gate, creates (or updates) the PR from the pr-template, copies the story's estimated classification tags to the PR (no analysis), marks it ready-for-review and updates the board state via mapping

2. Given the WoW declares a git-workflow section (base-branch, branch-format, commit-format, squash: true|false)
   When the PR is prepared
   Then the section is read deterministically — e.g. base-branch: develop + squash: true yields a PR against develop with squashed history; omitted section ⇒ defaults (main, standard templates)

3. Given the diff of the branch
   When the PR body is composed
   Then conditional sections are filled only when pertinent: "Services to Release" (packages/services from git diff --name-only <base>...HEAD grouped by package) and "Screenshots" (before/after, only when the diff touches UI); no empty sections

4. Given the adoption declares a code-host different from the PM tool (Code host separate from PM tool (WoW override) — GitHub + Linear reference case #236)
   When publish-pr runs
   Then the PR targets the code host and cross-links via text convention (Refs: <issue-id>), while board updates go to the PM tool

5. Given the quality gate fails
   When publish-pr runs
   Then it HALTs before creating/updating the PR, reporting the failing checks

Business Rules

• Standalone invocable: no dependency on implement having run in the same session
• Tag propagation is a copy — the authoritative re-classification happens in review (G6)
• Input contract = handoff document (checkpoint format); missing handoff ⇒ gather minimal state from branch + story, then proceed

Edge Cases and Error Handling

• PR already exists for branch: update body/tags instead of creating
• No classification tags on story: PR created without tags (projection may be inactive, D17); noted in output
• Story id not resolvable from handoff/branch: HALT asking for it

Definition of Done Checklist

Development Completion

• All acceptance criteria implemented and verified
• Skill follows authoring conventions (composes verify-quality)
• Code review completed and approved
• Documentation updated — docs site (apps/website) page for the new capability + pr-template changes
• CLI (apps/pair-cli) unaffected verified (template distribution via KB registry as usual)

Quality Assurance

• Standalone run on a hotfix branch (no prior implement session)
• git-workflow variants tested (defaults, custom base, squash on/off)
• Conditional sections verified on UI and non-UI diffs

Story Sizing and Sprint Readiness

Refined Story Points

Final Story Points: 5 (L)
Confidence Level: Medium
Sizing Justification: gate composition + PR mechanics + three adoption-driven behaviors (git-workflow, conditional sections, code-host) — confirmed L(5); the addendum scope is what keeps it above M

Sprint Capacity Validation

Sprint Fit Assessment: yes, single sprint
Total Effort Assessment: fits — Yes

Dependencies and Coordination

Story Dependencies

Prerequisite Stories: checkpoint story (handoff format contract)
Dependent Stories: implement composition story; G10 automation reuses publish-pr (#212); #236 (code-host override) for AC4 — degrades to single-tool if absent
Shared Components: pr-template (KB), verify-quality, write-issue state updates

Validation and Testing Strategy

Acceptance Testing Approach

Testing Methods: end-to-end on pair repo (dogfood PR); matrix of WoW fixtures (defaults / custom git-workflow / code-host split)
Test Data Requirements: branches with UI and non-UI diffs, multi-package diff for Services to Release

Notes and Additional Context

Refinement Session Insights: AC4 ships degraded (single-tool) until #236 lands — no hard dependency
Documentation Links: R4.1, D7 · Spec G5 · #206 addendum (git-workflow, conditional PR sections, code-host)

Technical Analysis

Implementation Approach

Technical Strategy: new capability skill in .skills/capability/publish-pr/: phase 1 gate (compose verify-quality), phase 2 PR compose (template + conditional sections from diff), phase 3 tags copy + ready-for-review + board state via mapping; adoption reads: WoW git-workflow, code-host, state-mapping
Key Components: SKILL.md (phases, HALT on red gate), pr-template conditional sections, diff→package grouping instructions
Integration Points: verify-quality, write-issue (state), checkpoint (input), code host CLI (gh or adoption-declared equivalent)

Technical Risks and Mitigation

Risk	Impact	Probability	Mitigation Strategy
UI-touch detection unreliable	Medium	Medium	path-based heuristic from adoption (UI package globs); when unsure, include section with TODO marker
Gate duplication with CI	Low	Medium	gate = local pre-flight only; CI remains authoritative (#210)

Task Breakdown

Checklist

• T1 — SKILL.md skeleton + gate phase (verify-quality composition, HALT)
• T2 — git-workflow WoW section schema + deterministic read (defaults)
• T3 — PR compose: template + conditional sections (Services to Release, Screenshots)
• T4 — Tag propagation + ready-for-review + board state via mapping; code-host routing
• T5 — Standalone + dogfood E2E + docs site

Dependency Graph

T1 → T2 → T3 → T4 → T5

AC Coverage

Task	AC1	AC2	AC3	AC4	AC5
T1	✓				✓
T2		✓
T3			✓
T4	✓			✓
T5	✓	✓	✓	✓	✓