LT-22723: Add jira-issue skill and compact style for issues and PRs - #1098
Closed
johnml1135 wants to merge 6 commits into
Closed
LT-22723: Add jira-issue skill and compact style for issues and PRs#1098johnml1135 wants to merge 6 commits into
johnml1135 wants to merge 6 commits into
Conversation
Agent-authored LT tickets put good analysis in the wrong shape. The reference failure opens with a heading, runs past a thousand words, and states that it contains four separate user-visible problems, so a triager scanning a queue cannot act on it. Jira Data Center has no expand macro, so nothing in a description can be folded away. The skill keeps the description short and moves the depth into the first comment. The skill interviews for who, when, where and how under a cap of six questions, hunts duplicates before drafting rather than before posting, and gets a three-line lede approved before anything else is written. Unknowns are recorded rather than guessed, and nothing enters a description that the reporter did not say or that we did not verify. compact-style.md is a shared reference adapting the MIT-licensed i-have-adhd skill from chat turns to written artifacts. pr-pitch now points at it and gains a Start here line, numbered verification steps, a closing Next line, an optional status line for long-lived PRs, and the pre-send check. jira-bugfix gains the LT-XXXXX-short-slug branch convention, a relaxed worktree rule that asks rather than refuses, and a note that it is entered at Step 3 when jira-issue hands off. Evidence and screenshot handling is deliberately absent; it follows in a stacked branch. Co-Authored-By: Claude Opus 5 <[email protected]>
Not every LT ticket is about FLEx the product. One about developer tooling, an agent skill, the build or documentation has no FLEx version, no project file, no menu path and nothing to reproduce inside the application. Phase 0b now decides what kind of thing the ticket is about before the interview starts, and maps that to the environment questions worth asking. Asking which FLEx build was running, for a ticket about a Markdown reference file, spends one of six questions and signals that the ticket was generated rather than written. The output rule is the same: never emit a section that does not apply. A template dutifully filled with N/A costs the reader the same scan and returns nothing, so the heading goes instead. Co-Authored-By: Claude Opus 5 <[email protected]>
The design document was a working artifact, not something a future maintainer needs in order to change this code correctly. Under the pr-pitch triage it is RESEARCH: a one-time investigation whose conclusions are now carried by the skill itself. Its content survives in the pull request body, where the decisions, the rejected alternatives and the reasoning stay recoverable without shipping scaffolding into the repository. Refs LT-22723 Co-Authored-By: Claude Opus 5 <[email protected]>
Every new LT ticket carries Affects Version FW 9.3, with no exception. It is a filing convention that keeps the queue filterable rather than a claim about which build the reporter was running, so the Phase 0b relevance rule does not exempt a tooling, build or documentation ticket from it. A specific point release the reporter names is added alongside FW 9.3, never in place of it. Neither jira_create_issue nor jira_update_issue exposes the versions field, so it goes through custom_fields. The same applies to assignee, which those helpers send as a Cloud-style accountId that SIL's Data Center rejects; both fallbacks are now written down where the publish step needs them. Refs LT-22723 Co-Authored-By: Claude Opus 5 <[email protected]>
The example carried placeholder keys for the four symptom tickets that splitting LT-22715 would create. Those tickets now exist, filed on 2026-08-21 as LT-22724 through LT-22727 and linked back with Issue split, so the example names them. A worked example that cites real tickets can be checked by a reader. One that cites LT-AAAAA cannot, and quietly invites the reader to treat the whole example as hypothetical. Refs LT-22715, LT-22723 Co-Authored-By: Claude Opus 5 <[email protected]>
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #1098 +/- ##
=======================================
Coverage 38.33% 38.34%
=======================================
Files 1507 1507
Lines 350580 350580
Branches 40293 40293
=======================================
+ Hits 134410 134426 +16
+ Misses 186941 186925 -16
Partials 29229 29229 🚀 New features to boost your workflow:
|
SKILL.md goes from 224 lines to 95. It is the only file loaded every time the skill triggers, so every line it holds is context spent whether or not the reader needs it. Mechanics move to references, which load when the phase that needs them is reached. Moved out: the four duplicate-search passes to a new duplicates.md, the publish calls to publish.md, the relevance table to format.md. What stays is the phase table, the two gates, the budgets and the traps. Recorded from the retroactive rewrite of 28 tickets: - Link types must be read, never guessed. There is no Relates in this Jira, and falling back to the first name in the list produced four bogus Cloners links between a cause ticket and its children. - resolution cannot be set by an update, only by a transition. - The read-only skill's jira_workflow.py and jira_projects.py raise NameError on import; use the atlassian-skills copies. - A private Gmail or Drive URL in a description is broken evidence. - Rewriting a ticket posts the original as a comment first. Task-type tickets gain their own lede labels. Two of the rewritten tickets were Tasks and had to improvise them. Refs LT-22723 Co-Authored-By: Claude Opus 5 <[email protected]>
Contributor
Author
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Filing an LT ticket with an agent now goes through a skill instead of improvisation.
/jira-issueinterviews 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.The unknown you arrive with: why does a writing-style skill run to 850 lines? Because Jira Data Center has no
{expand}macro. Nothing in a description can be folded away, so length in the description is length on the screen, for every reader, permanently. Every budget in 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. The nine phases are the design; the fourreferences/files are detail it delegates to.Where to look:
compact-style.mdis shared, not copied.pr-pitchreads the same file, so the two cannot drift apart.jira-bugfix's worktree prohibition is relaxed from "do NOT create worktrees automatically" to "not without asking", and it gains theLT-XXXXX-short-slugbranch convention.Deliberately not here: screenshots, attachments and the evidence framework, stacked behind this in the follow-up PR.
Verification:
gitlintclean on all five commits; skill frontmatter parses; no trailing whitespace on any added line. Nobuild.ps1ortest.ps1run — nothing compiled changed.Build\Agent\check-and-fix-whitespace.ps1errors on a clean branch because it reads a logTee-Objectnever creates, so whitespace was verified by hand instead.Next: review, or tell me to split the
pr-pitchandjira-bugfixedits out of this branch.Reading this a year from now — start here
The design for this skill was written as a document in
Docs/workflows/and then deliberately deleted before merge. It was working scaffolding, not something anyone needs in order to change this code correctly. What follows is that record, kept here because a PR body outlives a branch and costs nothing to scroll past.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. Three labelled lines, rendered and shown, up to three revisions. After the third the skill asks which line is wrong rather than guessing a fourth time. Every other budget in the skill 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.Preferences are a gitignored file, not agent memory.
.claude/.jira-issue-prefs.jsonis portable to any agent this repo supports and is per-clone, so one developer'sworktreepreference never becomes another's default.Branches are
LT-XXXXX-short-slug. The number keepsjira-bugfix's existing "contains the LT number" check working; the slug is what makes a list of sixteen worktrees readable. A real session was lost hunting for "the branch for LT-22715" among branches named descriptively.Paths not taken
A second skill pair mirroring
pr-preflight/pr-pitch. Two entrypoints to keep straight 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 of this skill would be different.A standalone
compact-writingskill. A fourth skill in the chain, loadable when nobody asked for it. A reference file that two skills read costs less and cannot be invoked by accident.Duplicating the style rules in each skill. Rejected because they would drift, and the drift would be invisible until someone noticed tickets and PR bodies had different rules about the same thing.
The i-have-adhd adaptation
compact-style.mdadapts the MIT-licensed i-have-adhd skill. That skill shapes chat turns; these rules shape written artifacts, which changes several of them:Two rules were added that have no chat equivalent: say what is not known, and never assert what was not verified.
Evidence
The reference failure is real, not hypothetical. LT-22715's first rendered line is
h3. The underlying problem; its description runs past a thousand words; and it states in its own text that "that single missing distinction produces four separate user-visible problems".references/examples.mdcarries the before-and-after in full, with the rewrite at 228 words.The skill was used to file its own ticket. LT-22723 went through Phase 0 (type), Phase 0b (relevance — tooling, so no environment or repro sections), Phase 2 (three JQL passes, no duplicate), Phase 3 (lede approved by the developer before drafting), and Phase 6. Description came in at 232 words against a 250 budget; summary at 60 characters against 80.
Jira API surfaces were read, not guessed.
jira_create_issuesets{'accountId': ...}forassignee, which is Cloud-only — SIL Jira is Data Center and needs{'name': ...}, so the skill documents thecustom_fieldsfallback. Confirmed by filing LT-22723 that way.Unrelated defect found in passing, not fixed here:
.claude/skills/atlassian-readonly-skills/scripts/jira_projects.pyraisesNameError: name 'Optional' is not definedon import — a missing typing import. Out of scope for this branch.This change is