fix(skills): start tag annotation with blank line when no custom title

[rh-hemartin]

Summary

• GoReleaser reads the first non-empty annotation line as .TagSubject, causing verbose release titles (e.g. v0.9.0: Features - Docs sidebar search filter…) when no custom title is given
• Updates step 6 of the cutting-releases skill to require a blank first line instead of "start the body directly with highlights"

Closes #1237

Test plan

• Cut a release with no custom title — verify release title is just the tag (e.g. v0.9.0)
• Cut a release with a custom title — verify title renders as vX.Y.Z: Custom Title

🤖 Generated with Claude Code

[github-actions]

Site preview

Preview: https://7cfcddee-site.fullsend-ai.workers.dev

Commit: d719299d7bb17fa8dcad62614ee754bb7f8130bf

[fullsend-ai-review]

Review

Findings

Low

• [structural-consistency] skills/cutting-releases/SKILL.md:88 — The new three-bullet structure (Line 1, Line 2, Lines 3+) differs from the original two-bullet pattern used in similar procedural lists in sibling skills. The addition of "Line 2: Blank" is technically accurate and important for the GoReleaser guard mechanism, but breaks the established pattern.

• [emphasis-style] skills/cutting-releases/SKILL.md:84 — Step 6 bolds the entire phrase ("use the tag name itself") while step 4's corresponding instruction at line 67 uses unbolded prose. Minor inconsistency in emphasis style within the same document.

Info

• [documentation-clarity] skills/cutting-releases/SKILL.md:67 — The updated steps 4 and 6 now correctly explain the underlying mechanism: setting .TagSubject == .Tag triggers the ne guard in .goreleaser.yml:62, suppressing the suffix and producing a clean release title. This is a clear improvement over the prior instruction to "leave the subject empty," which did not work because %(contents:subject) skips leading blank lines.

Previous run

Review

Findings

Low

• [formatting-inconsistency] skills/cutting-releases/SKILL.md:88 — The new three-bullet structure (Line 1, Line 2, Lines 3+) differs from the original two-bullet pattern. However, making the blank line explicit improves clarity for agents following these instructions. Consider incorporating "Line 2: Blank" into the Line 1 bullet's explanation to keep a two-item structure if preferred.

• [prose-style] skills/cutting-releases/SKILL.md:83 — Step 4 bolds the negation ("do not use") while step 6 bolds the entire phrase ("use the tag name itself"). Minor inconsistency in emphasis style — consider bolding just the verb for consistency (e.g., "use the tag name itself").

Info

• [documentation-detail] skills/cutting-releases/SKILL.md:83 — The new step 6 explanation includes significantly more technical detail about %(contents:subject) behavior and GoReleaser guard mechanics compared to the concise style of surrounding sections. Consider moving the git internals explanation to a note after the bullet list or near the existing name_template paragraph at line 92.

• [documentation-clarity] skills/cutting-releases/SKILL.md:64 — The updated step 4 and step 6 now correctly explain the underlying mechanism (setting .TagSubject == .Tag to trigger the guard) rather than the prior incorrect instruction to "leave the subject empty." This is a clear improvement.

Previous run (2)

Review

Findings

Medium

• [correctness] skills/cutting-releases/SKILL.md:64-66 — Step 4 contradicts the updated step 6. Step 4 still reads: "If blank, do not use the version as the subject — leave the subject empty so that GoReleaser's name_template renders just the tag without duplication." But step 6 now instructs the opposite: "If no custom title, use the tag name itself." The PR's own diff explains why leaving the subject empty doesn't work (%(contents:subject) skips leading blank lines), yet step 4 still tells the agent to leave it empty. An agent following step 4 would produce the wrong annotation.
  Remediation: Update step 4 (lines 64-66) to match the new step 6 approach — e.g. "If blank, use the tag name as the subject line so that GoReleaser's name_template guard (ne .TagSubject .Tag) suppresses it, producing a clean release title."

• [protected-path] skills/cutting-releases/SKILL.md — This file is under skills/, a protected path that requires human approval. The PR links to cutting-releases skill produces verbose release titles when no custom title is given #1237 and the description explains the rationale (GoReleaser reads the first non-empty annotation line as .TagSubject, producing verbose release titles when no custom title is given). Human approval is required for protected-path changes regardless of context.

Previous run (3)

Review

Findings

Medium

• [protected-path] skills/cutting-releases/SKILL.md — This file is under skills/, a protected path that requires human approval. The PR links to cutting-releases skill produces verbose release titles when no custom title is given #1237 and the description explains the rationale (GoReleaser reads the first non-empty annotation line as .TagSubject, producing verbose release titles when no custom title is given). The fix correctly changes the instruction from "omit the subject line" to "line 1 must be blank" and updates the body line reference from "Lines 3+" to "Lines 2+". Human approval is required for protected-path changes regardless of context.

Previous run (4)

Review

Findings

No findings.

[ralphbean]

I think this needs a tweak before we merge. See inline.

[fullsend-ai-review]

[low] formatting-inconsistency

The new three-bullet structure (Line 1, Line 2, Lines 3+) differs from the original two-bullet pattern. Making the blank line explicit improves clarity, but consider incorporating it into the Line 1 bullet to maintain a two-item structure.

[fullsend-ai-review]

[low] prose-style

Step 4 bolds the negation (do not use) while step 6 bolds the entire phrase (use the tag name itself). Minor emphasis inconsistency — consider bolding just the verb for consistency.

[fullsend-ai-review]

[info] documentation-detail

Step 6 explanation includes significantly more technical detail about %(contents:subject) behavior and GoReleaser guard mechanics compared to surrounding sections. Consider moving git internals explanation to a note or near the existing name_template paragraph.

[fullsend-ai-review]

[info] documentation-clarity

Updated step 4 and step 6 now correctly explain the underlying mechanism (setting .TagSubject == .Tag to trigger the guard) rather than the prior incorrect instruction to leave the subject empty. Clear improvement.

[ralphbean]

LGTM. Steps 4 and 6 are consistent now and the goreleaser guard does the rest. Just needs a rebase to resolve the merge conflict.

[fullsend-ai-retro]

Retro: PR #1239 — fix(skills): start tag annotation with blank line when no custom title

This was a human-authored, single-file documentation fix to the cutting-releases skill. The PR took 19 days from open to merge, with 5 review agent cycles and 3 merge queue attempts.

Timeline

1. May 20: Issue cutting-releases skill produces verbose release titles when no custom title is given #1237 filed and PR opened within 36 seconds (agent-assisted). Initial approach tried to use a blank first line in the tag annotation — fundamentally flawed because git's %(contents:subject) skips blank lines.
2. May 20: Review agent approved with no findings on the flawed approach (false negative).
3. May 28: Human reviewer (ralphbean) caught the real issue and requested changes.
4. June 1: Review agent run docs: Add codebase context problem document and trim CLAUDE.md #3 independently flagged the step 4 vs step 6 contradiction (same issue the human caught).
5. June 5: Fix applied using tag name as subject line. Human and agent both approved.
6. June 8: Three merge queue attempts — first two ejected due to GitHub 504 outages hitting TestResolveLinuxBinary_Download (which makes live HTTP calls to GitHub's release CDN). Merged on third attempt ~3 hours later.

Key observations

• Review quality (false negative): The review agent approved a fundamentally flawed approach on the first run. However, this pattern is already extensively tracked — 15+ open issues target review agent false negatives, and recently-closed Review agent should evaluate approach soundness, not just implementation correctness #1999 directly addressed "approach soundness vs implementation correctness." No new proposal warranted.
• Redundant review cycles: 5 review runs for a 1-file, 14-line doc change. This is also heavily tracked with 20+ open issues covering debouncing, skip conditions, and fast paths (notably Review orchestrator: add fast path for trivial docs/prompt-only changes #1900 for trivial docs changes, Skip re-review when PR diff is unchanged after rebase/reopen #1356 for rebase-only re-reviews).
• Merge queue fragility: TestResolveLinuxBinary_Download makes live HTTP calls to GitHub's release CDN, causing merge queue ejections during GitHub outages. This affected 5 PRs on June 8. No existing issue covers this — proposal filed below.

Proposals filed

• TestResolveLinuxBinary_Download should not make live HTTP calls to GitHub CDN (in fullsend-ai/fullsend)