5.8 KiB
| name | description |
|---|---|
| forge-issue-filing | 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:
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:
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:
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 <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
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.