diff --git a/claude-plugins/plugins/base/skills/forge-issue-filing/SKILL.md b/claude-plugins/plugins/base/skills/forge-issue-filing/SKILL.md deleted file mode 100644 index deef37d5..00000000 --- a/claude-plugins/plugins/base/skills/forge-issue-filing/SKILL.md +++ /dev/null @@ -1,119 +0,0 @@ ---- -name: forge-issue-filing -description: How to file a well-formed forge issue through the hive-forge CLI - check for an existing duplicate first (title-only grepping misses it, use server-side --search), pick a title that states the problem not the symptom, write a body that's the *problem*, and put any proposed fix in a follow-up comment rather than the issue description. Use this whenever you're about to run `hive-forge issue-create`, whenever you hit a bug/gap/usability problem and are about to file it rather than silently work around it, or whenever asked to write up a finding as an issue. ---- - -# Forge Issue Filing - -Filing an issue is cheap to do badly and expensive to do badly at scale - a -vague title makes it unsearchable later, a missing dedup check produces a -duplicate someone else has to notice and close, and a description that -mixes "what's wrong" with "here's my fix" forces every reader to -untangle the two. None of this needs much extra effort, just doing the -steps in the right order. - -## 1. Check for a duplicate before filing - -`hive-forge list` has a server-side full-text `--search` flag that covers -title *and* body - use it before writing anything: - -```sh -hive-forge list --search "keyword or two" --state all -``` - -Grepping `list`'s plain output only ever sees titles, so an existing issue -whose title doesn't happen to share your wording is invisible to that -approach even though its body describes the same problem - which is the -common case, not the exception, since you and whoever filed it first -almost never land on the same phrasing independently. Try a couple of -different keyword combinations (the symptom, the affected -component/verb) before concluding nothing exists; one search with the -wrong words is not evidence of absence. If you land on a candidate, -skim its body and comments before deciding it's actually the same -problem - a superficially similar title can be a different issue. - -If you're filing something adjacent to work already grouped into a -milestone, `--milestone ` composes with `--search` and narrows the -search to that scope. - -## 2. Title: the problem, not the symptom-of-the-moment - -A good title is something a future full-text search would actually match. -Prefer naming the broken behavior or missing capability over a specific -error string or one-off symptom - "hive-forge list has no way to filter by -milestone" beats "list command confusing" or "can't find issues for -milestone 11 easily". If you're not sure which framing is more durable, -lean toward whatever a colleague hitting the *same underlying gap* through -a *different* symptom would still recognize. - -## 3. Body: what's wrong, not how to fix it - -The issue description should state the problem clearly enough that -someone unfamiliar with it understands what's broken/missing and, ideally, -how to reproduce it or where it bites. It is **not** the place for your -proposed implementation - post that as a **follow-up comment**, not baked -into the description: - -```sh -hive-forge issue-create --title "..." --body "..." --label ... --assignee ... -hive-forge comment --body "proposed fix: ..." -``` - -Why the split matters: the description is what search and future readers -land on first, and it should stay stable - "what's the problem" doesn't -change as a design evolves. A proposal is a specific point-in-time idea -that gets discussed, revised, or replaced entirely; if it's baked into the -description, either the description goes stale the moment the proposal -changes, or someone has to edit it to keep it current and lose the -history of how the thinking evolved. A comment thread naturally -preserves that evolution - the description doesn't need to. - -If you already know roughly what the fix should look like, it's fine (good, -even) to say so in a comment right after filing - just keep it visibly -separate from the problem statement. - -## 4. Labels: check the taxonomy, don't guess - -Label names are repo-specific and an unresolved name in `issue-create ---label` errors out before the issue is even created (better than the -alternative, but still wasted effort if you guess wrong). If you don't -already know the repo's label scopes, list them first: - -```sh -hive-forge repo-labels -``` - -Attach whatever scope labels the repo actually uses (commonly a `type/*` -and an `area/*`, but check - taxonomies differ per repo) when you -already know them - it saves a round trip. But don't stress over an -unlabeled issue: labeling what's already filed is what triage coverage -(`hive-forge lint unlabeled --scope `, and whatever agent/process -this hive runs to sweep it) exists for. Guessing at a label you're not -sure of just to avoid leaving it blank can do more harm than leaving it -for triage to get right. - -## 5. Assignee: leave it to triage unless you know who owns it - -Don't self-assign by default just because you filed it - filing and owning -are different things, and an issue you noticed isn't necessarily yours to -fix. Set `--assignee` only when you already know who should pick it up -(yourself included, if you're about to start on it immediately) or when -the hive's own triage convention says otherwise. When in doubt, leave it -unassigned and let it surface through the normal triage sweep (see the -**`forge-triage`** skill). - -## Putting it together - -```sh -hive-forge list --search "thing you think is broken" --state all # 1: dedup -hive-forge repo-labels # 4: taxonomy -hive-forge issue-create \ - --title "the problem, stated durably" \ - --body "what's wrong, how to reproduce, where it bites" \ - --label area/whatever --label type/bug -hive-forge comment --body "proposed fix, if you have one" # 3: comment, not description -``` - -This is the filing mechanics only - the **`forge-workflow`** skill covers -the surrounding etiquette (never call the forge API directly, `@name` -subscribes, read before you comment) and applies just as much here.