LT-22723: Agent skills for filing Jira issues and writing PR bodies

[johnml1135]

Filing an LT ticket with an agent now goes through a skill instead of improvisation, and the three skills that already existed lost two thirds of their bulk without losing a rule. /jira-issue interviews for who/when/where/how, searches Jira for duplicates before drafting, gets a three-line lede approved by the developer, caps the description at 250 words, and moves the analysis into the first comment.

LT-22723 was filed by the skill itself as the worked example, and the 28 tickets filed before it were rewritten the same way — median description 368 → 140 words, every original preserved verbatim as a comment.

The unknown you arrive with: why does a set of writing-style skills need 1,500 lines? It doesn't — the branch is net +584, because most of it is deletion. Jira Data Center has no {expand} macro, so nothing in a description can be folded away; every budget here serves that one constraint. There is no product code on this branch. Markdown, plus three lines of .gitignore.

Start here: .claude/skills/jira-issue/SKILL.md — 95 lines, the whole design. The six references/ files are detail it delegates to.

Where to look:

• Two gates block publishing — the duplicate table and the lede approval. If either can be skipped quietly, the skill is decoration; both are written as "never file without".
• compact-style.md is shared, not copied. pr-pitch reads the same file, so ticket style and PR style cannot drift apart.
• The compression is deduplication, not shortening. jira-bugfix carried its own copy of the JIRA API calls, the custom_fields workarounds and the transition rules; it now points at jira-issue/references/publish.md and delegates commits, PRs and coverage to the skills that own them. Read the diff for deletions of duplicated procedure, not for changed rules — a rule that changed meaning is a bug.
• Screenshots get a defined path — capture, curate, publish — with the rule that the test is the evidence and the screenshot is the courtesy. jira_add_attachment is proven against live Jira (LT-22723 carries attachment 154621).
• Nine references pointed at nothing across the Avalonia migration and WinApp skills. Every target existed; the paths were written relative to the skill root while the citing file lives in references/.

Deliberately not here: the Atlassian transport skills, which are a separate PR — they are Python and vendored, and need a different kind of review.

Verification: gitlint clean on all 11 commits. 39/39 key rules survive compression (pr-pitch 15/15, pr-preflight 14/14, jira-bugfix 10/10), checked by grep rather than by eye. Every .md reference in .claude resolves from the directory it is written in — nine dangling before, zero after. Skill frontmatter parses. No trailing whitespace on any added line. No build.ps1 or test.ps1 run: nothing compiled changed. Build\Agent\check-and-fix-whitespace.ps1 errors on a clean branch because it reads a log Tee-Object never creates, so whitespace was verified by hand.

Next: review, or tell me to split the compression commits out of the new-skill commits.

---

Reading this a year from now — start here

This began as four separate PRs — the new skill, the evidence framework, the compression pass, and a reference-path fix — stacked in that order. They were consolidated because they are one story told in four parts, and because the alternative was asking a reviewer to hold four bases in their head. All eleven commits survive, so the original boundaries are still there in git log.

The design was written as a document in Docs/workflows/ and deliberately deleted before merge; it was working scaffolding, not something anyone needs in order to change this code correctly. What follows is that record.

What was measured, before and after

File	Before	After
jira-bugfix/SKILL.md	455	114
pr-pitch/SKILL.md	376	141
pr-preflight/SKILL.md	276	119
jira-issue/SKILL.md	(new) 224 first draft	95

A SKILL.md is loaded whole every time its skill triggers, so every line it holds is context spent whether the reader needs it or not. Procedure only one phase needs now lives in a reference that loads when that phase is reached.

The 28 rewritten tickets: median 368 → 140 words, longest 1,255 → 271, two still over the 250 budget and justified (LT-22709's acceptance-test steps are the deliverable; LT-22715 carries a cause plus four children plus three options).

Decisions, and why

Search before drafting, not before posting. If the ticket already exists, the work is a comment on it. Discovering that after twenty minutes of drafting wastes the drafting.

The lede is approved before anything else is written. Every other budget is enforceable by counting; this one is only enforceable by stopping.

"I don't know" is recorded, not resolved. Missing facts become a *Not known:* line. Nothing enters a description that the reporter did not say or that we did not verify — inferred mechanism goes to the comment, labelled inferred. Fabricated detail in a ticket becomes folklore that outlives the ticket.

Affects Version FW 9.3 on every new ticket, as a filing convention rather than a claim about a build — so the relevance rule that drops FLEx-specific sections from a tooling ticket does not exempt it.

Branches are LT-XXXXX-short-slug. A real session was lost hunting for "the branch for LT-22715" among sixteen descriptively-named worktrees.

Preferences are a gitignored file, not agent memory — portable to any agent this repo supports, and per-clone, so one developer's worktree preference never becomes another's default.

Paths not taken

A second skill pair mirroring pr-preflight / pr-pitch. Two entrypoints for a workflow that is mostly linear. The PR pair earns its split because the write-up gets re-run on existing PRs; a Jira description is rewritten far less often.

Collapsible sections in the description. {expand} is a Confluence macro, not a Jira one — verified absent before the comment split was designed around it. Had it existed, the whole shape would be different.

A standalone compact-writing skill. A fourth skill in the chain, loadable when nobody asked for it. A reference file that two skills read costs less.

An orphan evidence branch hosting screenshots behind sha-pinned raw URLs. Cut before review: speculative, unbuilt, and it traded permanent repo weight for a problem that lasts one review. The honest third route is to hand the file to the author.

Compressing the Atlassian skills here. They are vendored and need their own review; they are the other PR.

The i-have-adhd adaptation

compact-style.md adapts the MIT-licensed i-have-adhd skill. That skill shapes chat turns; these rules shape written artifacts, which changes several:

• "Lead with the next action" becomes "lead with what the reader must decide" — a triager's next action is a triage decision.
• "Give specific time estimates" becomes cost shape, not hours: "needs a liblcm release and a package bump" rather than "about two days". Hours on a ticket read as a commitment nobody in the conversation is authorised to make.
• "Restate state every turn" does not apply to filing; it applies to later comments.
• "Make completed work visible" was dropped — PR territory, not ticket territory.

Two rules were added with no chat equivalent: say what is not known, and never assert what was not verified.

Evidence

The reference failure is real. LT-22715's first rendered line was h3. The underlying problem, its description ran past a thousand words, and it stated in its own text that it contained "four separate user-visible problems". It has since been split into LT-22724 through LT-22727, linked with Issue split, and references/examples.md carries the before-and-after.

The skill was used to file its own ticket. LT-22723 went through the type check, the relevance check (tooling, so no environment or repro sections), three JQL passes finding no duplicate, developer-approved lede, and publish. 232 words against a 250 budget; summary 60 characters against 80.

Jira API surfaces were read, not guessed. jira_create_issue sets {'accountId': ...} for assignee, which is Cloud-only — SIL Jira is Data Center and needs {'name': ...}. resolution cannot be set by an update at all, only by a transition. Both confirmed by hitting them.

The compression was verified by grep, not by reading. Distinctive rules from each original — the 200-400 word budget, the triage buckets, "Always trust the written code", the 65,536 cap, the four analysis passes, "Author does not understand", the TDD escape hatch, "never transition to Done" — were checked present in the compressed files. 39 of 39.

One rule was genuinely dropped, deliberately: jira-bugfix's IDE-Specific Notes, obsolete now that pr-preflight owns PR creation.

---

This change is