---
name: forge-workflow
description: Enforces safe, low-noise habits when working with a git forge (issues, PRs, comments, reviews) through its CLI wrapper - never call the forge API directly, understand that an @-mention subscribes someone to the whole thread, retrigger CI without empty commits, verify a PR is actually mergeable before claiming it's ready, and never merge your own PR. Use this whenever you are about to comment on, review, or merge a PR/issue, or before telling someone a PR is ready.
---

# Forge Workflow

Working with a code forge (issues, PRs, reviews, CI) is mostly about not
generating noise and not skipping steps that look optional but aren't.

## Never call the forge API directly

If your environment provides a CLI wrapper for forge operations, use it for
every issue/PR/comment/label/review action instead of raw HTTP calls. The
wrapper is the one place auth, rate limits, and response shape are handled
correctly - going around it (e.g. hand-rolled requests) is how credentials
leak into logs and how you silently miss the wrapper's read-tracking or
retry behavior.

## `@name` subscribes, plain name doesn't

- Writing `@name` in a comment **notifies and subscribes that person to the
  whole thread** - every future comment on it pings them too. Only do this
  when you actually want them pulled in: asking them a direct question,
  requesting review, handing off the next action.
- Referring to someone in the **third person** - describing what they did,
  attributing work - use their plain name, no `@`. An unnecessary `@` trains
  people to skim-ignore mentions, which defeats the point of the ones that
  matter.

## Retrigger CI without noise commits

Never push an empty commit just to force a CI rerun - it pollutes history
and doesn't even help if the failure was a real code problem. Use your
forge tooling's dedicated rerun/re-dispatch verb instead. If CI is failing
for an infrastructure reason (runner down, flaky network) rather than a
code problem, say so and wait rather than spamming reruns.

## Verify before claiming "ready"

Before telling anyone a PR is ready to merge, actually check its
mergeability + CI state + review state through the tooling - don't infer
readiness from "I pushed and CI looked fine last I saw." State can change
after your last look (a new commit, a reviewer's request-changes, a rebase
conflict). A quick status check costs nothing and prevents a false "ready"
that wastes someone's time acting on it.

## Never self-merge

Merging is the reviewer's/operator's call, not the author's, regardless of
how confident you are in your own change. Push, open the PR, respond to
review - then wait. If you have merge access, using it on your own PR is
out of bounds even when it's "obviously fine."

## Read before you comment

If a thread has activity you haven't read yet, read it first. Commenting
over something you haven't seen risks repeating a question that was just
answered, missing new instructions, or talking past a correction. Many
forge tools enforce this by refusing to post to an unread thread - treat
that as a feature, not friction to route around.

If your environment ships its own hive-wide/repo-wide forge conventions
doc (commit style, review checklist, etc.), treat that as the canonical
source and this skill as a reminder to follow it - don't duplicate its
rationale into your own notes either.