diff --git a/qa/.claude-plugin/plugin.json b/qa/.claude-plugin/plugin.json index b3567aa..156c5e9 100644 --- a/qa/.claude-plugin/plugin.json +++ b/qa/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "qa", - "version": "3.4.1", + "version": "3.5.0", "description": "QA Quincey, the manual-QA persona. Verifies one defined flow against the spec or mockup and records a QA posture. qa:browser drives the real running app through the user's persistent agent-browser session (click/pixel level), walks the spec, seeds and tears down tagged data via the repo's recipe, and ends with the QA_STATUS contract that satisfies the build-time Stop hook and the PR qa-gate CI. qa:headless does the same for backend features with no UI (capturing side effects). qa:qa-plan authors the two-phase QA plan and writes the approval stamp. The plugin also SHIPS Quincey's enforcement hooks (hooks/hooks.json): the QA-plan gates (presentation, build, PR) and the QA-status Stop gate, active in opted-in repos (.qa-plan-gate.json) under ~/dev. Skills: qa:browser, qa:headless, qa:qa-plan.", "author": { "name": "Mujtaba Badat", diff --git a/qa/skills/qa-plan/CHANGELOG.md b/qa/skills/qa-plan/CHANGELOG.md index 6da7466..e7f257b 100644 --- a/qa/skills/qa-plan/CHANGELOG.md +++ b/qa/skills/qa-plan/CHANGELOG.md @@ -1,5 +1,18 @@ # qa:plan CHANGELOG +## v2.1.0 + +Story-first companion artifact. + +- The artifact template now opens with three context blocks above the + Development section: **The story** (the change's user story plus the observed + problem), **The solution being built**, and **How this plan proves it** + (numbered bullets mapping the plan's rows to the story's outcome), each with + its own FILL marker (`STORY` / `SOLUTION` / `PROOF`). Step 4b documents how to + fill them from the Step 2 success criteria (never invented). Driven by + Mujtaba's 2026-07-20 feedback: a QA artifact should say what problem is being + solved and what the solution is before showing any test rows. + ## v2.0.0 Readability overhaul + a pointable companion artifact. diff --git a/qa/skills/qa-plan/SKILL.md b/qa/skills/qa-plan/SKILL.md index 85313bc..0628bbb 100644 --- a/qa/skills/qa-plan/SKILL.md +++ b/qa/skills/qa-plan/SKILL.md @@ -1,6 +1,6 @@ --- name: qa-plan -version: 2.0.0 +version: 2.1.0 description: | QA Quincey's planning skill: turn a change's success criteria into a two-phase QA plan written into the PR body, BEFORE the PR is reviewed or merged. Produces a @@ -160,7 +160,14 @@ Mechanics: Publish a rendered, always-linked view of the same plan as a Claude **artifact**, so there is one pretty page to point at. The artifact is a **companion**, not the source of truth: the gates only ever read the PR-body `## QA` section (Step 4). The artifact can carry the full mechanics that would bloat the table. -1. **Build the HTML.** Copy `references/artifact-template.html` (this skill's base directory) to the session scratchpad and swap the content between the `FILL:` markers: the **title**, the **Development** ELI5 + rows, the **Production** ELI5 + rows, the **Production artifacts**, and the **Definition of Done**. The artifact is the leaner companion view: it deliberately drops the QA-driver line, the `Standard (all green)` line, and the QA-posture line (those live in the PR body, the source of truth). The template is self-contained (inline CSS + data-URI images, theme-aware, no external assets, which the artifact CSP requires) and uses display checkbox glyphs (`☐` / `☑`), NEVER square-bracket checkboxes (the artifact is never gate-parsed, so glyphs are free here). +1. **Build the HTML.** Copy `references/artifact-template.html` (this skill's base directory) to the session scratchpad and swap the content between the `FILL:` markers: the **title**, the story-first **context blocks** (STORY / SOLUTION / PROOF, below), the **Development** ELI5 + rows, the **Production** ELI5 + rows, the **Production artifacts**, and the **Definition of Done**. The artifact is the leaner companion view: it deliberately drops the QA-driver line, the `Standard (all green)` line, and the QA-posture line (those live in the PR body, the source of truth). + + **Story-first context blocks (required).** The page opens with three blocks ABOVE the Development section, so a reader gets what problem is being solved, what is being built, and how the plan proves it before any table: + - `FILL: STORY` - the change's user story in one sentence (`As , when , I want , so `), then the observed problem in a muted line (the incident, gap, or pain that motivated the change, with date/PR when one exists). Derive it from the same success criteria Step 2 pulled (spec, issue, mockup, or the user's own words); never invent it. + - `FILL: SOLUTION` - one paragraph naming what is being built to deliver that outcome, concrete enough that the QA rows below visibly test it. + - `FILL: PROOF` - 2-4 numbered bullets mapping the plan to the story: each states one thing the plan establishes and ends with a muted pointer to the rows that establish it (for example "(Dev rows 1-3.)", "(Prod row 2.)"). This is the bridge that lets the reader see the QA verifies the solution actually solves the story's problem. + + The template is self-contained (inline CSS + data-URI images, theme-aware, no external assets, which the artifact CSP requires) and uses display checkbox glyphs (`☐` / `☑`), NEVER square-bracket checkboxes (the artifact is never gate-parsed, so glyphs are free here). **Driver avatars.** The `Tester` cell shows a logo-only avatar that carries the driver's identity for assistive tech via `role="img"` + `aria-label` (the `title` is the hover tooltip), with the decorative inner `.pic` marked `aria-hidden`: ``, where `` is a roster id with a built-in avatar (`claude` `mutwo` `muthree` `mufour` `mujtaba`). For any driver without one, use the initials fallback: ``. The template's header comment documents how to add a new avatar (inline its `github.com/.png` as a data URI in a new `.pic.` rule; `claude` is a hand-drawn inline-SVG burst on Anthropic clay). diff --git a/qa/skills/qa-plan/references/artifact-template.html b/qa/skills/qa-plan/references/artifact-template.html index 9ec291d..a654cf8 100644 --- a/qa/skills/qa-plan/references/artifact-template.html +++ b/qa/skills/qa-plan/references/artifact-template.html @@ -2,7 +2,9 @@ +

As Mujtaba, when email-hero's LLM starts failing in production, I want the health check to notice and flag it, so silent LLM breakage surfaces in the mini's triage instead of going unnoticed for days.

+

Observed problem: LLM calls were failing quietly inside the daemon; email-hero health stayed green because nothing recorded the failures where it could see them.

+ +
+

The solution being built

+ +

A per-failure sink records every LLM failure to llm-failures.jsonl, and email-hero health counts the failures inside its window, exiting non-zero past --llm-max-failures so mini check #8 turns red when the LLM is breaking.

+
+
+

How this plan proves it

+ +
    +
  • 1.The counting rules are right in isolation: unit tests cover in-window counting, torn lines, and the cap. (Dev row 1.)
    • +
  • 2.A forced failure on a real copy is noticed end to end: the sink records it and health exits non-zero at the threshold. (Dev row 2.)
    • +
  • 3.The live daemon on the mini behaves the same after deploy, which is the story's outcome verified in production. (Prod row 1.)
    • +
+
+ +

🖥️ Development