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

[johnml1135]

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

Filing an LT ticket with an agent now goes through a skill instead of improvisation, and the three existing skills lost two thirds of their bulk without losing a rule. /jira-issue interviews for who/when/where/how, searches for duplicates before drafting, gets a three-line lede approved, 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; the 28 tickets before it were rewritten the same way — median description 368 → 140 words, every original preserved verbatim as a comment.

Jira Data Center has no {expand} macro, so nothing in a description folds away — every budget here serves that constraint. No product code: markdown, plus three .gitignore lines. Net +584, mostly deletion.

Where to look:

• Three gates block publishing — duplicate table, lede approval, permission to post. If any can be skipped quietly, the skill is decoration.
• compact-style.md is shared, not copied. pr-pitch reads the same file, so ticket and PR style cannot drift apart.
• The compression is deduplication. jira-bugfix carried its own copy of the JIRA calls, custom_fields workarounds and transition rules; it now points at publish.md. Read the diff for deleted duplication, not for changed rules — a rule that changed meaning is a bug.
• Screenshots get a defined path, under the rule that the test is the evidence and the screenshot is the courtesy. jira_add_attachment is proven against live Jira (LT-22723, attachment 154621).
• Nine references pointed at nothing. The targets existed; the paths were written relative to the skill root, not to the citing file in references/.

Deliberately not here: the Atlassian transport skills — that is #1101, already open, which reduces both variants to Jira and fixes their broken modules. This branch touches two of their files only, because it deletes a workaround that named them.

Verification: gitlint clean on 12 commits. 39/39 key rules survive compression, checked by grep. Every .md reference in .claude resolves from where it is written — nine dangling before, zero after. The two vendored modules this branch repairs were imported and called against live Jira. Nothing compiled changed, so no build.ps1; whitespace was verified by hand, because check-and-fix-whitespace.ps1 errors on a clean branch.

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 on every new ticket, derived from Src/MasterVersionInfo.txt, 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.

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 

[jasonleenaylor]

The best part of this branch is the deduplication: jira-bugfix stops carrying its own copy
of the Jira API procedure and delegates commits to commit-messages, PR bodies to
pr-preflight, and coverage to fieldworks-test-coverage, with an explicit "Never
hand-write a PR body". pr-preflight and pr-pitch are extended in place rather than forked.
compact-style.md is one file with two consumers instead of a copy. That is the right shape.

Two other things worth saying before the list. Deleting the stray ```skill fence at
the top of jira-bugfix/SKILL.md is a real defect fix — that fence makes the frontmatter
unparseable, which is why the skill currently advertises itself in the loaded skill list with
the description "```skill". And the security guidance in .claude/references/evidence.md:68-78
is genuinely good: naming the `user_session` cookie as full-account access that bypasses 2FA,
forbidding `gh image extract-token` in an agent session because stdout becomes context, and
requiring the developer to set the token in their own shell rather than paste it into a prompt.
That is the right instinct written down correctly.

1. Fix the Optional import; do not route Jira reads through the write-capable scripts.

jira-issue/references/publish.md:74-79 and SKILL.md:63-65 tell every agent to use the
atlassian-skills copies of jira_workflow.py and jira_projects.py "for reads as well as
writes, until the read-only ones are fixed."

The bug is real:

atlassian-skills/scripts/jira_workflow.py:12           from typing import Any, Dict, Optional
atlassian-readonly-skills/scripts/jira_workflow.py:11  from typing import Any, Dict
atlassian-skills/scripts/jira_projects.py:14           from typing import Any, Dict, Optional
atlassian-readonly-skills/scripts/jira_projects.py:13  from typing import Any, Dict

The fix is , Optional on two lines, in this repo. What is shipping instead is a standing
instruction, in an always-loaded skill, to perform reads with the script set that can create,
update, delete and transition — and it contradicts three places, none of which this PR updates:

• AGENTS.md:59 — for LT- tickets use .claude/skills/atlassian-readonly-skills/scripts.
• atlassian-skills/SKILL.md:23 — "Default to atlassian-readonly-skills for read operations.
  Use this full skill set only when the user explicitly requests create/update/delete."
• Docs/workflows/ai-pr-workflow.md:45 — same read-only invocation.

This is not a credential leak, but it is a permanent widening of blast radius adopted as a side
effect of not fixing a typo. Please add the import and delete the workaround sections; the
AGENTS.md conflict disappears with them, and the change is smaller than the workaround it
replaces.

Note the scope is narrower than the workaround implies — only those two scripts are affected.
Reads through the other read-only scripts work today.

2. Restore the dropped anti-fabrication rule.

The pre-compression pr-preflight/SKILL.md opened Setup with: "Determine the review model
name. Use GitHub Copilot when running in Copilot. Do not invent AI co-author trailers."

Neither half survives. Searching the branch's pr-preflight/SKILL.md for
co-author|trailer|Review model returns zero matches, while
pr-preflight/references/summary-template.md:11 still requires a **Review model**: <model name> field. So the agent is asked to fill in a field it is no longer told how to determine,
and the sentence forbidding it to invent attribution is gone.

That is the half worth keeping most: it exists precisely to stop a fabricated author line.
Please restore it.

Worth knowing for its own sake: the "14/14 rules survived" check could not have caught this,
because the rule's distinctive phrase was not on the grep checklist. A read of the deletions is
the only thing that finds a rule that vanished rather than moved.

3. The worktree path is wrong in two places.

jira-bugfix/SKILL.md:83-85 says worktrees on disk are under .tmp/worktrees/, and
publish.md:106 repeats it in the example ticket comment
(`.tmp/worktrees/nc-delete-warning`).

git worktree list shows thirteen worktrees, all under .claude/worktrees/. There is no
.tmp at the repo root. The ../<repo>.worktrees/ half is right and matches
scripts/Worktree-CreateFromBranch.ps1:5,119; the "what is already there" half is invented,
so an agent told to match it creates worktrees at a path that does not exist.

Please correct both. Worth noting where this bites: worktrees live under .claude/worktrees/
deliberately, because the FwBuildTasks bootstrap fails on paths containing spaces.

This is also the rule this branch introduces failing on its own first outing — pr-pitch
Phase 2 says to verify every concrete noun a DURABLE file names, and its checklist says every
name in the body must resolve in the current tree.

4. The body breaks two rules this PR introduces.

pr-pitch/SKILL.md:78 — "200-400 words, fitting one screen without scrolling. That is
binding, not a target," followed by "Word-count before publishing. Over 400, cut — do not
rationalize."

This body breaks both:

• The budget. Everything above the first --- measures 490 words, against a ceiling the
  same branch calls binding.
• The no-rationalizing rule. The framing paragraph — "why does a set of writing-style
  skills need 1,500 lines?" — is an argument for why the length is justified, written into the
  body by the branch that forbids exactly that move.

Either the body comes under the budget or the rule is softened, but the two need to agree. A
process PR that does not follow its own process is the first thing anyone asked to adopt the
process will point at.

The accordions themselves are fine — this is a genuinely large multi-part branch, which is when
they are warranted. The one I would cut is the licence-provenance accordion, which already
appears verbatim at compact-style.md:9-12.

5. pr-pitch contradicts its own checklist about **Start here:**.

pr-pitch/SKILL.md:103 places **Start here:** inside section 3 ("Where to look"), the third
of six sections. pr-pitch/references/publishing.md:51 checks that the body "opens with
**Start here:**". Those cannot both be satisfied.

Please decide which is intended and update the other file to match. This PR's own body is the
evidence that the ambiguity bites: it puts **Start here:** in the fourth paragraph, so read
literally it fails its own published checklist — the third way this body does not satisfy the
rules the branch adds.

6. "Gates" — please use "check" or "checkpoint".

jira-issue/SKILL.md:32 ("## The two gates"), :39, and the PR body ("Two gates block
publishing"). This is a standing preference for newly written prose across the repo rather than
a note specific to this branch, so it is worth adopting in new skill files generally — "## The
two checks" loses nothing.

7. Two small things in the new skill.

• publish.md:44 hardcodes a real colleague's Jira username (John_Lambert) in the worked
  example. Use <username> — the skill already stores jiraUsername in
  .claude/.jira-issue-prefs.json, so the placeholder has somewhere real to resolve from, and
  a template gets copied.
• jira-issue/SKILL.md:43 and references/format.md hardcode Affects Version FW 9.3 as an
  absolute rule with no pointer to where it is bumped. The repo is on 9.3.12 today; this goes
  stale at 9.4 with nothing to catch it. Either point at the source of truth or say how it is
  maintained.

---

This review was assisted by Claude Fable 5.

[johnml1135]

Six of the seven confirmed and fixed in 8ed642121. Item 3 does not hold, and
item 1 turned out much bigger than either of us thought.

1. The broken imports — right diagnosis, wrong scope

You were right that the workaround should not exist and that the fix is the
import. But it is not two scripts, and it is not one missing name. I imported
every module in atlassian-readonly-skills/scripts:

Cause	Modules
NameError: Optional	confluence_comments, confluence_labels, jira_links, jira_worklog
NameError: AtlassianCredentials	confluence_pages, jira_agile, jira_projects, jira_workflow
ImportError: relative import with no known parent package	all four bitbucket_*

Twelve of sixteen fail to import. Only jira_issues, jira_search,
jira_users and confluence_search work — which is exactly why nobody noticed:
those four are the ones the skills actually call.

AtlassianCredentials is defined in the read-only _common.py:108. The
vendoring generator stripped it from each module's from _common import (...)
list while leaving Optional[AtlassianCredentials] in the signatures, so the
annotation references a name the module never imported. Same generator, two
symptoms.

I fixed the two you named — both now import, and jira_get_transitions was run
against live LT-22723 to prove it end to end — and deleted both copies of the
workaround (publish.md and the SKILL.md trap bullet), which contradicted
AGENTS.md:59.

I did not fix the other ten, and I want that decision visible rather than
buried: this branch's body says the Atlassian transport skills are a separate
PR because they are vendored Python needing a different review. Repairing ten
vendored modules here would break that boundary in a markdown PR. They are one
line each and I am happy to do them — say the word and they land here, or they
go with the transport PR. Either way the measurement above is now on the record
instead of in nobody's head.

3. Backwards — worktrees are not where you say

.claude/worktrees does not exist on disk. git worktree list shows twelve,
all under .tmp/worktrees/. ../FieldWorks.worktrees does not exist either,
though scripts/Worktree-CreateFromBranch.ps1:119 is what would create it.

So there were three candidate paths and the docs named two of them, neither
matching reality. Per the author's call I dropped the fixed path entirely:
jira-bugfix and dependabot-consolidation now point at
Worktree-CreateFromBranch.ps1 as the source of truth and tell the reader to
match git worktree list. dependabot-consolidation was the worse offender —
it hardcoded .claude/worktrees/ in a runnable git worktree add line and
justified it with ".gitignore reserves .claude/worktrees/*", which is true
and irrelevant, since nothing has ever been created there. (.tmp/ is ignored
only incidentally, by *.tmp at .gitignore:72.)

2, 5, 6, 7 — all confirmed

• 2. The compression dropped the review-model instruction while
  summary-template.md:11 still demanded the field. Restored in two lines at
  the top of Setup, including the never-invent-a-co-author-trailer rule, which
  had also gone.
• 5. Sharper than reported: pr-pitch/SKILL.md put **Start here:**
  inside section 3, while publishing.md:51 requires the body to open with
  it — the skill contradicted its own checklist. The line is now hoisted above
  the numbered sections, and this PR's body was rewritten to lead with it.
• 6. "The two gates" undercounted: Phase 5 permission is an equal hard stop
  before filing. Now three gates, and the checklist matches.
• 7. John_Lambert now reads <jiraUsername> from
  .claude/.jira-issue-prefs.json, which the skill already defines and was not
  using. FW 9.3 is derived from Src/MasterVersionInfo.txt
  (FWMAJOR/FWMINOR) in SKILL.md and format.md; the one literal left is
  a copy-paste example, now labelled as such.

4. Body cut to 396 words

Was 490 against a 400 ceiling my own skill sets. Gone: the "why does a set of
writing-style skills need 1,500 lines?" paragraph — it argued with a reader who
had not spoken yet — and the i-have-adhd accordion, whose licence and
provenance duplicate .claude/references/compact-style.md:1-6, where they
belong. The body's "two gates" bullet and its frozen FW 9.3 line were
corrected to match the fixes above.

Verification

gitlint clean. No build.ps1: nothing compiled changed. The two repaired
modules were imported and exercised against live Jira; the other ten were
measured, not guessed.

One thing I nearly shipped: git add -A swept in an untracked
Src/Common/FwAvalonia/GeneratedTokenKeys.g.cs left in this worktree by other
branch work, and the first commit carried 126 lines of generated Avalonia code.
Caught before pushing; 8ed642121 is nine skill files and nothing else.

[github-actions]

NUnit Tests

    1 files  ± 0      1 suites  ±0   11m 0s ⏱️ ±0s
5 864 tests +11  5 783 ✅ +11  81 💤 ±0  0 ❌ ±0 
5 873 runs  +11  5 792 ✅ +11  81 💤 ±0  0 ❌ ±0 

Results for commit 1065652. ± Comparison against base commit 6f72671.

♻️ This comment has been updated with latest results.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 38.35%. Comparing base (6f72671) to head (1065652).
⚠️ Report is 5 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1100      +/-   ##
==========================================
+ Coverage   38.33%   38.35%   +0.01%     
==========================================
  Files        1507     1507              
  Lines      350580   350634      +54     
  Branches    40293    40304      +11     
==========================================
+ Hits       134410   134499      +89     
+ Misses     186941   186902      -39     
- Partials    29229    29233       +4     

see 12 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[johnml1135]

Follow-up on item 1: all twelve are fixed in 83a61e447, and I traced where
the breakage came from. It came from us, not upstream.

Provenance

Upstream langpingxue/atlassian-skills is correct. Its read-only
jira_workflow.py imports both Optional and AtlassianCredentials. I fetched
all 18 upstream read-only modules and diffed them against ours:

• The four modules that worked (jira_issues, jira_search, jira_users,
  confluence_search) are byte-identical to upstream.
• The nine that raised NameError differ from upstream only by names
  deleted from their import lists — nothing else.

Our copies arrived in a single commit, d1a9bc66d (#935). The damage pattern is
an automated unused-import pass that did not understand names used only inside
annotations: Optional[AtlassianCredentials] = None reads as unused to a naive
pruner. Nine modules lost AtlassianCredentials, five also lost Optional.

One I had missed: jira_projects.py also lost NotFoundError, raised at
:178 inside a function body. Import succeeds; the module breaks only when a
project is actually absent. My first commit "fixed" that module while leaving
that in — found by running pyflakes for undefined names instead of trusting a
successful import. Worth remembering: import success is not a proof of health
for this class of bug.

Eight modules are now restored to upstream's imports verbatim. The diff against
upstream is empty for all of them.

The bitbucket four are genuinely upstream's bug

Different cause, and this one is not ours: all four use from ._common import,
a relative import, in both variants and upstream too. That can never resolve
under the invocation every SKILL.md documents — sys.path.insert on the
scripts directory, then import the module directly. They now use the absolute
import plus the path shim the other fourteen modules already had. That is a
deliberate divergence from upstream and worth sending back to them.

Verification

33/33 modules import across both variants; pyflakes reports no undefined name
in either. Five modules that previously died on import — jira_workflow,
jira_links, jira_projects, jira_worklog, jira_agile — were called
against live Jira and returned data. Only Jira is configured in this
environment, so the Confluence and Bitbucket modules are verified statically,
not end to end.

Two things I did not change, for the author to decide

1. _common.py disables TLS verification. Ours sets ssl_verify = False in
   four places where upstream sets True. That is a deliberate local change
   rather than vendoring damage — every live call above emits
   InsecureRequestWarning — so reverting it blind would likely break access to
   jira.sil.org. It should be a recorded decision rather than an undocumented
   diff.
2. The licence reference points at a file that does not exist. Both
   SKILL.md files carry license: Complete terms in LICENSE. There is no
   LICENSE in either vendored directory, and upstream has none either — its
   README.md declares "MIT License" in prose, with no copyright holder or
   year, and GitHub reports no licence for the repo. So this is vendored
   third-party code whose only licence grant is one line of README prose, and
   our frontmatter cites a file nobody has. I did not invent a copyright line;
   recording actual provenance is a call for the author.

[johnml1135]

Retracting my previous comment. Two of its claims were wrong, and the
commit it described is reverted in 106565272.

It is not our bug, and it is already being fixed

I said the missing imports were pruned locally when these were vendored, and
that upstream was correct. Wrong on both counts. The real history:

When	What
2025-12-20 cdd1823f6	Upstream introduces the read-only variant, with the imports already missing
2026-02-10 0fafb48e7	Upstream fixes it — "Fix missing imports in readonly variant scripts"
2026-06-11 d1a9bc66d (#935)	We vendor the pre-fix state, four months after upstream fixed it

Our copy is byte-identical to upstream at cdd1823f6. I checked the current
upstream files, saw them correct, and concluded the divergence must be ours —
without checking whether upstream had changed. The remedy is a re-sync from
upstream, not the hand-patching I did.

Worse: PR #1101 is open and already does this. It reduces both variants to
Jira, deleting the Bitbucket and Confluence modules outright, and adds a
PROVENANCE.md to each. Eleven of the fifteen files I "repaired" are files
#1101 deletes — I was patching code that another open PR removes, and it would
have conflicted on merge. This PR's own body pointed at that separate PR; I
should have opened it before acting.

What this branch now touches

Two vendored files, jira_workflow.py and jira_projects.py — the minimum for
honestly deleting a workaround that named them. Both were imported and called
against live Jira. Those two lines overlap #1101, so whichever merges second
takes a two-line conflict.

One line survives the revert: the read-only jira_projects.py had also lost
NotFoundError, raised at :179 inside a function body. A successful import
does not prove that module healthy, which is why I ran pyflakes for undefined
names rather than trusting the import. Since this branch claims to fix that
module, leaving a known latent NameError in it was not defensible.

Still standing from the earlier comments

Items 2, 3, 5, 6 and 7, and the body cut, are unaffected — none of them touch
vendored code. Item 3 is still backwards: worktrees are under .tmp/worktrees/,
.claude/worktrees does not exist.

Two observations for #1101 rather than here, since that PR owns these files:

1. _common.py sets ssl_verify = False in four places where upstream sets
   True. Every live call emits InsecureRequestWarning. That looks like a
   deliberate local change for jira.sil.org rather than vendoring damage, so
   it wants a recorded reason, not a silent diff.
2. Both SKILL.md files carry license: Complete terms in LICENSE, and no
   LICENSE exists in either directory. Upstream has none either — README.md
   declares "MIT License" in prose, with no holder or year, and GitHub reports
   no licence for the repo. Reduce the Atlassian skills to Jira, and fix eight broken modules #1101's PROVENANCE.md may already cover this; if
   not, it is the right place.