diff options
| -rw-r--r-- | teams/deepsat/claude/rules/publishing.md | 21 |
1 files changed, 17 insertions, 4 deletions
diff --git a/teams/deepsat/claude/rules/publishing.md b/teams/deepsat/claude/rules/publishing.md index c919d3c..c184c08 100644 --- a/teams/deepsat/claude/rules/publishing.md +++ b/teams/deepsat/claude/rules/publishing.md @@ -10,21 +10,34 @@ DeepSat tracks work in Linear. Tickets carry IDs like `SE-289`. **PR title.** Append the ticket ID in parentheses to the conventional-commit subject: `refactor: remove dead if-count check in admin (SE-289)`. If there is no ticket, omit the parenthetical. -**PR body cross-link.** Include a `Linear: [<TICKET-ID>](<linear-url>)` line so Linear's GitHub integration auto-cross-links the PR to the ticket. If there is no ticket, state it explicitly (`Linear: n/a`) so reviewers know it was considered. +**PR body cross-link.** Include a `Linear: [<TICKET-ID>](<linear-url>)` line linking the PR to the ticket. If there is no ticket, state it explicitly (`Linear: n/a`) so reviewers know it was considered. **Linear ticket bodies** (when you write or update a ticket) carry two sections, in order: 1. **Problem** — what's wrong, with enough detail that a teammate can recognize the same failure mode in their own work. 2. **Fix** — what changed (or what's proposed). -The causal "why" and the test verification belong in the PR, not the ticket. Linear's GitHub integration auto-cross-links once the PR body includes the `Linear:` line, so the ticket reader reaches the PR without a body-level link. +The causal "why" and the test verification belong in the PR, not the ticket. The ticket reader reaches the PR through the manual cross-link comment in the post-create step below, not through any automatic integration. + +## Linear ticket state is manual (no GitHub-integration automation) + +The Linear↔GitHub integration does **not** move ticket state for us. It never advances a ticket to Dev Review when a PR opens, and it never moves a merged ticket onward to PM Acceptance or Done — confirmed 2026-05-22, when two merged PRs (SE-286, SE-399, both chores) sat in Dev Review until moved to Done by hand. Treat every ticket-state transition as a manual step we own. Don't wait for the integration to catch up, because it won't. ## After `gh pr create` (ticket reconciliation) Run these where the global PR-description subflow says to run the project's post-create overlay steps: -1. Post a comment on the linked Linear ticket with the PR URL (Linear MCP `save_comment`, or open the ticket manually if MCP is unavailable). This closes the ticket→PR direction of the cross-link. -2. Move the Linear ticket to the **Dev Review** status (`save_issue` with the Dev Review state ID, or the Linear UI). The ticket should not remain "In Progress" once a PR is open against it. +1. Post a comment on the linked Linear ticket with the PR URL (Linear MCP `save_comment`, or open the ticket manually if MCP is unavailable). This is the reliable PR↔ticket cross-link. +2. Move the Linear ticket to the **Dev Review** status (`save_issue` with `state="Dev Review"`, or the Linear UI). The ticket should not remain "In Progress" once a PR is open against it. + +## After merge (ticket → PM Acceptance or Done) + +When a PR merges, move its linked Linear ticket yourself (`save_issue`, or the Linear UI) — nothing does this automatically. The target state depends on whether the PM can review the work: + +- **Bug or feature with functionality or UI the PM should review** → **PM Acceptance** (`save_issue` with `state="PM Acceptance"`). The merge is done, but the ticket isn't closed until the PM signs off on the behavior. The later PM Acceptance → Done move is the PM's call, not ours. +- **Chore, tests, or an infra change the PM can't meaningfully review** → **Done** (`state="Done"`) directly. There's nothing for the PM to accept. + +The ticket's label is the quick signal (Bug/Feature vs Chore/Test/Infra), but the real test is whether there's user-facing behavior to approve. Do the move right after `gh pr merge` reports the merge, the same way the Dev Review move rides along with `gh pr create`. If a batch of PRs merged without their tickets following, reconcile them: list the merged PRs, pull each `SE-xxx` ID, and route each ticket to PM Acceptance or Done by the same test. ## GitHub Enterprise host |