diff --git a/skills/reporting-a-skill-gap/SKILL.md b/skills/reporting-a-skill-gap/SKILL.md index d1f41a8..a3490d7 100644 --- a/skills/reporting-a-skill-gap/SKILL.md +++ b/skills/reporting-a-skill-gap/SKILL.md @@ -27,7 +27,7 @@ The issue goes to the plugin's repository, never to the repository of the curren 1. Read `${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json`. Its `repository` field holds the URL of the plugin's repository. Take `OWNER/REPO` from it (`https://github.com/OWNER/REPO` gives `OWNER/REPO`). Its `version` field is the plugin version for the report. 2. If the file or the field is missing, ask the user for the repository. Do not take it from a README, a marketplace file, or the current remote. -3. Pass `--repo OWNER/REPO` on every `gh issue` command this skill runs, and name the repository in the path of every `gh api` call (`repos/OWNER/REPO/...`): `gh api` takes no `--repo`. +3. Pass `--repo OWNER/REPO` on every `gh issue` command this skill runs. `gh api` takes no `--repo`, so name the repository in the path of every REST call (`repos/OWNER/REPO/...`), and in the query of every GraphQL call (`repository(owner:"OWNER",name:"REPO")`). ## Step 2: locate the gap in the skill @@ -39,11 +39,19 @@ Open the installed skill, `${CLAUDE_PLUGIN_ROOT}/skills//SKILL.md`, and fi gh issue list --repo OWNER/REPO --state all --search " " --limit 20 ``` -Run a second search with other words if the first finds nothing. The list shows titles only, so open each plausible match with `gh issue view --repo OWNER/REPO --comments` before you pick a branch below. Then: +Run a second search with other words if the first finds nothing. The list shows titles only, so open each plausible match with `gh issue view --repo OWNER/REPO --comments` before you pick a branch below. That view shows a closed issue as `CLOSED` but not why it was closed, so for each closed match also run: + +``` +gh issue view --repo OWNER/REPO --json stateReason --jq .stateReason +``` + +It prints `COMPLETED`, `NOT_PLANNED`, or `DUPLICATE`. If it prints an empty line, GitHub recorded no reason: take it from the closing comment, and if the comment does not say, ask the user which branch applies. Then: - **An open issue covers the same gap:** comment on it instead of filing a new one. The comment adds your reproduction and evidence (see the template's comment form). If the issue already has a reproduction of the same case, tell the user and stop. -- **A closed issue covers it, fixed in a version newer than the installed one:** tell the user to update the plugin. File nothing. -- **A closed issue covers it and the installed version has the fix:** it is a regression. File a new issue and name the closed one in `## Evidence`. +- **A closed issue covers it, closed as `DUPLICATE`:** follow it to the issue it duplicates and pick the branch for that issue instead. Do not comment on the duplicate. Get the number with `gh api graphql -f query='query{repository(owner:"OWNER",name:"REPO"){issue(number:){duplicateOf{number}}}}' --jq '.data.repository.issue.duplicateOf.number'`. If it prints an empty line, take the number from the closing comment. +- **A closed issue covers it, closed as `NOT_PLANNED`:** the maintainers declined this gap. Tell the user, with the reason from the thread, and file nothing: no new issue, and no comment on the closed one. This holds under a standing grant too, because a grant lets a report land without a prompt and does not decide whether one is due. A reproduction that the closed issue lacks is not a difference. File a new issue only when your case differs from the closed one in a way the maintainers' reason does not cover, such as another section or another failure. The new issue names the closed one and the difference in `## Evidence`. +- **A closed issue covers it, closed as `COMPLETED` and fixed in a version newer than the installed one:** tell the user to update the plugin. File nothing. +- **A closed issue covers it, closed as `COMPLETED`, and the installed version has the fix:** it is a regression. File a new issue and name the closed one in `## Evidence`. - **No match:** file a new issue. ## Step 4: draft the body from the template @@ -91,4 +99,5 @@ Do not edit the installed copy of the skill under `${CLAUDE_PLUGIN_ROOT}`: the p | "I'll mention the project so they see it was a real case" | The repository is public. The generic shape is the real case; the names add only risk. | | "It's only a test key, I'll mask it" | Leave it out. A masked key still tells a reader what kind of secret leaked and where. | | "This is probably new, I'll skip the search" | A second issue splits the thread. Search first; a reproduction is worth more on the existing issue. | +| "It was closed as not planned, but it had no reproduction, and the user asked me to report" | The maintainers declined the gap, not the report's form. Tell the user and file nothing. A new issue needs a difference that their reason does not cover. | | "I'll fix the installed skill file so it works now" | The cache is overwritten on update, and the fix needs the maintainer's RED baseline. Report it and keep the hand-added instruction in your prompts. |