From c2b55e7cdef042d1f945b6208718eea148da6207 Mon Sep 17 00:00:00 2001 From: Graham Walker Date: Mon, 13 Jul 2026 11:04:12 -0500 Subject: [PATCH 1/7] creating qa skill based on retro feedback --- .../skills/evaluating-qa-readiness/SKILL.md | 95 +++++++++++++++++++ .../examples/sample_evaluation.md | 51 ++++++++++ .../references/criteria.md | 64 +++++++++++++ 3 files changed, 210 insertions(+) create mode 100644 plugins/bitwarden-atlassian-tools/skills/evaluating-qa-readiness/SKILL.md create mode 100644 plugins/bitwarden-atlassian-tools/skills/evaluating-qa-readiness/examples/sample_evaluation.md create mode 100644 plugins/bitwarden-atlassian-tools/skills/evaluating-qa-readiness/references/criteria.md diff --git a/plugins/bitwarden-atlassian-tools/skills/evaluating-qa-readiness/SKILL.md b/plugins/bitwarden-atlassian-tools/skills/evaluating-qa-readiness/SKILL.md new file mode 100644 index 00000000..fa9e2107 --- /dev/null +++ b/plugins/bitwarden-atlassian-tools/skills/evaluating-qa-readiness/SKILL.md @@ -0,0 +1,95 @@ +--- +name: evaluating-qa-readiness +description: Use whenever someone wants to check whether a Jira ticket is ready to hand to QA — "Is PROJ-123 ready for QA?", "QA-check PROJ-123", "Does PROJ-123 have everything QA needs?", "Review PROJ-123 before I move it to Ready for QA", "Is this story ready to test?", or any request to validate that a story/bug has the information a tester needs before testing starts. Reads the ticket via the read-only Atlassian MCP and reports, per objective criterion, what QA needs that is present or missing — feature flag state, testing instructions, implementation notes, acceptance criteria, affected clients, and a linked PR/build — plus a ready-to-paste comment the developer can act on. Use this proactively when a developer says they are moving a ticket to Ready for QA, even if they don't say "QA readiness." +--- + +# Evaluating QA Readiness + +When a ticket moves to **Ready for QA**, the tester should not have to hunt down the developer to learn how to test it. This skill checks a Jira ticket for the concrete, objectively-verifiable pieces of information QA needs _before_ testing starts, so gaps get fixed by the implementer instead of turning into back-and-forth later. + +**This is a completeness check, not a quality judgment.** You are checking whether the _information_ a tester needs is present and usable — not whether the fix is correct, whether the acceptance criteria are good, or whether the design is right. Those are QA's and the team's calls. Staying inside that boundary is what keeps this check objective and trustworthy: a developer should be able to look at any "missing" flag and agree it's genuinely absent. + +## Workflow + +### Step 1: Read the ticket + +Use the `get_issue` MCP tool with the issue key. It defaults to expanding `renderedFields` and `names`, giving you HTML-rendered field values and human-readable custom-field display names — you need both, because feature-flag and implementation info often live in custom fields, not the description. + +Then use `get_issue_comments` — developers frequently drop testing steps, flag names, or "how to test" notes in a comment rather than editing the description. Treat comments as a first-class source, not an afterthought. + +If the description or comments reference a PR, build, or Confluence page, note it; use `get_issue_remote_links` to catch linked PRs and pages that aren't inline. You are looking for _evidence that the information exists somewhere on the ticket_, wherever the developer put it. + +### Step 2: Evaluate each criterion + +Judge each criterion against everything you gathered — description, all custom fields, comments, and links. For each, decide one of: + +- **Present** — the information is there and a tester could act on it. +- **Missing** — no trace of it anywhere on the ticket. +- **Unclear** — something is there but it's ambiguous or incomplete (e.g. a flag is mentioned but not its name, or "test the usual flows" with no steps). Treat unclear as a gap worth flagging, but describe _what_ is ambiguous rather than just calling it absent — that's more actionable and more fair to the developer. + +Read the criteria definitions and what counts as satisfied in `references/criteria.md`. In short: + +**Blocking** (a tester is genuinely stuck without these): + +1. **Testing instructions** — how to validate the change: setup/preconditions, steps, and expected result. For a bug, this includes what "fixed" looks like versus the original broken behavior. +2. **Implementation notes** — what was changed and where, at enough detail for a tester to know what surface area to exercise. +3. **Feature flag** — whether the change sits behind a flag. If it does, the flag's name/key **and** the state QA needs it in (on/off) to test. If it doesn't, the ticket should say so — "not behind a flag" is a valid, passing answer. Silence is the gap, because the tester otherwise can't tell whether they're testing the right thing. + +**Non-blocking** (QA can usually start, but these save round-trips): + +4. **Acceptance criteria** — a testable statement of what the change should do. +5. **Affected clients/platforms** — which clients (web, browser extension, desktop, mobile, CLI) / OSes / browsers are in scope, so QA tests the right surfaces. +6. **Linked PR or build** — a PR link or a build/version where the change can actually be exercised. + +Distinguishing blocking from non-blocking matters: a ticket missing only a PR link is _nearly_ ready and shouldn't be treated the same as one with no testing instructions at all. The verdict should reflect that difference so developers fix the things that actually stop testing first. + +### Step 3: Report + +Use this structure: + +``` +## QA Readiness: — +**Verdict:** Ready for QA | Not ready — N blocking gap(s) | Nearly ready — N non-blocking gap(s) + +| Criterion | Status | Notes | +|---|---|---| +| Testing instructions | ✅ Present / ❌ Missing / ⚠️ Unclear | | +| Implementation notes | ... | ... | +| Feature flag | ... | ... | +| Acceptance criteria | ... | ... | +| Affected clients/platforms | ... | ... | +| Linked PR/build | ... | ... | +``` + +Rules for the verdict: + +- **Not ready** if any _blocking_ criterion is Missing or Unclear. +- **Nearly ready** if all blocking criteria pass but one or more _non-blocking_ ones don't. +- **Ready for QA** only if everything passes. + +In the Notes column, cite the evidence when something passes (where you found it — "steps in description", "flag name in comment by @dev") and state specifically what's absent when it doesn't. Vague notes ("needs more detail") aren't actionable; "no expected result given for the reset-password step" is. + +### Step 4: Draft the developer ask + +If there are any gaps, produce a short comment the QA (or the tool user) can paste onto the ticket to ping the developer. Address only the gaps — don't restate what's already there. Keep it collegial and specific; the goal is to make it trivial for the developer to fill the holes: + +``` +Before this is ready for QA, could you add: +- **Feature flag:** is this behind a flag? If so, which flag and what state should it be in to test? +- **Testing instructions:** steps to validate, including expected result. +``` + +If nothing is missing, say so plainly and skip the draft comment — no need to manufacture busywork. + +## Boundaries and honesty + +- The Atlassian MCP here is **read-only**. You cannot post the comment or change the ticket — you produce the draft for a human to post. Say so if the user expects it to be posted. +- If `get_issue` fails or the key doesn't exist, report that plainly rather than guessing at contents. +- Never infer that a criterion is satisfied from the issue _type_ or _status_ alone. A ticket marked "Ready for QA" is exactly the case where you should still check — that status is the claim you're verifying, not evidence. +- If a custom field name suggests it holds relevant info (anything mentioning "flag", "test", "QA", "implementation", "platform") but it's empty, that's a Missing signal worth noting by name. + +## Examples + +### examples/sample_evaluation.md + +A worked example: reading a Story, finding testing steps in a comment but no feature-flag information, and producing the report plus a targeted developer ask. diff --git a/plugins/bitwarden-atlassian-tools/skills/evaluating-qa-readiness/examples/sample_evaluation.md b/plugins/bitwarden-atlassian-tools/skills/evaluating-qa-readiness/examples/sample_evaluation.md new file mode 100644 index 00000000..4ba45fa3 --- /dev/null +++ b/plugins/bitwarden-atlassian-tools/skills/evaluating-qa-readiness/examples/sample_evaluation.md @@ -0,0 +1,51 @@ +# Sample Evaluation + +A worked walkthrough of evaluating a Story that's been moved to Ready for QA. + +## Input + +User: "Is PM-4821 ready for QA?" + +## Gathering + +1. `get_issue("PM-4821")` returns a Story: _"Add per-item reprompt toggle to vault item edit view."_ + - **Description**: Explains the feature and lists acceptance criteria ("User can toggle master-password reprompt on an individual item; setting persists after sync"). + - **Custom fields**: A "Feature Flag" field exists but is empty. An "Affected Clients" field lists _Web, Browser Extension_. + - No implementation summary in the description. +2. `get_issue_comments("PM-4821")` returns one comment from the developer: _"To test: create a login item, open edit, flip the new 'Require master password re-prompt' switch, save, refresh — switch state should persist. Also confirm reprompt is enforced on view."_ +3. `get_issue_remote_links("PM-4821")` returns a linked GitHub PR. + +## Reasoning + +- **Testing instructions** → Present. Clear steps and an expected result in the developer's comment. +- **Implementation notes** → Missing. There's a PR link but no summary of what changed; QA would have to read the diff. +- **Feature flag** → Unclear. A "Feature Flag" field exists but is empty — so it's ambiguous whether the feature is flagged and, if so, what state to test in. Flag by name. +- **Acceptance criteria** → Present. Stated in the description and testable. +- **Affected clients/platforms** → Present. Web and Browser Extension named in the custom field. +- **Linked PR/build** → Present. PR linked via remote links. + +Blocking criteria: testing instructions (pass), implementation notes (fail), feature flag (unclear → fail). Two blocking gaps → **Not ready**. + +## Output + +## QA Readiness: PM-4821 — Add per-item reprompt toggle to vault item edit view + +**Verdict:** Not ready — 2 blocking gaps + +| Criterion | Status | Notes | +| -------------------------- | ---------- | ------------------------------------------------------------------------------------------------------- | +| Testing instructions | ✅ Present | Steps + expected result in developer comment (persist after refresh; reprompt enforced on view). | +| Implementation notes | ❌ Missing | PR is linked but there's no summary of what changed/where — QA shouldn't have to read the diff. | +| Feature flag | ⚠️ Unclear | "Feature Flag" field exists but is empty. Can't tell if the toggle is flagged or what state to test in. | +| Acceptance criteria | ✅ Present | Stated and testable in description. | +| Affected clients/platforms | ✅ Present | Web, Browser Extension (custom field). | +| Linked PR/build | ✅ Present | GitHub PR linked via remote links. | + +**Draft comment for the developer:** + +> Nearly there — before this moves to Ready for QA, could you add: +> +> - **Feature flag:** the "Feature Flag" field is empty. Is the reprompt toggle behind a flag? If so, which flag and what state should QA set it to? If it's not flagged, a quick "not behind a flag" works. +> - **Implementation notes:** a one-line summary of what changed and which areas it touches, so QA knows the surface to exercise (the PR link alone means reading the diff). +> +> Testing steps, AC, affected clients, and the PR link all look good — thanks! diff --git a/plugins/bitwarden-atlassian-tools/skills/evaluating-qa-readiness/references/criteria.md b/plugins/bitwarden-atlassian-tools/skills/evaluating-qa-readiness/references/criteria.md new file mode 100644 index 00000000..6fd7c2eb --- /dev/null +++ b/plugins/bitwarden-atlassian-tools/skills/evaluating-qa-readiness/references/criteria.md @@ -0,0 +1,64 @@ +# QA Readiness Criteria + +Detailed definitions of what each criterion checks and what counts as satisfied. The guiding question for every criterion is the same: **can a tester who has never spoken to the developer act on this?** If yes, it's present. If they'd have to ask a follow-up question to proceed, it's a gap. + +These criteria check for the _presence and usability of information_, never the correctness of the work. + +## Blocking criteria + +A tester is genuinely stuck — or at high risk of testing the wrong thing — without these. Any one of them missing or unclear means the ticket is **not ready**. + +### 1. Testing instructions + +**Satisfied when** the ticket describes how to validate the change with enough specificity that a tester can follow it: + +- Any setup or preconditions (account state, test data, org configuration) needed before the steps. +- The steps themselves, in order. +- The expected result — what the tester should observe if the change works. + +For a **bug**, this means both the original broken behavior and what "fixed" looks like, so the tester can confirm the specific fix rather than a general smoke test. + +**Not satisfied by**: "test the feature", "verify it works", or a link to steps that isn't accessible. Generic acceptance criteria are not the same as testing steps — AC says _what_ should be true, testing instructions say _how to check_. + +### 2. Implementation notes + +**Satisfied when** the ticket says what was changed and roughly where, at a level that tells QA what surface area to exercise and where regressions might hide. Examples: "changed the vault-item export to stream instead of buffering; touches the web and desktop export dialogs", or "fixed null-check in the autofill matcher for URLs without a scheme." + +**Not satisfied by**: a PR link _alone_ with no summary — QA shouldn't have to read a diff to learn what to test. A one-line summary plus the PR link is fine. + +### 3. Feature flag + +**Satisfied when** the ticket makes the flag situation unambiguous: + +- If the change is behind a flag: the flag's name/key **and** the state QA needs (enabled/disabled, and for which environment or account if relevant). +- If the change is not behind a flag: an explicit statement to that effect. + +**Why silence is a gap**: without this, the tester can't tell whether the feature will even be visible in their environment, and a "passing" test against a flagged-off build is worse than no test. An explicit "not behind a flag" is a passing answer — the requirement is a clear answer, not a flag. + +## Non-blocking criteria + +QA can usually begin without these, but each one that's missing tends to cause a round-trip mid-test. Flag them so they get fixed, but don't block the handoff on them alone. + +### 4. Acceptance criteria + +**Satisfied when** there's a testable statement of what the change should accomplish — the conditions the tester (and the team) agree define "done." + +**Note the overlap with testing instructions**: AC is the _what_, instructions are the _how_. A ticket can have strong AC and still be missing steps, or vice versa. Evaluate them independently. + +### 5. Affected clients / platforms + +**Satisfied when** the ticket names which clients (web vault, browser extension, desktop, mobile, CLI) and, where it matters, which OSes or browsers are in scope. This lets QA test the right surfaces instead of guessing or over-testing. + +**Not satisfied by**: an implicit assumption. "It's a server change" counts if stated; leaving platform scope unsaid does not. + +### 6. Linked PR or build + +**Satisfied when** there's a link to the PR or a specific build/version where the change can be exercised. This is what lets QA actually get their hands on the change. + +**Partial credit**: a PR link is good; a link to an installable build or a named version QA can pull is better. Either satisfies the criterion. + +## Judgment notes + +- **Where developers put things varies.** Some teams keep testing steps in a custom field, others in the description, others in a comment. Search all of them before calling something missing — a false "missing" erodes trust in the check faster than a missed gap. +- **Unclear is its own category.** When something is present but ambiguous (a flag named with no state, steps with no expected result), say what specifically is ambiguous. That's more useful than a binary pass/fail and more fair to the developer. +- **Don't reward the ticket's status.** "Ready for QA" is the assertion under test, not evidence. Evaluate the content as if the status label weren't there. From a22475654696cb5fd24225ba7553e8eda24808fc Mon Sep 17 00:00:00 2001 From: Graham Walker Date: Wed, 5 Aug 2026 14:46:38 -0500 Subject: [PATCH 2/7] updating skill --- .claude-plugin/marketplace.json | 2 +- .cspell.json | 1 + README.md | 2 +- .../bitwarden-atlassian-tools/.claude-plugin/plugin.json | 2 +- plugins/bitwarden-atlassian-tools/CHANGELOG.md | 6 ++++++ .../skills/evaluating-qa-readiness/SKILL.md | 4 ++-- 6 files changed, 12 insertions(+), 5 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 8f63488e..9fca85ba 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -48,7 +48,7 @@ { "name": "bitwarden-atlassian-tools", "source": "./plugins/bitwarden-atlassian-tools", - "version": "2.2.8", + "version": "2.3.0", "description": "Read-only Atlassian access via MCP server with deep Jira issue research skill, JQL search, Confluence pages, CQL search, and attachments" }, { diff --git a/.cspell.json b/.cspell.json index c42db5a0..1f51e057 100644 --- a/.cspell.json +++ b/.cspell.json @@ -95,6 +95,7 @@ "pyproject", "pytest", "remotelink", + "reprompt", "Rescope", "resolutiondate", "rustdoc", diff --git a/README.md b/README.md index 27ab17a0..77484cd8 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ A curated collection of plugins for AI-assisted development at Bitwarden. Enable | ------------------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | [bitwarden-tech-lead](plugins/bitwarden-tech-lead/) | 2.3.2 | Tech lead for technical planning, architecture coherence, and surfacing patterns to Technical Strategy Ideas | | [bitwarden-shepherd](plugins/bitwarden-shepherd/) | 1.0.0 | Champion of a technical strategy — shepherds a TSI through evaluation into the funnel, then through to adoption | -| [bitwarden-atlassian-tools](plugins/bitwarden-atlassian-tools/) | 2.2.8 | Read-only Atlassian access via MCP server with deep Jira issue research skill | +| [bitwarden-atlassian-tools](plugins/bitwarden-atlassian-tools/) | 2.3.0 | Read-only Atlassian access via MCP server with deep Jira issue research skill | | [bitwarden-code-review](plugins/bitwarden-code-review/) | 1.13.1 | Autonomous code review agent following Bitwarden engineering standards with GitHub integration | | [bitwarden-delivery-tools](plugins/bitwarden-delivery-tools/) | 2.0.0 | Delivery lifecycle skills: initiative funnel navigation, work transitions, tech breakdowns and task decomposition, commits, PRs, preflight, labeling | | [bitwarden-designer](plugins/bitwarden-designer/) | 0.1.0 | Product designer persona: Code of Conduct and 30/60/90 critique, critique facilitation; dispatches into bitwarden-design-tools | diff --git a/plugins/bitwarden-atlassian-tools/.claude-plugin/plugin.json b/plugins/bitwarden-atlassian-tools/.claude-plugin/plugin.json index e47976b2..81a26267 100644 --- a/plugins/bitwarden-atlassian-tools/.claude-plugin/plugin.json +++ b/plugins/bitwarden-atlassian-tools/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "bitwarden-atlassian-tools", - "version": "2.2.8", + "version": "2.3.0", "description": "Read-only Atlassian access via MCP server with deep Jira issue research skill, JQL search, Confluence pages, CQL search, and attachments", "author": { "name": "Bitwarden" diff --git a/plugins/bitwarden-atlassian-tools/CHANGELOG.md b/plugins/bitwarden-atlassian-tools/CHANGELOG.md index c0a58550..d2b29d3d 100644 --- a/plugins/bitwarden-atlassian-tools/CHANGELOG.md +++ b/plugins/bitwarden-atlassian-tools/CHANGELOG.md @@ -5,6 +5,12 @@ All notable changes to the Bitwarden Atlassian Tools plugin will be documented i The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [2.3.0] - 2026-07-20 + +### Added + +- Added the `evaluating-qa-readiness` skill, which checks a Jira ticket for the information QA needs before testing (testing instructions, implementation notes, feature-flag state, acceptance criteria, affected clients, and a linked PR/build) via the read-only Atlassian MCP and drafts a ready-to-paste developer comment for any gaps + ## [2.2.8] - 2026-07-01 ### Security diff --git a/plugins/bitwarden-atlassian-tools/skills/evaluating-qa-readiness/SKILL.md b/plugins/bitwarden-atlassian-tools/skills/evaluating-qa-readiness/SKILL.md index fa9e2107..a12eea35 100644 --- a/plugins/bitwarden-atlassian-tools/skills/evaluating-qa-readiness/SKILL.md +++ b/plugins/bitwarden-atlassian-tools/skills/evaluating-qa-readiness/SKILL.md @@ -1,6 +1,6 @@ --- name: evaluating-qa-readiness -description: Use whenever someone wants to check whether a Jira ticket is ready to hand to QA — "Is PROJ-123 ready for QA?", "QA-check PROJ-123", "Does PROJ-123 have everything QA needs?", "Review PROJ-123 before I move it to Ready for QA", "Is this story ready to test?", or any request to validate that a story/bug has the information a tester needs before testing starts. Reads the ticket via the read-only Atlassian MCP and reports, per objective criterion, what QA needs that is present or missing — feature flag state, testing instructions, implementation notes, acceptance criteria, affected clients, and a linked PR/build — plus a ready-to-paste comment the developer can act on. Use this proactively when a developer says they are moving a ticket to Ready for QA, even if they don't say "QA readiness." +description: Use whenever someone wants to check whether a Jira ticket is ready to hand to QA — "Is PROJ-123 ready for QA?", "QA-check PROJ-123", "Does PROJ-123 have everything QA needs?", "Review PROJ-123 before I move it to Ready for QA", or any request to validate that a story/bug has the information a tester needs before testing starts. Reports what QA needs that is present or missing and drafts a ready-to-paste comment for the developer. Use proactively when a developer says they are moving a ticket to Ready for QA, even if they don't say "QA readiness." --- # Evaluating QA Readiness @@ -21,7 +21,7 @@ If the description or comments reference a PR, build, or Confluence page, note i ### Step 2: Evaluate each criterion -Judge each criterion against everything you gathered — description, all custom fields, comments, and links. For each, decide one of: +Judge each criterion against everything gathered — description, all custom fields, comments, and links. For each, decide one of: - **Present** — the information is there and a tester could act on it. - **Missing** — no trace of it anywhere on the ticket. From 08a660da2b54bd430567b73503f3705310d32f9d Mon Sep 17 00:00:00 2001 From: Graham Walker Date: Wed, 12 Aug 2026 15:08:52 -0500 Subject: [PATCH 3/7] testing JFrog --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 11feebd9..339218a5 100644 --- a/README.md +++ b/README.md @@ -69,3 +69,5 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for plugin development guidelines, struct - [Plugin Reference](https://docs.claude.com/en/docs/claude-code/plugins-reference.md) - [Plugin Marketplaces](https://docs.claude.com/en/docs/claude-code/plugin-marketplaces.md) - [Validation Scripts](https://github.com/bitwarden/gh-actions/tree/main/validate-ai/scripts) + +Graham Walker From 09fbaf23b0313a75e06eccb77e0f49a91106585f Mon Sep 17 00:00:00 2001 From: Graham Walker Date: Thu, 13 Aug 2026 17:11:36 -0500 Subject: [PATCH 4/7] fixing skill based on comments --- README.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/README.md b/README.md index 339218a5..11feebd9 100644 --- a/README.md +++ b/README.md @@ -69,5 +69,3 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for plugin development guidelines, struct - [Plugin Reference](https://docs.claude.com/en/docs/claude-code/plugins-reference.md) - [Plugin Marketplaces](https://docs.claude.com/en/docs/claude-code/plugin-marketplaces.md) - [Validation Scripts](https://github.com/bitwarden/gh-actions/tree/main/validate-ai/scripts) - -Graham Walker From 3afb40e6607159bb4f9e1f7d3b9677a906ebb31b Mon Sep 17 00:00:00 2001 From: Graham Walker Date: Fri, 21 Aug 2026 12:31:57 -0500 Subject: [PATCH 5/7] fixing issues --- plugins/bitwarden-atlassian-tools/README.md | 22 +++++++++++++++++++ .../skills/evaluating-qa-readiness/SKILL.md | 5 +++-- .../examples/sample_evaluation.md | 4 +++- 3 files changed, 28 insertions(+), 3 deletions(-) diff --git a/plugins/bitwarden-atlassian-tools/README.md b/plugins/bitwarden-atlassian-tools/README.md index 6bc94052..668f9bdd 100644 --- a/plugins/bitwarden-atlassian-tools/README.md +++ b/plugins/bitwarden-atlassian-tools/README.md @@ -175,6 +175,28 @@ Features: Live creation requires `ATLASSIAN_JIRA_WRITE_TOKEN`; without it the skill can still draft and preview. +### `assessing-jira-issue-relevance` + +Determines whether a Jira issue still applies to the current codebase by fetching the ticket, locating the code path it describes, and comparing current behavior against the ticket's description. Triggered by questions about whether a ticket is still relevant (e.g., "Is PM-123 still pending?", "Has this been fixed?", "Can we close this?"). + +Features: + +- Fetches ticket, comments, and remote links as evidence, then verifies against the current codebase rather than trusting ticket status +- Returns a verdict (still applicable / fixed / stale) backed by cited evidence +- Assesses one ticket at a time; invoke iteratively for multiple tickets + +### `evaluating-qa-readiness` + +Checks a Jira ticket for the concrete, objectively-verifiable information QA needs before testing starts — testing instructions, implementation notes, feature-flag state, acceptance criteria, affected clients, and a linked PR/build — then drafts a developer comment for any gaps. Triggered by requests to check QA readiness (e.g., "Is PROJ-123 ready for QA?", "QA-check PROJ-123") or proactively when a ticket is being moved to Ready for QA. + +Features: + +- Reads description, custom fields, comments, and remote links as evidence, since developers often drop testing notes or flag names in a comment rather than the description +- Distinguishes blocking gaps (testing instructions, implementation notes, feature flag) from non-blocking ones (acceptance criteria, affected clients, linked PR/build) so the verdict reflects how stuck a tester actually is +- Drafts a targeted, collegial ask addressing only the gaps found + +This skill is read-only: it drafts the developer comment but cannot post it to the ticket. + ## Requirements - Claude Code with MCP support diff --git a/plugins/bitwarden-atlassian-tools/skills/evaluating-qa-readiness/SKILL.md b/plugins/bitwarden-atlassian-tools/skills/evaluating-qa-readiness/SKILL.md index 40ab2053..5d3b6ca8 100644 --- a/plugins/bitwarden-atlassian-tools/skills/evaluating-qa-readiness/SKILL.md +++ b/plugins/bitwarden-atlassian-tools/skills/evaluating-qa-readiness/SKILL.md @@ -1,6 +1,7 @@ --- name: evaluating-qa-readiness -description: Use whenever someone wants to check whether a Jira ticket is ready to hand to QA — "Is PROJ-123 ready for QA?", "QA-check PROJ-123", "Does PROJ-123 have everything QA needs?", or any request to validate that a story or bug has what a tester needs before testing starts. Reports which pieces are present or missing and drafts a comment for the developer. Use proactively when someone says they are moving a ticket to Ready for QA, even without the words "QA readiness." +description: Use whenever the user wants to check whether a Jira ticket is ready to hand to QA — "Is PROJ-123 ready for QA?", "QA-check PROJ-123", "Does PROJ-123 have everything QA needs?", or any request to validate that a story or bug has what a tester needs before testing starts. Reports which pieces are present or missing and drafts a comment for the developer. Use proactively when the user says they are moving a ticket to Ready for QA, even without the words "QA readiness." +allowed-tools: Read, mcp__plugin_bitwarden-atlassian-tools_bitwarden-atlassian__get_issue, mcp__plugin_bitwarden-atlassian-tools_bitwarden-atlassian__get_issue_comments, mcp__plugin_bitwarden-atlassian-tools_bitwarden-atlassian__get_issue_remote_links --- # Evaluating QA Readiness @@ -86,7 +87,7 @@ If nothing is missing, say so plainly and skip the draft comment — no need to - The Atlassian MCP here is **read-only**. You cannot post the comment or change the ticket — you produce the draft for a human to post. Say so if the user expects it to be posted. - If `get_issue` fails or the key doesn't exist, report that plainly rather than guessing at contents. - Never infer that a criterion is satisfied from the issue _type_ or _status_ alone. A ticket marked "Ready for QA" is exactly the case where you should still check — that status is the claim you're verifying, not evidence. -- If a custom field name suggests it holds relevant info (anything mentioning "flag", "test", "QA", "implementation", "platform") but it's empty, that's a Missing signal worth noting by name. +- If a custom field name suggests it holds relevant info (anything mentioning "flag", "test", "QA", "implementation", "platform") but it's empty, note it by name. A clearly-relevant field left empty is Unclear rather than Missing — the ticket neither answers the question nor disclaims it. ## Examples diff --git a/plugins/bitwarden-atlassian-tools/skills/evaluating-qa-readiness/examples/sample_evaluation.md b/plugins/bitwarden-atlassian-tools/skills/evaluating-qa-readiness/examples/sample_evaluation.md index 4ba45fa3..0a76fbad 100644 --- a/plugins/bitwarden-atlassian-tools/skills/evaluating-qa-readiness/examples/sample_evaluation.md +++ b/plugins/bitwarden-atlassian-tools/skills/evaluating-qa-readiness/examples/sample_evaluation.md @@ -28,6 +28,7 @@ Blocking criteria: testing instructions (pass), implementation notes (fail), fea ## Output +``` ## QA Readiness: PM-4821 — Add per-item reprompt toggle to vault item edit view **Verdict:** Not ready — 2 blocking gaps @@ -40,10 +41,11 @@ Blocking criteria: testing instructions (pass), implementation notes (fail), fea | Acceptance criteria | ✅ Present | Stated and testable in description. | | Affected clients/platforms | ✅ Present | Web, Browser Extension (custom field). | | Linked PR/build | ✅ Present | GitHub PR linked via remote links. | +``` **Draft comment for the developer:** -> Nearly there — before this moves to Ready for QA, could you add: +> Before this is ready for QA, could you add: > > - **Feature flag:** the "Feature Flag" field is empty. Is the reprompt toggle behind a flag? If so, which flag and what state should QA set it to? If it's not flagged, a quick "not behind a flag" works. > - **Implementation notes:** a one-line summary of what changed and which areas it touches, so QA knows the surface to exercise (the PR link alone means reading the diff). From d2ad991eda43fbe23cabe878db65503d476d3887 Mon Sep 17 00:00:00 2001 From: Graham Walker Date: Wed, 26 Aug 2026 11:14:28 -0500 Subject: [PATCH 6/7] AI-27 fixing skill based on feedback --- .claude-plugin/marketplace.json | 2 +- README.md | 2 +- .../.claude-plugin/plugin.json | 2 +- plugins/bitwarden-atlassian-tools/CHANGELOG.md | 8 ++++++++ .../skills/evaluating-qa-readiness/SKILL.md | 12 ++++++++++-- .../evaluating-qa-readiness/references/criteria.md | 6 ++++++ 6 files changed, 27 insertions(+), 5 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index e74b8aad..52212198 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -48,7 +48,7 @@ { "name": "bitwarden-atlassian-tools", "source": "./plugins/bitwarden-atlassian-tools", - "version": "2.7.0", + "version": "2.7.1", "description": "Atlassian access via MCP server with deep Jira issue research skill, JQL search, Confluence pages, CQL search, attachments, and opt-in Jira write tools" }, { diff --git a/README.md b/README.md index 6f3696fe..ab117633 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ A curated collection of plugins for AI-assisted development at Bitwarden. Enable | [bitwarden-ai-telemetry](plugins/bitwarden-ai-telemetry/) | 1.1.0 | Claude Code hooks emitting metadata-only AI-usage telemetry (identity, git-linkage, MCP) via OTLP | | [bitwarden-tech-lead](plugins/bitwarden-tech-lead/) | 3.0.1 | Tech lead for technical planning, architecture coherence, and surfacing patterns to Technical Strategy Ideas | | [bitwarden-shepherd](plugins/bitwarden-shepherd/) | 1.0.1 | Champion of a technical strategy — shepherds a TSI through evaluation into the funnel, then through to adoption | -| [bitwarden-atlassian-tools](plugins/bitwarden-atlassian-tools/) | 2.7.0 | Atlassian access via MCP server with deep Jira issue research skill and opt-in Jira write tools | +| [bitwarden-atlassian-tools](plugins/bitwarden-atlassian-tools/) | 2.7.1 | Atlassian access via MCP server with deep Jira issue research skill and opt-in Jira write tools | | [bitwarden-code-review](plugins/bitwarden-code-review/) | 1.13.1 | Autonomous code review agent following Bitwarden engineering standards with GitHub integration | | [bitwarden-delivery-tools](plugins/bitwarden-delivery-tools/) | 3.0.0 | Delivery lifecycle skills: initiative funnel navigation, work transitions, architectural judgment, commits, PRs, preflight, labeling | | [bitwarden-designer](plugins/bitwarden-designer/) | 0.1.0 | Product designer persona: Code of Conduct and 30/60/90 critique, critique facilitation; dispatches into bitwarden-design-tools | diff --git a/plugins/bitwarden-atlassian-tools/.claude-plugin/plugin.json b/plugins/bitwarden-atlassian-tools/.claude-plugin/plugin.json index 694e7b32..c3183389 100644 --- a/plugins/bitwarden-atlassian-tools/.claude-plugin/plugin.json +++ b/plugins/bitwarden-atlassian-tools/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "bitwarden-atlassian-tools", - "version": "2.7.0", + "version": "2.7.1", "description": "Atlassian access via MCP server with deep Jira issue research skill, JQL search, Confluence pages, CQL search, attachments, and opt-in Jira write tools", "author": { "name": "Bitwarden" diff --git a/plugins/bitwarden-atlassian-tools/CHANGELOG.md b/plugins/bitwarden-atlassian-tools/CHANGELOG.md index c61a9a30..b2335e3d 100644 --- a/plugins/bitwarden-atlassian-tools/CHANGELOG.md +++ b/plugins/bitwarden-atlassian-tools/CHANGELOG.md @@ -5,6 +5,14 @@ All notable changes to the Bitwarden Atlassian Tools plugin will be documented i The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [2.7.1] - 2026-08-26 + +### Fixed + +- `evaluating-qa-readiness` no longer reports "no PR or build is linked" as a settled fact. `get_issue_remote_links` cannot see Jira's native Development panel (the GitHub/Bitbucket integration that links most PRs via smart commits or branch naming), so an empty result is now reported as "not found in the sources this check can search" with a pointer to check the Development panel manually, instead of a confident negative. +- `evaluating-qa-readiness`'s feature-flag criterion and developer-ask draft no longer demand an explicit on/off state when only one flag is named — "enable to test" is now the assumed default unless the ticket gives a real reason the state is ambiguous. +- `evaluating-qa-readiness`'s drafted developer ask now names the gap without dictating exhaustive step-by-step detail (exact queries, seed data, timing) that a competent tester doesn't need. + ## [2.7.0] - 2026-08-06 ### Added diff --git a/plugins/bitwarden-atlassian-tools/skills/evaluating-qa-readiness/SKILL.md b/plugins/bitwarden-atlassian-tools/skills/evaluating-qa-readiness/SKILL.md index 5d3b6ca8..d3daf4fd 100644 --- a/plugins/bitwarden-atlassian-tools/skills/evaluating-qa-readiness/SKILL.md +++ b/plugins/bitwarden-atlassian-tools/skills/evaluating-qa-readiness/SKILL.md @@ -20,6 +20,8 @@ Then use `get_issue_comments` — developers frequently drop testing steps, flag If the description or comments reference a PR, build, or Confluence page, note it; use `get_issue_remote_links` to catch linked PRs and pages that aren't inline. The goal is _evidence that the information exists somewhere on the ticket_, wherever the developer put it. +**Known blind spot:** `get_issue_remote_links` does not surface Jira's native Development panel — the PR/branch/commit links that Jira's GitHub integration attaches automatically via smart commits or branch naming, which is how most PRs actually get linked. Neither MCP tool here can see that panel. So absence of a result from `get_issue`/`get_issue_remote_links` is not evidence a PR isn't linked — it only means it isn't linked through the sources this check can search. Carry that caveat into Step 3. + ### Step 2: Evaluate each criterion Judge each criterion against everything gathered — description, all custom fields, comments, and links. For each, decide one of: @@ -34,7 +36,7 @@ Read the criteria definitions and what counts as satisfied in `references/criter 1. **Testing instructions** — how to validate the change: setup/preconditions, steps, and expected result. For a bug, this includes what "fixed" looks like versus the original broken behavior. 2. **Implementation notes** — what was changed and where, at enough detail for a tester to know what surface area to exercise. -3. **Feature flag** — whether the change sits behind a flag. If it does, the flag's name/key **and** the state QA needs it in (on/off) to test. If it doesn't, the ticket should say so — "not behind a flag" is a valid, passing answer. Silence is the gap, because the tester otherwise can't tell whether they're testing the right thing. +3. **Feature flag** — whether the change sits behind a flag. If it does, the flag's name/key **and** the state QA needs it in (on/off) to test. If it doesn't, the ticket should say so — "not behind a flag" is a valid, passing answer. Silence on whether a flag exists at all is the gap. Silence on _state_ is not automatically a gap: if exactly one flag is named, default to assuming "enable it to test" and only flag the state as unclear when something about the ticket makes the right state genuinely ambiguous (see `references/criteria.md`). **Non-blocking** (QA can usually start, but these save round-trips): @@ -70,9 +72,15 @@ Rules for the verdict: In the Notes column, cite the evidence when something passes (where you found it — "steps in description", "flag name in comment by @dev") and state specifically what's absent when it doesn't. Vague notes ("needs more detail") aren't actionable; "no expected result given for the reset-password step" is. +**Linked PR/build is the one exception to stating an absence as fact.** If no PR/build turns up in the description, comments, or `get_issue_remote_links`, don't write "Missing" as if that's settled. Write something like "⚠️ Not found in description/comments/remote links — check the ticket's Development panel in Jira, which this tool can't see" and don't count it toward the verdict as a confirmed gap the way a true Missing would be. + ### Step 4: Draft the developer ask -If there are any gaps, produce a short comment the QA (or the tool user) can paste onto the ticket to ping the developer. Address only the gaps — don't restate what's already there. Keep it collegial and specific; the goal is to make it trivial for the developer to fill the holes: +If there are any gaps, produce a short comment the QA (or the tool user) can paste onto the ticket to ping the developer. Address only the gaps — don't restate what's already there. Keep it collegial and specific; the goal is to make it trivial for the developer to fill the holes. + +**Ask for the gap, not for exhaustive detail.** The ask should name what's missing, not dictate how thoroughly the developer must answer it. Don't demand step-by-step scripts, exact tool/table/query names, or timing specifics for testing instructions — a competent tester doesn't need a walkthrough of routine functionality, just a callout for anything non-obvious. And don't ask questions the ticket already lets you answer yourself — e.g. don't ask "what state should the flag be in?" when only one flag is named and "enable to test" is the obvious inference; ask about state only when it's genuinely ambiguous. + +**Don't phrase the PR/build gap as a fact.** Per the known limitation above, phrase it as "I couldn't find a linked PR or build in the description/comments/remote links — is there one linked elsewhere (e.g. the Development panel)?" rather than asserting none exists. ``` Before this is ready for QA, could you add: diff --git a/plugins/bitwarden-atlassian-tools/skills/evaluating-qa-readiness/references/criteria.md b/plugins/bitwarden-atlassian-tools/skills/evaluating-qa-readiness/references/criteria.md index 6fd7c2eb..01279ac9 100644 --- a/plugins/bitwarden-atlassian-tools/skills/evaluating-qa-readiness/references/criteria.md +++ b/plugins/bitwarden-atlassian-tools/skills/evaluating-qa-readiness/references/criteria.md @@ -35,6 +35,8 @@ For a **bug**, this means both the original broken behavior and what "fixed" loo **Why silence is a gap**: without this, the tester can't tell whether the feature will even be visible in their environment, and a "passing" test against a flagged-off build is worse than no test. An explicit "not behind a flag" is a passing answer — the requirement is a clear answer, not a flag. +**Inference is allowed for state.** If exactly one flag is named for the change and no explicit on/off state is given, the reasonable default is "enable it to exercise the new behavior" — don't flag the state as a gap just because it wasn't spelled out. Only treat the state as genuinely Unclear when there's a real reason the correct state isn't obvious: multiple flags or environments that could behave differently, a flag that gates removal/deprecation (where "off" is the interesting state), or the ticket itself raises a question about rollout (e.g., cloud vs. self-hosted needing different treatment). The bar is "would a competent tester actually be stuck," not "is every detail spelled out." + ## Non-blocking criteria QA can usually begin without these, but each one that's missing tends to cause a round-trip mid-test. Flag them so they get fixed, but don't block the handoff on them alone. @@ -57,6 +59,10 @@ QA can usually begin without these, but each one that's missing tends to cause a **Partial credit**: a PR link is good; a link to an installable build or a named version QA can pull is better. Either satisfies the criterion. +**Known limitation — read before reporting this criterion as failing.** The only sources this check can see are the description, comments, and whatever `get_issue_remote_links` returns (Confluence pages and any manually-added remote links). Jira's native **Development panel** — the one populated automatically by the GitHub/Bitbucket integration via smart commits or branch naming, which is how most PRs actually get linked to a ticket — is a separate data source that neither MCP tool exposes. That panel is invisible to this check. + +This means a PR can be linked on the ticket (visible in the Jira UI) while both tools report nothing. **Never state "no PR or build is linked" as a fact.** Report it as: not found in the sources this check can search (description, comments, remote links), and note explicitly that the ticket's Development panel isn't visible to this tool and should be checked manually in Jira before treating this as a real gap. + ## Judgment notes - **Where developers put things varies.** Some teams keep testing steps in a custom field, others in the description, others in a comment. Search all of them before calling something missing — a false "missing" erodes trust in the check faster than a missed gap. From 5de52388f1c3694158f08dbc963c9e66bca97f6a Mon Sep 17 00:00:00 2001 From: Graham Walker Date: Wed, 26 Aug 2026 12:20:21 -0500 Subject: [PATCH 7/7] AI-27 fixing issues based on comments --- plugins/bitwarden-atlassian-tools/CHANGELOG.md | 1 + plugins/bitwarden-atlassian-tools/README.md | 12 ++++++------ 2 files changed, 7 insertions(+), 6 deletions(-) diff --git a/plugins/bitwarden-atlassian-tools/CHANGELOG.md b/plugins/bitwarden-atlassian-tools/CHANGELOG.md index b2335e3d..a1076972 100644 --- a/plugins/bitwarden-atlassian-tools/CHANGELOG.md +++ b/plugins/bitwarden-atlassian-tools/CHANGELOG.md @@ -12,6 +12,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - `evaluating-qa-readiness` no longer reports "no PR or build is linked" as a settled fact. `get_issue_remote_links` cannot see Jira's native Development panel (the GitHub/Bitbucket integration that links most PRs via smart commits or branch naming), so an empty result is now reported as "not found in the sources this check can search" with a pointer to check the Development panel manually, instead of a confident negative. - `evaluating-qa-readiness`'s feature-flag criterion and developer-ask draft no longer demand an explicit on/off state when only one flag is named — "enable to test" is now the assumed default unless the ticket gives a real reason the state is ambiguous. - `evaluating-qa-readiness`'s drafted developer ask now names the gap without dictating exhaustive step-by-step detail (exact queries, seed data, timing) that a competent tester doesn't need. +- README's `## Usage` examples used the unscoped `mcp__bitwarden-atlassian__` prefix; corrected to the plugin-scoped `mcp__plugin_bitwarden-atlassian-tools_bitwarden-atlassian__` form that Claude Code actually resolves. ## [2.7.0] - 2026-08-06 diff --git a/plugins/bitwarden-atlassian-tools/README.md b/plugins/bitwarden-atlassian-tools/README.md index 668f9bdd..0b4ec04d 100644 --- a/plugins/bitwarden-atlassian-tools/README.md +++ b/plugins/bitwarden-atlassian-tools/README.md @@ -140,13 +140,13 @@ A leaked write token permits more than these two tools use: `write:comment:jira` ## Usage -The MCP tools are available as `mcp__bitwarden-atlassian__`. Examples: +The MCP tools are available as `mcp__plugin_bitwarden-atlassian-tools_bitwarden-atlassian__`. Examples: -- Read an issue: `mcp__bitwarden-atlassian__get_issue` with `issueIdOrKey: "PROJ-123"` -- Search with JQL: `mcp__bitwarden-atlassian__search_issues` with `jql: "project = PROJ AND status = Open"` -- Read a Confluence page: `mcp__bitwarden-atlassian__get_confluence_page` with `pageId: "123456789"` -- Search Confluence: `mcp__bitwarden-atlassian__search_confluence_cql` with `cql: "space = EN AND text ~ \"search term\""` -- Preview a ticket before creating it: `mcp__bitwarden-atlassian__create_issue` with `project: "PM"`, `issueType: "Story"`, `summary: "Add CSV export to the item list"` — omit `dryRun` (defaults to `true`) to get the payload back without creating anything +- Read an issue: `mcp__plugin_bitwarden-atlassian-tools_bitwarden-atlassian__get_issue` with `issueIdOrKey: "PROJ-123"` +- Search with JQL: `mcp__plugin_bitwarden-atlassian-tools_bitwarden-atlassian__search_issues` with `jql: "project = PROJ AND status = Open"` +- Read a Confluence page: `mcp__plugin_bitwarden-atlassian-tools_bitwarden-atlassian__get_confluence_page` with `pageId: "123456789"` +- Search Confluence: `mcp__plugin_bitwarden-atlassian-tools_bitwarden-atlassian__search_confluence_cql` with `cql: "space = EN AND text ~ \"search term\""` +- Preview a ticket before creating it: `mcp__plugin_bitwarden-atlassian-tools_bitwarden-atlassian__create_issue` with `project: "PM"`, `issueType: "Story"`, `summary: "Add CSV export to the item list"` — omit `dryRun` (defaults to `true`) to get the payload back without creating anything ## Skills