v3.5.0 feat(qa): story-first qa:plan companion artifact

[mujtaba3B]

Summary

Makes every /qa:plan companion artifact open story-first, per 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.

• qa/skills/qa-plan/references/artifact-template.html gains a context region above the Development section: The story (user story + observed problem), The solution being built, and How this plan proves it (numbered bullets mapping the plan's rows to the story outcome), each with a FILL marker (STORY / SOLUTION / PROOF) and token-based CSS covering both themes. The worked example stays self-rendering.
• SKILL.md Step 4b documents how to fill the three blocks from the Step 2 success criteria (never invented), keeping the marker list in lockstep with the template.
• qa:plan CHANGELOG v2.1.0 entry; skill frontmatter 2.0.0 -> 2.1.0; qa plugin 3.4.1 -> 3.5.0.

Reference implementation already live: the pr-watcher v4 QA artifact was republished today with this exact structure.

QA

📄 Plan view: https://claude.ai/code/artifact/eec14acb-db23-4145-9bf1-5de8bed65b93

QA driver: Claude, the building agent (this session) - every Dev row is runnable from this machine right now
Standard (all green): unit tests · lint/types · CI · /eng:cr

🖥️ Development

Before merge we prove the new template on this machine: render it in both themes to see the story blocks lead the page, and walk the authoring instructions end to end to confirm they produce the same result.

✓	Tester	Check	Expect	Notes
[x]	claude	Render check: publish the edited template's worked example to a scratch artifact	Story / Solution / Proof blocks render above Development, light and dark, no sideways scroll	Compared against the live pr-watcher v4 reference artifact (d4780d67)
[x]	claude	Marker contract: template FILL markers vs SKILL.md Step 4b	STORY / SOLUTION / PROOF added and named in both; existing markers unchanged	grep both files; header comment marker list updated too
[x]	claude	Self-containment sweep of the template	No external URLs; only inline CSS and data: URIs	Artifact CSP blocks external hosts; a stray link renders broken silently
[x]	claude	Authoring dry-run: fill the new template for a sample change following only Step 4b	Resulting page opens story-first with proof bullets mapping to its rows	Proves the instructions carry the format, not this session's memory of it

🚀 Production

After merge we reinstall the plugin so future sessions read the new template from the cache, then confirm the next real QA plan artifact opens with its story.

Tester	Check	Expect	Notes
claude	After merge: bin/install, then diff cache copy vs merged main	Cache qa/3.5.0 carries references/artifact-template.html byte-identical to the repo	Skills read from the plugin cache, not the repo; install is the refresh trigger
mujtaba	Next real /qa:plan run on any change	Its artifact opens with story, solution, and proof; "what are we solving" answered at a glance	The acceptance bar is Mujtaba's read, since his feedback drove the change

Production artifacts: plugin cache copy ~/.claude/plugins/cache/gstack-extensions/qa/3.5.0/skills/qa-plan/references/artifact-template.html (plus the updated SKILL.md beside it) on Mujtaba's laptop, exercised by the next /qa:plan invocation; refreshed only by bin/install (prod row 1 performs and verifies the refresh).

Definition of Done:

• Tests written and green
• Independent local review clear (/eng:cr) + CodeRabbit addressed
• Docs updated where user-facing
• where-things-run.json bumped if the deploy changed hosts

QA posture: Pre-merge, state QA_STATUS: dev_verified plus EVIDENCE: once every Dev QA box and every Definition-of-Done bullet is checked. Post-deploy, state QA_STATUS: prod_verified plus EVIDENCE: once the Prod QA rows are verified live.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Updated QA plan artifacts to a story-first layout, showing the user story, proposed solution, and proof approach before any test details.
  • Added dedicated context blocks (story/solution/proof) with clearer success-criteria guidance and proof bullets pointing to the relevant plan rows.
  • Improved readability with self-contained, theme-aware rendering and clearer checkbox glyphs (☐/☑).

• Documentation

  • Updated the QA plan skill/changelog and artifact template instructions to reflect the new story-first workflow.

[coderabbitai]

📝 Walkthrough

Walkthrough

The QA plan skill now publishes story, solution, and proof context before QA tables. The companion HTML template adds matching placeholders and styling, while metadata and changelog versions advance to the new release.

Changes

QA plan story-first artifact

Layer / File(s)	Summary
Skill contract and release metadata qa/skills/qa-plan/SKILL.md, qa/skills/qa-plan/CHANGELOG.md, qa/.claude-plugin/plugin.json	Step 4b now requires STORY, SOLUTION, and PROOF sections above Development, with self-contained HTML and checkbox glyphs. Skill, plugin, and changelog versions are updated.
Story-first HTML template qa/skills/qa-plan/references/artifact-template.html	The template adds story, solution, and proof placeholders, inline styling, heading styling, and example content before the Development and Production QA phases.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• mujtaba3B/gstack-extensions#55: Introduced the companion artifact and its FILL-based rendering used by this update.

Poem

First comes the story, clear and bright,
Then solution steps come into sight.
Proof follows close with checks in line,
Before QA tables neatly shine.
A version bump marks the design.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title is concise and accurately summarizes the main change: a story-first QA plan companion artifact for v3.5.0.

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@qa/skills/qa-plan/references/artifact-template.html`:
- Around line 98-120: Update the context block headings for “The story,” “The
solution being built,” and “How this plan proves it” to preserve the document’s
heading hierarchy after the page h1, using h2 or an equivalent context h2 parent
with nested h3 headings; adjust the matching CSS selectors so the existing
styling remains unchanged.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 85ecb693-738b-4da2-92c7-e42e0298fe05

📥 Commits

Reviewing files that changed from the base of the PR and between d7a554c and 82547e6.

📒 Files selected for processing (4)

• qa/.claude-plugin/plugin.json
• qa/skills/qa-plan/CHANGELOG.md
• qa/skills/qa-plan/SKILL.md
• qa/skills/qa-plan/references/artifact-template.html

[mujtaba3B]

QA_STATUS: dev_verified
EVIDENCE: All 4 Dev QA rows executed this session on the edited template: (1) render check via headless Chromium on the doctype-wrapped worked example, light + dark screenshots, story/solution/proof blocks lead the page, no horizontal scroll; (2) marker contract grep: template FILL list and SKILL.md Step 4b name STORY/SOLUTION/PROOF 1:1, existing markers unchanged; (3) self-containment sweep: zero external URLs, data: URIs only; (4) authoring dry-run: cloned the template and swapped FILL regions per Step 4b for a sample change, resulting page opens story-first (order STORY>SOLUTION>PROOF>DEV>PROD verified programmatically). claude plugin validate . --strict passes at qa 3.5.0. /eng:cr stamped on HEAD 953b52a; CodeRabbit round settled clean (1 actionable, fixed and CR-confirmed).

[mujtaba3B]

Prod QA row 1 verified post-merge: ran bin/install; ~/.claude/plugins/cache/gstack-extensions/qa/3.5.0/skills/qa-plan/references/artifact-template.html and SKILL.md are byte-identical to merged main (fdd24b5). Prod row 2 (next real /qa:plan artifact opens story-first, Mujtaba's read) remains open; posture stays dev_verified until then.

[mujtaba3B]

QA_STATUS: prod_verified
EVIDENCE: Prod row 1: after merge, bin/install refreshed the cache and ~/.claude/plugins/cache/gstack-extensions/qa/3.5.0/skills/qa-plan/references/artifact-template.html + SKILL.md are byte-identical to merged main (fdd24b5). Prod row 2: Mujtaba reviewed and confirmed the story-first layout on the live artifacts (the template-change plan artifact and the restructured pr-watcher plan artifact, both republished with the h2 heading fix); the artifact opens with story, solution, and proof before any QA table.