Feature/skills library gh issue

.agents/skills/write-implementation-brief/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: write-implementation-brief
+description: >
+  Write the Implementation Brief and Test Coverage sections of a Site Kit issue from its
+  acceptance criteria. Use when the user asks to write, draft, fill in, or groom an
+  implementation brief and/or test coverage for an issue (e.g. "write the implementation brief
+  for #12345", "fill in the brief and test coverage for this issue", "groom issue 12345") in the
+  google/site-kit-wp repo.
+argument-hint: "[issue-number-or-path]"
+allowed-tools: Bash, Read, Grep, Glob, Edit, Write
+---
+
+# Write an implementation brief
+
+Write the **Implementation Brief** and **Test Coverage** sections for **$ARGUMENTS** — either a
+GitHub issue number, or a path the user supplied to a local issue file. If you were given
+neither, ask for one before doing anything else; never go looking for the file yourself. Do not
+reimplement the procedure here — read and follow the playbook, which is the single source of
+truth shared with the other AI tools.
+
+## Procedure
+
+1. **Read the playbook** `docs/context/workflow/write-implementation-brief.md` and follow every
+   step: read the issue, read the design doc and sibling issues, verify every symbol against the
+   code, load only the relevant `docs/context/{js,php}` convention docs, write the two sections,
+   and report what you left out.
+2. **Read the issue**: `gh issue view $ARGUMENTS --json title,body,labels` for an issue number, or
+   read the path the user supplied. Stop and ask the user if the acceptance criteria are missing,
+   ambiguous, or contradictory.
+3. **Read the design doc**: use the one the issue links or the path the user gives you; otherwise
+   ask for it, bundling the question with any ask from step 2. Many issues have none — if there
+   isn't one, say so and work from the acceptance criteria and the code rather than stalling.
+4. **Verify against the code** before naming anything. Open every file the brief will touch and
+   confirm each class, method, hook, handle and path exists as you describe it. Where the design
+   doc and the code disagree, the code wins.
+5. **Write the two sections** in place. The brief is grouped by path, one instruction per bullet,
+   naming real symbols/components/strings and pointing at existing exemplars. Test Coverage is
+   short: one bullet per test file or area, cases nested and phrased as behaviors, Storybook
+   stories listed there rather than in the brief.
+6. **Report separately** the discrepancies, unanticipated consequences, and assumptions that did
+   not belong in the brief.
+
+## Important
+
+- **Instructions only.** No rationale, no trade-off discussion, no restated acceptance criteria,
+  no background on how the existing system works.
+- **Omit what isn't needed.** Never write "no Storybook changes required" or similar — silence
+  says it.
+- **No routine commands.** Lint, build, test and VRT invocations belong to
+  `docs/context/workflow/implement-issue.md`, not the brief.
+- **No links to local design docs** — the brief is read on GitHub where those paths don't
+  resolve.
+- **Only the two sections.** Leave Feature Description, Acceptance criteria, QA Brief and
+  Changelog entry untouched, and do not edit the GitHub issue or post a comment unless the user
+  explicitly asks.

.agents/skills/write-issue/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: write-issue
+description: >
+  Write the description and Acceptance criteria of a Site Kit issue — a feature request or a bug
+  report — from a design doc, from a bug report, or from requirements given in the message. Use
+  when the user asks to create, draft or write a GitHub issue or ticket, to file a bug, to break
+  an epic's design doc into issues, or to write/add acceptance criteria for an existing issue
+  (e.g. "create an issue for the read_article event from this design doc", "write a bug report
+  for the audience tile showing no data", "write the remaining issues from design-doc.md", "add
+  acceptance criteria to #12345") in the google/site-kit-wp repo.
+argument-hint: "[design-doc-path, issue-number, bug report, or requirements]"
+allowed-tools: Bash, Read, Grep, Glob, Edit, Write
+---
+
+# Write an issue
+
+Write the **description** and the **Acceptance criteria** for **$ARGUMENTS** — a design doc path,
+a bug report, requirements stated in the user's message, or an existing issue that needs criteria.
+Do not reimplement the procedure here — read and follow the playbook, which is the single source
+of truth shared with the other AI tools.
+
+## Procedure
+
+1. **Read the playbook** `docs/context/workflow/write-issue.md` and follow every step.
+2. **Establish the issue type**, because it decides the template and the sections you write:
+   - **Feature request** — `.github/ISSUE_TEMPLATE/feature_request.md`: the **Feature
+     Description** and the **Acceptance criteria**.
+   - **Bug report** — `.github/ISSUE_TEMPLATE/bug_report.md`: the **Bug Description**, the
+     **Steps to reproduce** and the **Acceptance criteria**.
+
+   **Ask the user which type they want whenever their message does not make it clear**, and wait
+   for the answer before writing anything. Say how you read the request when you ask. An existing
+   issue keeps the type it already has — never convert one into the other. A request to change
+   behavior that works as designed is a feature request, even when the user calls it a fix.
+3. **Establish the source and the mode.** New issue → write the description sections and the
+   criteria. Existing issue whose description is already written → write **only** the criteria and
+   leave the description byte-for-byte alone. Ask the user if no source was given, the
+   requirements are ambiguous, or a design doc covers an epic without saying which issue to write.
+   Never invent a design-doc path or go hunting for a local issue file.
+4. **Read the source material end to end** — the whole design doc (the rationale for one issue's
+   decisions often sits in another's section), any spec it names as authoritative, the sibling
+   issues already written for the epic, and, for a bug, the whole report plus whatever evidence it
+   names: a support thread, a linked issue, the pull request the user says introduced it.
+5. **Verify against the code** before naming anything: every class, method, hook, constant,
+   handle and path, the shape of the base class or registry being extended, and who consumes the
+   data the issue changes. For a bug, confirm the wrong behavior is really what the code does
+   today and find the lines that produce it. Where the design doc and the code disagree, the code
+   wins.
+6. **Lay the issue out** by copying the template file for the type — drop its YAML frontmatter,
+   put the title in its place as a single `# ` heading, and keep everything else as the file has
+   it, including the moderator notice and the placeholder comment in every section you are not
+   writing. The two templates word their placeholders differently, so copy them from the file for
+   the type you are writing rather than from the other one. On a bug report, Screenshots and
+   Additional Context stay as the template gives them, filled in only with environment facts the
+   user actually stated. The title names the deliverable, or for a bug the symptom and where it
+   happens; nothing sits between it and the first description heading. A dependency on another
+   issue is a clause inside the description, by real GitHub issue number.
+7. **Write the description** — prose, and the only place rationale belongs. A **Feature
+   Description** gives the gap today, what this adds, the halves of the work, and the load-bearing
+   decisions with their reasons. A **Bug Description** gives the wrong behavior on the real
+   surface with its values, what should happen instead, and the conditions it needs — plus the
+   cause in one clause only when you verified it in the code, never the fix. **Steps to reproduce**
+   are a numbered list starting from a state the tester can reach, one action per step with real
+   values, ending in what the tester sees and what they should have seen.
+8. **Write the Acceptance criteria** — a flat `*` list, one checkable outcome per bullet, nested
+   only for enumerable cases, tables inlined for lookups. Name real symbols and give real values.
+   On a bug, write the corrected behavior as the outcome it produces, plus the cases that must
+   keep working — never "no longer broken".
+9. **Report separately** the type you wrote when you had to ask, the decisions you had to make,
+   code/design-doc discrepancies, the cause you found with its `file:line`, anything in a report
+   you could not confirm, anything added beyond scope, and any ordering constraint between issues.
+
+## Important
+
+- **Ask which type of issue it is** when the request does not make it clear. The wrong template
+  means the wrong sections and a rewrite.
+- **Outcomes only in the criteria.** No rationale, no technique notes, no cause or fix, no
+  negative parentheticals ("(not an `id`)"), no restating the event name, no "no X is needed", no
+  "Out of scope" or "Known limitations" lists. Keep negatives only when the negative is the
+  asserted outcome.
+- **The scope boundary lives in the criteria**, because that is what the PR is graded against — as
+  the outcome at the edge ("the cart and checkout pages render nothing"), never as a list of what
+  isn't built and never as a clause in the description.
+- **No links or paths to local design docs or specs** in any section you write — they don't
+  resolve on GitHub. Restate the constraint instead. External links are fine.
+- **Never reference a sibling by its design-doc position** ("issue 5", "the next issue") — that
+  numbering is not GitHub's. Use a real issue number, or the deliverable's name.
+- **An existing description is untouchable** unless the user explicitly asks — a Feature
+  Description, or a Bug Description with its Steps to reproduce.
+- **Don't publish.** No `gh issue create`, no `gh issue edit`, no comments, unless explicitly
+  asked. Produce the file and let the user place it.

.agents/workflows/write-implementation-brief.md

@@ -0,0 +1,39 @@
+---
+title: Write an implementation brief
+description: Write the Implementation Brief and Test Coverage sections of a Site Kit issue from its acceptance criteria, verified against the codebase.
+---
+
+# Write an implementation brief
+
+Run with `/write-implementation-brief <issue-number-or-path>` in the Agent chat.
+
+The full procedure is the shared, tool-agnostic playbook
+**`docs/context/workflow/write-implementation-brief.md`** (the single source of truth used by all
+of this project's AI tools). Follow it exactly. Summary of the steps:
+
+1. **Read the issue** — from GitHub when given a number
+   (`gh issue view <number> --json title,body,labels`), or from the path the user supplies for a
+   local issue file. Ask for one if you were given neither; never go looking for the file. The
+   Acceptance criteria are the contract — stop and ask if they are missing, ambiguous, or
+   contradictory.
+2. **Read the source material** — the design doc, plus the sibling issues that bound this issue's
+   scope and supply the numbers to cross-reference. Use the design doc the issue links or the
+   user gives you a path to; otherwise ask for it, bundling the question with the Step 1 ask.
+   Many issues have none — if there isn't one, say so and work from the acceptance criteria and
+   the code rather than stalling.
+3. **Verify against the code** — open every file the brief will touch and confirm each class,
+   method, hook, handle and path. Where the design doc and the code disagree, the code wins.
+4. **Load only** the relevant `docs/context/{js,php}` convention docs (use the map in
+   `implement-issue.md` Step 3).
+5. **Write the Implementation Brief** — grouped by path, one instruction per bullet. Name real
+   symbols, selectors, components, class names and user-facing strings; point at an existing
+   exemplar rather than describing one; cross-reference sibling issues inline; fence the scope
+   in one line. No rationale, no unneeded work, no routine commands, no local design-doc links.
+6. **Write the Test Coverage** — short. One bullet per test file or area, cases nested and
+   phrased as behaviors, negative cases included, Storybook stories listed here (not in the
+   brief), plus any existing tests the change will break.
+7. **Report separately** the discrepancies, unanticipated consequences, and assumptions that did
+   not belong in the brief.
+
+**Two sections only** — leave Feature Description, Acceptance criteria, QA Brief and Changelog
+entry untouched, and do not edit the GitHub issue or post a comment unless explicitly asked.

.agents/workflows/write-issue.md

@@ -0,0 +1,80 @@
+---
+title: Write an issue
+description: Write the description and Acceptance criteria of a Site Kit issue — a feature request or a bug report — from a design doc, a bug report or requirements, verified against the codebase.
+---
+
+# Write an issue
+
+Run with `/write-issue <design-doc-path | issue-number | bug report | requirements>` in the Agent
+chat.
+
+The full procedure is the shared, tool-agnostic playbook
+**`docs/context/workflow/write-issue.md`** (the single source of truth used by all of this
+project's AI tools). Follow it exactly. Summary of the steps:
+
+1. **Establish the issue type**, which decides the template and the sections you write. A
+   **feature request** (`.github/ISSUE_TEMPLATE/feature_request.md`) gets the **Feature
+   Description** and the **Acceptance criteria**; a **bug report**
+   (`.github/ISSUE_TEMPLATE/bug_report.md`) gets the **Bug Description**, the **Steps to
+   reproduce** and the **Acceptance criteria**. **Ask the user which type they want whenever their
+   message does not make it clear**, and wait for the answer before writing anything — say how you
+   read the request when you ask. An existing issue keeps the type it already has; never convert
+   one into the other. A request to change behavior that works as designed is a feature request,
+   even when the user calls it a fix.
+2. **Establish the source and the mode** — a design doc, a bug report or requirements in the
+   user's message, or an existing issue (`gh issue view <number> --json title,body`, or a path the
+   user supplies). A **new** issue gets the description sections and the criteria; an **existing**
+   issue whose description is already written gets **only** the Acceptance criteria, with the
+   description left byte-for-byte alone. Ask when nothing was given, the requirements are
+   ambiguous, or a design doc covers an epic without saying which issue to write. A design doc's
+   work-estimate table *is* the breakdown — one issue per row; do not re-slice it.
+3. **Read the source material end to end** — the whole design doc, not just this issue's section;
+   any spec the design doc names as authoritative; the sibling issues already written for the
+   epic, which show where this issue's scope stops; and, for a bug, the whole report as the user
+   gave it plus whatever evidence it names — a support thread, a linked issue, the pull request
+   the user says introduced the problem.
+4. **Verify against the code** — every class, method, hook, constant, handle and path; the shape
+   of the base class or registry being extended; and who consumes the data the issue changes,
+   which is what makes a "must stay unchanged" criterion real. For a bug, confirm that the wrong
+   behavior is really what the code does today, find the lines that produce it, and check which
+   cases served by the same code still work. Where the design doc and the code disagree, the code
+   wins.
+5. **Lay the issue out** by copying the template file for the type. Drop its YAML frontmatter and
+   put the title in its place as a single `# ` heading; everything else stays as the file has it —
+   moderator notice intact, the template's own placeholder comments left in the sections you are
+   not writing (the two templates word them differently, so copy from the right file), and on a
+   bug report Screenshots and
+   Additional Context left as the template gives them, filled in only with environment facts the
+   user actually stated. The title names the deliverable, or for a bug the symptom and where it
+   happens, and nothing sits between it and the first description heading — no epic name, no point
+   estimate, no dependency line. Where the issue depends on another, that dependency is a clause
+   inside the description, by real GitHub issue number.
+6. **Write the description** — prose only, and the only place rationale belongs. A **Feature
+   Description**: the gap today and where it falls short, what this issue adds, the halves of the
+   work as bold run-in headings, and the load-bearing decisions with their reasons. A **Bug
+   Description**: the wrong behavior on the real surface with its values, what should happen
+   instead, and the conditions it needs — plus the cause in one clause, only when you verified it
+   in the code, and never the fix. **Steps to reproduce**: a numbered list that starts from a
+   state the tester can reach, one action per step with the real values to click or paste, ending
+   in what the tester sees and what they should have seen.
+7. **Write the Acceptance criteria** — a flat `*` list, one checkable outcome per bullet, nested
+   one level for enumerable cases, tables inlined for lookups. Name real symbols, give real
+   values, state cardinality, and say what must stay unchanged. On a bug, write the corrected
+   behavior as the outcome it produces ("the tile shows the audience's 412 users"), never "no
+   longer broken", and add the cases that must keep working. The criteria are also where the
+   **scope boundary** lives, since they are what the PR is graded against — as the outcome at the
+   edge ("the cart and checkout pages render nothing"), never as an "Out of scope" list and never
+   as a clause in the description. Cut rationale, technique notes, the cause and the fix, negative
+   parentheticals, restated event names, and work that isn't being done.
+8. **Report separately** the type you wrote when you had to ask, the decisions you had to make,
+   discrepancies against the code with `file:line`, the cause you found for a bug, anything in the
+   report you could not confirm, anything added beyond the design doc's scope, and any ordering
+   constraint between the issues.
+
+**No local design-doc paths or links, and no sibling references by design-doc position** ("issue
+5", "the next issue") — that numbering is not GitHub's. Use a real issue number or the
+deliverable's name.
+
+**The authoring sections only** — leave Implementation Brief, Test Coverage, QA Brief and
+Changelog entry as placeholder comments, and do not create or edit a GitHub issue unless
+explicitly asked.

.claude/settings.json

@@ -0,0 +1,7 @@
+{
+	"enabledPlugins": {
+		"figma@claude-plugins-official": true,
+		"playwright@claude-plugins-official": true,
+		"chrome-devtools-mcp@claude-plugins-official": true
+	}
+}

.claude/skills/write-implementation-brief/SKILL.md

@@ -0,0 +1 @@
+../../../.agents/skills/write-implementation-brief/SKILL.md

.claude/skills/write-issue/SKILL.md

@@ -0,0 +1 @@
+../../../.agents/skills/write-issue/SKILL.md