skills: add forge-issue-filing skill

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 <name>` 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 <number> --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 <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 <number> --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.