bitwarden · prograhamming · Jul 13, 2026
@@ -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: <ISSUE-KEY> — <summary>
+**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 | <evidence or what's missing> |
+| 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.
@@ -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!
@@ -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.