From ef40b03c87d7d45975f9201a6f72eb5d95ff24fc Mon Sep 17 00:00:00 2001 From: damocles Date: Wed, 12 Aug 2026 21:56:00 +0200 Subject: [PATCH] skills: add forge-issue-filing skill --- .../base/skills/forge-issue-filing/SKILL.md | 116 ++++++++++++++++++ 1 file changed, 116 insertions(+) create mode 100644 claude-plugins/plugins/base/skills/forge-issue-filing/SKILL.md diff --git a/claude-plugins/plugins/base/skills/forge-issue-filing/SKILL.md b/claude-plugins/plugins/base/skills/forge-issue-filing/SKILL.md new file mode 100644 index 00000000..580a813e --- /dev/null +++ b/claude-plugins/plugins/base/skills/forge-issue-filing/SKILL.md @@ -0,0 +1,116 @@ +--- +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). Skipping labels +entirely is worse than a slightly-off guess: an unlabeled issue is what +`hive-forge lint unlabeled --scope ` exists to catch, so an +unlabeled issue you filed becomes someone else's triage cleanup. + +## 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.