Skip to content

Reduce the Atlassian skills to Jira, and fix eight broken modules - #1101

Draft
johnml1135 wants to merge 4 commits into
mainfrom
atlassian-skills-fix
Draft

Reduce the Atlassian skills to Jira, and fix eight broken modules#1101
johnml1135 wants to merge 4 commits into
mainfrom
atlassian-skills-fix

Conversation

@johnml1135

@johnml1135 johnml1135 commented Aug 21, 2026

Copy link
Copy Markdown
Contributor

The two Atlassian skills supported Jira, Confluence and Bitbucket. FieldWorks uses Jira. Confluence and Bitbucket are gone — 4,362 deletions against 293 insertions — and eight modules that never worked are fixed.

Start here: .claude/skills/atlassian-skills/SKILL.md — the Configuration and Core Workflow sections show the shape of the whole change.

Where to look:

  • Eight of twelve read-only modules were unusable. They raised NameError on import, so any read through them failed and callers had to reach into the write skill to do a read. Cause is an upstream generator bug: the read-only variant is produced by stripping write functions, and the stripper also pruned Optional and AtlassianCredentials from imports while surviving signatures still referenced them. Reported as langpingxue/atlassian-skills#14.
  • Confluence and Bitbucket removed to the roots — not just the eight script modules per skill, but their docs, config blocks, credential fields, the CQL reference, and the plumbing in _common.py: dataclass fields, is_*_available, get_*_client, and the service branches in from_credentials. Zero references remain outside the provenance notes.
  • What remained was rewritten, not left with holes. Configuration is two short modes with SIL Data Center first. Core Workflow, the agent-mode example and the credentials reference are Jira-shaped rather than two-thirds excised.
  • Both frontmatter descriptions advertised Confluence and Bitbucket and are rewritten. An overstated description is how the wrong skill gets loaded.
  • The read-only variant also lost its duplicated utility catalogue: 237 lines restating function signatures REFERENCE.md already documents. Now a generated module-to-function index.

Deliberately not here: _common.py keeps its check_available_skills machinery even though only one service can now be unavailable. It is load-bearing for the credentials path and cheap to leave.

Verification: all 9 modules in each skill import (8 were broken); a live jira_get_issue('LT-22723') and jira_get_transitions both succeed through the read-only skill — previously impossible; zero Confluence/Bitbucket references outside PROVENANCE.md. gitlint clean. No build.ps1/test.ps1: Python utilities outside the build, no compiled code.

Next: review and merge — independent of #1098/#1099/#1100/#1102, touching none of their files.


Size before and after
Before After
atlassian-skills (md + py) ~5,900 3,325
atlassian-readonly-skills (md + py) ~4,400 2,219
Script modules per skill 17 9
Broken modules (read-only) 8 0

SKILL.md specifically: write variant 741 → 382 lines, read-only 560 → 148.

What the licence investigation found

Both skills carry license: Complete terms in LICENSE in frontmatter, which is what stopped an earlier pass from touching them at all. Checking properly:

Question Answer
Where from? https://github.com/langpingxue/atlassian-skills, vendored in d1a9bc6
Declared licence? MIT, in the upstream README
LICENSE file upstream? No. GitHub's license endpoint 404s
Copyright line anywhere? No
LICENSE file here? No — the frontmatter reference dangles in both places

MIT permits modification, so the earlier caution was unnecessary. The attribution it does ask for was missing and now exists as PROVENANCE.md in each skill. Since upstream names no copyright holder, a verbatim MIT text could not honestly be authored on their behalf; the provenance files record the declaration and its gaps instead.

This is now a hard fork. A re-sync is no longer a merge — upstream becomes a source to cherry-pick Jira fixes from. PROVENANCE.md says so.

Data Center gotchas captured while investigating

Upstream's docstrings describe Jira Cloud; SIL's instance is Data Center. Three that silently disagree, now in atlassian-skills/PROVENANCE.md:

  • assignee wants a username, not an accountId. jira_create_issue and jira_update_issue both send {"accountId": ...}, which Data Center rejects. Pass custom_fields={"assignee": {"name": "<username>"}}.
  • Affects Version is not exposed at all. Pass custom_fields={"versions": [{"name": "FW 9.3"}]}.
  • resolution cannot be set by an update — not on the edit screen; only a transition sets it.

Each was found by hitting it. They are duplicated into jira-issue/references/publish.md on #1098, where someone working an LT ticket looks first.


This change is Reviewable

confluence_comments, confluence_labels, confluence_pages, jira_agile,
jira_links, jira_projects, jira_workflow and jira_worklog all raised
NameError on import: Optional or AtlassianCredentials was referenced by
a surviving function signature but missing from the import lines. Eight
of the twelve read-only modules were therefore unreachable, and callers
had to fall back to the write skill for reads.

The read-only variant looks generated from the write variant by
stripping write functions, with the stripper also pruning those two
names. The fix restores them and nothing else. It is an upstream bug and
a re-sync will reintroduce it until reported.

Verified: all twelve modules in both skills now import, and
jira_get_transitions returns live data through the read-only skill.

Both skills gain a PROVENANCE.md recording the upstream repository, the
MIT declaration, the local modifications, and the Data Center behaviours
that upstream's Cloud-oriented docstrings get wrong. Upstream declares
MIT in its README but ships no LICENSE file and no copyright line, so
the frontmatter reference to LICENSE dangles there as well as here; it
is left unchanged to keep this copy diffable.

Co-Authored-By: Claude Opus 5 <[email protected]>
@johnml1135
johnml1135 marked this pull request as draft August 21, 2026 15:41
atlassian-readonly-skills/SKILL.md restated all 48 function signatures
that REFERENCE.md already documents in the same folder, 237 lines of it,
copied from the write variant. It now carries a module-to-function table
naming every function the variant has, and points at REFERENCE.md for
signatures. 560 lines to 265.

The delegation is narrower than it first looked. Only Response Data
Structures, Error Handling and Dependencies are byte-identical between
the two variants and safe to document once; Configuration, Core Workflow
and Philosophy differ, because the write variant carries write examples.
Those first two are kept here verbatim rather than delegated, and the
file says which is which.

Verified: every one of the 48 functions named here is documented in
REFERENCE.md, and the list is generated from the scripts themselves
rather than from the prose it replaces.

Refs LT-22723
@github-actions

This comment has been minimized.

@johnml1135
johnml1135 force-pushed the atlassian-skills-fix branch from 672dc33 to dcd60dd Compare August 21, 2026 15:54
PROVENANCE.md said this skill had deliberately not been compressed. It
has been, in the commit before this one, so the note now records what
changed and warns that a re-sync must re-apply it alongside the import
fix and the SIL section.

The read-only note also cites the upstream issue for the import bug now that one
exists: langpingxue/atlassian-skills#14.

Refs LT-22723

Co-Authored-By: Claude Opus 5 <[email protected]>
@github-actions

github-actions Bot commented Aug 21, 2026

Copy link
Copy Markdown

NUnit Tests

    1 files  ±0      1 suites  ±0   10m 35s ⏱️ -25s
5 853 tests ±0  5 772 ✅ ±0  81 💤 ±0  0 ❌ ±0 
5 862 runs  ±0  5 781 ✅ ±0  81 💤 ±0  0 ❌ ±0 

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

♻️ This comment has been updated with latest results.

FieldWorks uses Jira and nothing else. Nothing in the repository
referenced a Confluence or Bitbucket helper, yet both skills carried
full support for them: eight script modules each, their documentation,
their configuration blocks, and their plumbing in _common.py.

Removed across both variants: the confluence_* and bitbucket_* modules,
their SKILL.md and REFERENCE.md sections, the CQL query reference, the
partial-service configuration guidance, and in _common.py the dataclass
fields, is_*_available checks, get_*_client factories and the service
branches in AtlassianConfig.from_credentials.

Streamlined what remained rather than leaving holes. Configuration is
now two short modes, SIL Data Center first, with Jira Cloud kept only
for completeness. Core Workflow, the agent-mode example and the
credentials reference were rewritten around Jira instead of having
their other two thirds cut out.

Both frontmatter descriptions claimed Confluence and Bitbucket support,
so they are rewritten too. A description that overstates what a skill
does is how the wrong skill gets loaded.

Verified: zero Confluence or Bitbucket references remain outside the
provenance notes. All 9 modules in each skill import, and a live read
against SIL Jira through the read-only skill still works.

Refs LT-22723
@johnml1135 johnml1135 changed the title Fix eight unusable modules in atlassian-readonly-skills Reduce the Atlassian skills to Jira, and fix eight broken modules Aug 21, 2026
@codecov-commenter

codecov-commenter commented Aug 21, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 38.34%. Comparing base (6f72671) to head (f5c09c3).

Additional details and impacted files
@@           Coverage Diff           @@
##             main    #1101   +/-   ##
=======================================
  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           

see 3 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants