@groupby/ai-dev 0.4.2 → 0.5.1

package/teams/snpd/skills/draft-pr/SKILL.md

@@ -0,0 +1,252 @@
+---
+name: draft-pr
+description: Use when the user invokes `/draft-pr` (or asks to "draft a PR", "open a draft PR", "create a draft pull request"). Pushes the current branch and opens a DRAFT pull request on GitHub. Uses `.github/PULL_REQUEST_TEMPLATE.md` if present (creating one only with explicit user approval). Fills the description from the corresponding plan file (preferred) or commit history (fallback). Leaves all template checkboxes unchecked. Never marks the PR ready, never assigns reviewers, never opens follow-up tickets. Only runs when explicitly invoked — do NOT auto-trigger on the word "PR".
+---
+
+# draft-pr
+
+Push the current branch and open a **draft** pull request on GitHub.
+
+## Prerequisite
+
+- `gh` CLI installed and authenticated (`gh auth status` succeeds).
+- The repo's remote points at GitHub (`git remote -v` shows github.com).
+- The current branch is **not** the default branch and has commits ahead
+  of it.
+
+If any of these fails, stop with a specific actionable message.
+
+## Workflow
+
+### 1. Pre-flight
+
+1. Detect the default branch (same logic as `/tdd-implement`):
+   - `git symbolic-ref --short refs/remotes/origin/HEAD` → strip
+     `origin/` prefix.
+   - Fallback: `git config init.defaultBranch`.
+   - Fallback: ask the user.
+2. Confirm the current branch is not the default. If it is, stop.
+3. Run `git status` — working tree must be clean. If not, ask the user
+   how to proceed (commit / stash / abort).
+4. Confirm the branch has commits ahead of the default
+   (`git rev-list --count {default}..HEAD > 0`). If zero, stop — nothing
+   to PR.
+5. Check whether a PR already exists for this branch:
+
+   ```bash
+   gh pr view --json url,state,isDraft,title --jq '.'
+   ```
+
+   - If a PR exists, **do not create a duplicate.** Show its URL and
+     ask:
+     > *"PR already exists at `<url>` (state: `<state>`, draft:
+     > `<isDraft>`). Update its description, or skip and exit?"*
+   - On `update`: jump to step 4 (gather content) and then use
+     `gh pr edit --body-file <tmpfile>` instead of `gh pr create`.
+   - On `skip`: stop.
+
+### 2. Resolve the PR template
+
+Look for `.github/PULL_REQUEST_TEMPLATE.md` (also accept
+`PULL_REQUEST_TEMPLATE.md` at the repo root, and
+`.github/pull_request_template.md` lowercase).
+
+Three cases:
+
+**A. Template exists and uses a recognizable shape** (contains headings
+like `## Summary`, `## Description`, `## Test plan`, or a list of
+`- [ ]` checkboxes):
+
+- Use it as-is.
+- Identify the description / summary section and the checklist section.
+
+**B. Template exists but is custom / unfamiliar** (no recognizable
+section headings):
+
+- Use it verbatim.
+- Insert the generated content **at the very top** above the existing
+  template content, separated by `---`.
+- Do not modify the template body.
+
+**C. Template missing entirely:**
+
+- Stop and ask the user:
+  > *"No `.github/PULL_REQUEST_TEMPLATE.md` found. Creating one is a
+  > repo-wide commit affecting all future PRs. Create a default
+  > template now, or proceed without one (description-only PR)?"*
+- On `create`: write the default template (see below) and commit it
+  to the current branch with message `{KEY}: add PR template` (using
+  the ticket key derived in step 3 if available; otherwise prompt the
+  user for a message). Then continue.
+- On `proceed without`: skip template handling and use a plain
+  description.
+
+### 3. Derive ticket key, title, and content sources
+
+- **Ticket key:** parse from the most recent commit message
+  (`{KEY}: ...` prefix per repo convention). Fallback: parse from the
+  current branch name (`{KEY}-...`). If none found, prompt the user.
+- **Title:** use the first line of the squashed/most-recent commit
+  message verbatim (typically `{KEY}: <headline>`).
+- **Content sources, in priority order:**
+  1. Plan file at `.claude/artifacts/{KEY}_*-plan.md`. If present, pull
+     `## Implementation Details` and `## Post-Mortem` sections. Also
+     pull `## Goal` and `## Out of scope` if present.
+  2. Spec file at `.claude/artifacts/{KEY}_*-spec.md` for Acceptance
+     Criteria.
+  3. Squashed commit body (`git log -1 --pretty=%B`).
+  4. `git log {default}..HEAD --oneline` as a last resort.
+
+Note which sources were used; mention them in your final report so the
+user can audit.
+
+### 4. Compose the PR body
+
+Fill the template (or build a description if no template). Map content
+into sections that exist in the template:
+
+- **Summary / Description** — Plan's "Goal" + "Implementation Details"
+  summary (2–4 sentences).
+- **Acceptance Criteria** — Verbatim from spec, as unchecked `- [ ]` items.
+- **Test plan / How to test** — High-level test surface from plan's "Test
+  strategy" + final verification command output.
+- **Notes / Other** — Plan's "Post-Mortem" section if present.
+- **Out of scope** — Plan's "Out of scope" section.
+
+Rules for the body:
+
+- **Every `- [ ]` from the template is preserved unchecked.** No
+  exceptions, even when the corresponding work is done.
+- **No fabrication.** If the plan doesn't mention something, don't
+  invent it for the description.
+- **No new acceptance criteria.** Acceptance criteria come from the
+  spec or already-present template lines, never from the agent.
+- **No screenshots, no benchmark numbers** unless the user provided
+  them in the conversation.
+- **Keep it skimmable** — a reviewer should grasp the change in 30
+  seconds.
+
+### 5. Show the proposed PR for review
+
+Before any push or PR creation, present in chat:
+
+```markdown
+# Draft PR preview
+
+**Repo:** <owner>/<repo>
+**Base:** <default-branch>
+**Head:** <current-branch>
+**Title:** <title>
+**Draft:** yes
+
+---
+<full body, exactly as it will appear>
+---
+
+Content sources used: <list>
+```
+
+Ask:
+> *"Looks good? Reply `confirm` to push the branch and open the draft
+> PR, `edit` to revise the body, or `cancel` to stop."*
+
+### 6. Push, then create the PR (only on `confirm`)
+
+Two confirmations, sequentially:
+
+1. **Push:**
+   - `git push -u origin <current-branch>` (fast-forward only — no flags).
+   - If the push is rejected as non-fast-forward (the branch has a
+     remote with diverged history, typically because a squash rewrote
+     local history), **stop**. Do not retry with `--force` or
+     `--force-with-lease`. Print:
+     > *"Push rejected — remote `<branch>` has commits not in local
+     > history. This usually means the branch was previously pushed
+     > and then squashed locally. Force-push is a destructive operation
+     > and is not done by this skill. Resolve manually
+     > (`git push --force-with-lease` if you're sure, or rebase/merge
+     > the remote first), then re-run `/draft-pr`."*
+   - Show the push output on success.
+2. **Create:**
+   - `gh pr create --draft --title "<title>" --body-file <tmpfile> --base <default>`.
+   - Capture the URL.
+
+If `update` path was taken in step 1, replace step 6.2 with
+`gh pr edit <number> --body-file <tmpfile>`.
+
+### 7. Stop
+
+Print exactly one closing line:
+
+> *"Draft PR ready at `<url>`. I have not marked it ready, assigned
+> reviewers, or opened follow-up issues — those are your call."*
+
+Do **not**:
+
+- Run `gh pr ready` to take the PR out of draft.
+- Add labels, assignees, reviewers, or milestones.
+- Comment on the PR.
+- Run CI manually.
+- Create related issues.
+- Start the next ticket.
+
+## Default PR template (used only when user approves creating one)
+
+```markdown
+## Summary
+
+<one-paragraph description of the change>
+
+## Acceptance criteria
+
+- [ ] <criterion>
+- [ ] <criterion>
+
+## Test plan
+
+- [ ] <how to verify>
+- [ ] <how to verify>
+
+## Notes
+
+<anything reviewers should know — risks, follow-ups, context>
+```
+
+## Hard rules
+
+- **Always `--draft`.** Never `gh pr ready`. Never `--no-draft`.
+- **Never push or create without explicit `confirm`.** Two distinct
+  user-visible side effects; preview must come first.
+- **Never assign reviewers, labels, or milestones.** `CODEOWNERS` and
+  policy automations handle those.
+- **Never check a `- [ ]` box from the template.** Even if the work is
+  obviously done. Reviewers tick boxes.
+- **Never overwrite an existing PR description without asking.** If a
+  PR exists for the branch, the `update` path requires explicit user
+  approval.
+- **Never overwrite an existing custom PR template.** If the template
+  doesn't match a known shape, append/prepend; do not rewrite.
+- **Never commit a new PR template silently.** Creating
+  `.github/PULL_REQUEST_TEMPLATE.md` is a repo-wide change and needs
+  explicit user approval.
+- **Never invent acceptance criteria, test results, or screenshots.**
+- **Never force-push.** Not with `--force`, not with
+  `--force-with-lease`. If a normal push fails as non-fast-forward,
+  stop and surface the situation — the user resolves it manually.
+
+## Common mistakes
+
+- Pushing before showing the PR preview.
+- Checking template boxes because "the tests do pass".
+- Rewriting a custom PR template because it didn't match the expected
+  format. Custom is fine — append, don't rewrite.
+- Creating a duplicate PR when one already exists for the branch.
+- Marking the PR ready, even after the user says "looks great" — only
+  the user takes it out of draft.
+- Assigning reviewers based on guess.
+- Including the full plan or spec verbatim in the body. The body is a
+  summary; the plan is in the repo at `.claude/artifacts/`.
+- Opening follow-up issues for post-mortem suggestions. Those are user
+  actions.
+- Retrying a rejected push with `--force-with-lease` because "it's
+  probably fine". Force-push is the user's call, not the skill's.

package/teams/snpd/skills/jira-spec/SKILL.md

@@ -0,0 +1,216 @@
+---
+name: jira-spec
+description: Fetch a Jira ticket and write a development spec to ./.claude/artifacts/ in the current repo (alongside other work artifacts — plans, notes, design docs). Only run when the user explicitly invokes this command via /jira-spec — do NOT auto-trigger on Jira keys, ticket links, or the word "spec".
+---
+
+# Jira Spec
+
+## ⚠️ Prerequisite: Jira access
+
+This skill **cannot run without working Jira access**. The very first thing
+it does is fetch the ticket — if that fails, the skill stops. Most failures
+happen here. Before running, verify at least ONE of these works:
+
+- **Atlassian MCP** is configured (preferred): tools named
+  `mcp__atlassian__getAccessibleAtlassianResources` and
+  `mcp__atlassian__getJiraIssue` are available in the current session.
+- **go-jira CLI** is installed and authenticated: `jira issue view <KEY>`
+  returns the ticket.
+- **`curl` + stored credentials**: `${JIRA_BASE_URL}` is set and a
+  credential (`JIRA_TOKEN` or `.netrc` entry) authorizes
+  `${JIRA_BASE_URL}/rest/api/3/issue/<KEY>`.
+
+If none of these is in place, the skill will refuse to proceed.
+**Never fabricate ticket content** — the value of the spec is the verbatim
+audit record from Jira.
+
+## Overview
+
+Given a Jira ticket reference (key like `S4R-1234` or a browse URL), fetch the
+ticket from Jira and produce a markdown spec at
+`./.claude/artifacts/{KEY}_{kebab-title}.md` in the current repo. The spec
+preserves the original ticket verbatim (for audit) and adds AI-gathered repo
+context so a future session can start implementation immediately.
+
+## When to Use
+
+Trigger on inputs like:
+
+- A Jira key alone: `S4R-1234`, `SRE-7348`, `AIP-123`
+- A Jira URL: `https://*.atlassian.net/browse/S4R-1234`
+- Requests like "draft a spec for S4R-1234", "prep this ticket", "create
+  ticket doc for <link>"
+
+Do NOT use for: generic note-taking, non-Jira tickets (GitHub issues, Linear),
+or when the user already has a spec file and just wants to edit it.
+
+## Workflow
+
+1. **Parse the input** to extract the ticket key (uppercase letters, hyphen,
+   digits — e.g. `S4R-1234`). Accept both bare keys and `…/browse/KEY` URLs.
+
+2. **Fetch the ticket from Jira (the most common failure point — see
+   Prerequisite above).** Try in this order:
+   - **Atlassian MCP** (preferred when available): call
+     `mcp__atlassian__getAccessibleAtlassianResources` to obtain a `cloudId`,
+     then `mcp__atlassian__getJiraIssue` with that `cloudId` and the ticket
+     key. Also fetch comments if the description references them.
+   - **CLI fallback**: `jira issue view KEY` (go-jira) or a `curl` against
+     `${JIRA_BASE_URL}/rest/api/3/issue/KEY` using stored credentials.
+   - **If none of these works, STOP.** Print which mechanism was tried, the
+     error, and what the user needs to configure (e.g. "install go-jira and
+     run `jira init`", or "enable the Atlassian MCP in this client"). Do
+     NOT proceed to the repo scan. Do NOT invent ticket content.
+
+3. **Investigate the repo (medium depth).** Based on the ticket
+   summary/description:
+   - Identify the most relevant files/modules (use Grep/Glob, check
+     `CLAUDE.md`, look at recent commits touching the area).
+   - Read the key files end-to-end where useful; skim larger ones.
+   - Note conventions, patterns, and any nearby code the change will touch.
+   - Keep this targeted — don't tour the whole codebase.
+
+4. **Determine the output path.**
+   - Directory: `./.claude/artifacts/` in the current working repo (create
+     if missing). Never write to `~/.claude/artifacts/`.
+   - Filename: `{KEY}_{short-slug}-spec.md`. The `-spec` suffix is
+     **mandatory** — it identifies the doc as this command's artifact and
+     keeps it distinct from sibling docs (`-plan`, `-design`, `-requirements`,
+     `-testing-results`, etc.). You — the agent — choose the `{short-slug}`
+     part. See "Slug Rules" below.
+   - If the file already exists, ask the user before overwriting.
+
+5. **Write the spec** using the template below.
+
+6. **Report** the absolute path of the file you wrote and a one-line summary.
+   Do not start implementation unless the user asks.
+
+## Spec Template
+
+```markdown
+# {KEY}: {Summary}
+
+- **Jira:** {browse URL}
+- **Status:** {status} · **Type:** {issuetype} · **Priority:** {priority}
+- **Assignee:** {assignee} · **Reporter:** {reporter}
+- **Labels:** {labels} · **Components:** {components}
+- **Parent / Epic:** {parent or epic link, if any}
+- **Fetched:** {YYYY-MM-DD}
+
+## Original Description (verbatim, for audit)
+
+> {Jira description, rendered to markdown. Preserve formatting, bullet lists,
+> code blocks, and links. Do not edit or paraphrase.}
+
+### Acceptance Criteria (verbatim)
+
+> {If present as a separate field or section, include verbatim. Omit the heading
+> if there is none — do not invent acceptance criteria.}
+
+### Relevant Comments (verbatim, optional)
+
+> {Include only comments that add load-bearing context — decisions, scope
+> changes, clarifications from the reporter. Skip chatter. Quote verbatim with
+> author and date. Omit the section entirely if nothing qualifies.}
+
+## Implementation Notes (AI-gathered)
+
+> ⚠️ The items below are AI guesses from a medium-depth repo scan. Verify
+> against the current code before relying on any specific file path, line
+> range, or claim — they may be stale, incomplete, or wrong.
+
+### Touch points in this repo
+- `path/to/file` — what lives here and why it matters for this ticket
+- `path/to/other:120-180` — specific region of interest
+
+### Patterns and conventions to follow
+- {e.g. "New search strategies extend SearchStrategy and register in SearchStrategyFactory"}
+- {Link to CLAUDE.md sections when relevant}
+
+### Suggested approach (sketch, not a plan)
+- {2–5 bullets outlining the most plausible shape of the change. Keep loose —
+>  the actual plan belongs in a separate planning step.}
+
+### Test surface
+- {Which test classes / component tests will need updates or additions}
+
+## Open Questions
+
+> Include this section **only** when at least one truly blocking question
+> exists — i.e. its answer would change the implementation and cannot be
+> resolved by reading the repo or the ticket. If there are no such questions,
+> omit this entire section (heading included). Don't print a placeholder.
+
+- [ ] {question, with the reason it blocks progress}
+```
+
+## Rules
+
+- **Verbatim means verbatim.** Do not summarize, "clean up", or translate the
+  Jira description. Quote it as-is in a blockquote so an auditor can compare
+  to Jira.
+- **One spec file per ticket.** Don't append to a different ticket's file.
+- **No invented metadata.** If a field is missing in Jira, omit it from the
+  spec rather than guessing.
+- **Minimize open questions.** Prefer to resolve uncertainty by reading the
+  code. Only escalate questions that are genuinely blocking.
+- **Don't start coding.** This skill produces the spec only. Implementation
+  comes later, in a fresh session that reads this file.
+
+## Slug Rules
+
+You — the agent — pick the slug. The goal: a short, recognizable handle, not a
+literal transliteration of the Jira summary. Aim for **3–6 words, ≤ 50
+characters**.
+
+Mechanics:
+
+- Lowercase. Replace any run of non-`[a-z0-9]` with a single `-`. Trim
+  leading/trailing `-`.
+- Strip a leading `KEY:` if the summary repeats the key.
+- Drop filler: `implement-the-`, `add-support-for-`, `feature-from-`,
+  `the-`, `a-`, `for-`, `from-`, `in-`, `of-`, etc.
+- Drop redundant qualifiers already implied by the repo (e.g. you don't
+  need `-mongo-` in the slug if every nearby ticket lives in a Mongo repo).
+- Keep the **distinctive core**: the noun/verb that names the change.
+  "Implement the does not affect feature from Mongo for Facet Exclusion"
+  → `does-not-affect` (not
+  `implement-the-does-not-affect-feature-from-mongo-for-facet-exclusion`).
+- If the ticket already has sibling docs in `.claude/artifacts/` with a slug
+  convention, follow that convention.
+
+Examples (the `-spec` suffix is appended after the slug, always):
+
+- Summary: `Implement the "does not affect" feature from Mongo for Facet
+  Exclusion`
+  - Good: `S4R-10226_does-not-affect-spec.md`
+  - Bad: `S4R-10226_implement-the-does-not-affect-feature-from-mongo...md`
+- Summary: `Add MongoDB command listener logging`
+  - Good: `S4R-10443_mongodb-command-listener-logging-spec.md`
+  - Bad: `S4R-10443_add-mongodb-command-listener-logging.md`
+- Summary: `S4R-10491: add support for LIST_VALUE
+  (VariantRollupValuesConverter)`
+  - Good: `S4R-10491_list-value-rollup-converter-spec.md`
+  - Bad: `S4R-10491_add-support-for-list-value-...converter.md`
+- Summary: `Fix: NPE in /search when filters empty`
+  - Good: `S4R-1234_npe-search-empty-filters-spec.md`
+  - Bad: `S4R-1234_fix-npe-in-search-when-filters-empty.md`
+- Summary: `Investigate latency spike on browse endpoint`
+  - Good: `S4R-1234_browse-latency-spike-spec.md`
+  - Bad: `S4R-1234_investigate-latency-spike-on-browse-endpoint.md`
+
+## Common Mistakes
+
+- Writing the spec without fetching Jira (hallucinating description).
+  **Never do this** — if Jira is unreachable, stop and report.
+- Saving to `~/.claude/artifacts/` instead of the repo's
+  `./.claude/artifacts/`.
+- Paraphrasing the description. The "Original Description" section must be
+  verbatim.
+- Padding "Open Questions" with nice-to-knows. Omit the section unless a
+  question is truly blocking.
+- Producing a long literal slug (e.g. `implement-the-X-feature-from-Y`).
+  Strip filler and aim for a 3–6 word distinctive handle.
+- Presenting AI-gathered touch points as ground truth. They are guesses —
+  keep the verify-before-relying banner above that section.
+- Doing deep design work here. This is a spec, not a plan — medium-depth repo investigation only.