AGENT SKILL

address-issue

End-to-end playbook for working a GitHub issue (or bug-fix PR) on nubjs/nub: triage → acknowledge an external report with an "Investigating" comment → reproduce it yourself → SIZE it → fix it at that size (most issues are a small fix you just write — no investigation spike, no sub-agent fleet, no top-tier model) → open a PR that references the issue with `Closes #N` → on merge, comment the resolution → on release, comment the version + release link. Invoke (via the Skill tool) whenever you pick up an issue to work, or are asked to fix a reported bug. Encodes both the maintainer-hygiene conventions in AGENTS.md (so the reporter is acknowledged, the issue auto-closes on merge, and the loop closes when the fix ships) and the proportionality gate that keeps an ordinary bug from being worked like an audit.

License 许可
MIT
所属仓库
nubjs/nub
最近更新
2026-11-14
Stars
★ 4.4k
Forks
71

01 前言 Front Matter

name
address-issue
metadata
{ "internal": true }
description
End-to-end playbook for working a GitHub issue (or bug-fix PR) on nubjs/nub: triage → acknowledge an external report with an "Investigating" comment → reproduce it yourself → SIZE it → fix it at that size (most issues are a small fix you just write — no investigation spike, no sub-agent fleet, no top-tier model) → open a PR that references the issue with `Closes #N` → on merge, comment the resolution → on release, comment the version + release link. Invoke (via the Skill tool) whenever you pick up an issue to work, or are asked to fix a reported bug. Encodes both the maintainer-hygiene conventions in AGENTS.md (so the reporter is acknowledged, the issue auto-closes on merge, and the loop closes when the fix ships) and the proportionality gate that keeps an ordinary bug from being worked like an audit.

03 SKILL.md 正文

Addressing a nub issue end-to-end

Taking a GitHub issue from "reported" to "shipped and the reporter told." The hygiene rules here are mandatory, not courtesies — maintainer responsiveness on a public repo is a visible health signal.

On the maintainer's Mac, every gh below that writes (comment, close, pr create, pr edit) runs as keyward --reason "<the task>" -- gh …. Reads stay plain gh.

Guardrails

  • Tone is factual, neutral, professional — never braggy, competitive, or over-promising. Invoke the prose-writing skill.
  • A fix lands via the PR-from-a-worktree flow, not directly on the shared main tree. Trivial doc/typo fixes are the documented exception.
  • Verify end-to-end before pushing — run the pre-push local-verification loop. A green suite with a stubbed fix is worse than an unchecked one.
  • Don't autonomously land a change to a default / security posture / product behavior / API-config-env surface. Those are recommend-only until the maintainer signs off. A mechanical, clearly-a-bug fix may land; a behavior decision routes back as a question.
  • Work the issue at its ACTUAL size — the default is that you just fix it yourself. Most issues are one clear cause and a small diff. Reaching for an investigation spike or a sub-agent fleet by reflex is the most common way this playbook is run wrong.

Step 1 — Triage: read the issue, the comments, and reproduce

gh issue view <n> --repo nubjs/nub --comments
  • Read the COMMENTS and the resolution history, not just the body. The body says what someone wanted; the thread says what's true. A "feature request" can be a deliberate prior rejection; a "bug" can already be fixed on main.
  • Classify it. Genuine bug, usage question, feature request, duplicate, or already-fixed? Mechanical fix (land it) or a maintainer-owned surface (propose, get sign-off)?
  • Reproduce empirically before reading source or deciding. Build a minimal differential fixture — the behavior under nub vs the reference tool it claims parity with — in a throwaway /tmp dir. A divergence IS the finding.
  • Do the reproduction YOURSELF. It is a fixture and a couple of commands; a second-hand repro is a lead you then have to re-verify anyway.

Step 1b — Size it, and let the size pick the machinery

Default to the top row and move down only on evidence — a cause you traced that turns out to be cross-cutting, a fix that touches a maintainer-owned surface. The issue's tone, label, or alarming title are not evidence.

Class What it looks like How you work it
Answer it usage question, duplicate, already fixed on main, working-as-intended, a docs or typo fix Reply and close (Step 6). No worktree, no sub-agent.
Small fix — the common case one clear cause; a few lines across one or two files; no design call Fix it yourself in a worktree. No sub-agent. Your own read of the diff plus the pre-push loop IS the review.
Real change several files, or logic whose knock-on effects you can't hold in your head, or a new test harness Do it yourself or hand it to ONE implementation agent. Add ONE reviewer over the diff if the logic isn't self-evident.
Big a default / security posture / public surface, the resolver / lockfile / registry / CAS, cross-platform behavior, or a genuine multi-prong audit The full shape earns its keep: an owning agent, a multi-lens review split by dimension, top-tier models.

Three or four Opus-high sub-agents on a small fix is a defect in how you ran the playbook, not thoroughness. If you are about to dispatch, name which row you're in and what you found that puts you there — if you can't, you're in "Small fix" and you should just fix it.

The escalation mandates elsewhere in the repo — the fan-out rule and multi-lens self-review in AGENTS.local.md, the L1/L2 shape in implementation-thread — describe the Big row. They are not a floor under every issue.

Step 2 — Acknowledge an external report immediately

For an EXTERNAL reporter (not a maintainer, not self-filed), post the acknowledgement the moment you start work. It is exactly one word:

gh issue comment <n> --repo nubjs/nub --body "Investigating."

No "thanks for the report," no timeline, no preview of your hypothesis — a longer ack leaks half-formed theories and reads as noise. Internal/self-filed issues don't need this.

Every substantive comment is terse + factual per the prose-writing skill. State what you found and what you did, in the fewest words that carry the facts. Never write "previous comments were wrong" or similar meta-commentary — prior comments are often a bot's. The gh-comment-guard PreToolUse hook blocks an over-long gh issue/pr comment / gh pr create body; trim it, or set NUB_ALLOW_LONG_COMMENT=1 only for a genuinely-needed longer body.

If triage shows it's not a bug, say so factually with the reason and close it per Step 6.

Step 3 — Fix it, at the size you sized it

  • Small fix (most issues): write it. The pre-push loop is the verification; your own read of your diff is the review. Don't dispatch anything.
  • Real change: one implementation agent, or yourself. One reviewer if the logic isn't self-evident.
  • Big: the orchestration methodology earns its keep (load the orchestrator skill by name) — you hold the goal set, dispatch model-tiered sub-agents, and the fix gets a multi-lens self-review scaled to blast radius.

Tier every agent you do dispatch by the judgment its task needs. A repro, a harvest, a doc update, or a CI watch is Sonnet or Haiku work; Opus is for the fix that lands.

Work in an isolated worktree off origin/main:

git worktree add /tmp/nub-fix-<n> -b fix-issue-<n> origin/main   # vendor/aube comes along (plain in-tree files)
cd /tmp/nub-fix-<n>
# Build through the wrapper; never export CARGO_TARGET_DIR yourself — that opts
# out of the CoW seeding that starts an isolated worktree warm (~14s) instead of
# cold (~40 min).
scripts/rust-build.sh build -p nub-cli --profile fast

Before pushing, run the pre-push local-verification loop: incremental build → the exact CI gates (NUB_ALLOW_INCOMPLETE_RUNTIME=1 cargo clippy --all-targets --all-features -- -D warnings, cargo fmt --check, scoped cargo test) → an e2e tmp-fixture run of the specific behavior → Docker for anything touching the global cache/config → promote a regression test for this bug into the suite. Get it green locally and push ONCE.

Step 3b — Update docs if the fix changes user-facing behavior

If a user observes the change — a flag's effect, a default, an error message, a formerly-broken feature that now works — update site/content/docs/ in the same PR. The fix is not done until docs reflect it.

Step 4 — Open the PR, referencing the issue

The body MUST reference the issue: a closing keyword for a bug the PR resolves, Refs #N for related-but-not-resolving.

git push -u origin fix-issue-<n>
gh pr create --repo nubjs/nub \
  --title "<concise factual title>" \
  --body "$(cat <<'EOF'
<What the bug was and what the fix does, factually.>

Closes #<n>

<Verification: the fixture/command you ran and its result.>

https://claude.ai/code/session_<id>
EOF
)"

Report the PR URL. Do NOT merge your own PR.

PR CI is opt-in, so opening the pull request starts nothing. When the head is final, request the run and watch it:

gh pr edit <n> --add-label ci
nub scripts/ci-watch.ts --pr <n> --required "CI gate" --timeout 90

Step 5 — On merge, comment the resolution

Closes #N auto-closes the issue silently, so add a brief factual comment. Extremely concise — don't re-explain what was done or the process of doing it; the PR carries that. Thank an external reporter:

gh issue comment <n> --repo nubjs/nub --body "Fixed in #<pr>, ships in the next release. Thanks for the report."

(Drop the thanks on an internal/self-filed issue.) If it did NOT auto-close (no closing keyword, or a non-fix resolution), close it explicitly with a comment — never silently:

gh issue close <n> --repo nubjs/nub --comment "<one line: what resolved it, or why no code fix is needed>"

Step 6 — On release, comment the version + release link (mandatory)

A fix merged is not a fix shipped. Keep it to the version + link; on an external contributor's PR, add a brief thanks:

REL="https://github.com/nubjs/nub/releases/tag/v<ver>"
gh issue comment <n> --repo nubjs/nub --body "Shipped in v<ver>: $REL"
gh pr comment   <pr> --repo nubjs/nub --body "Shipped in v<ver>: $REL — thanks for the contribution."

In practice the release skill's Step 5 executes this in bulk across the whole changeset; this documents the contract for a single issue.


Quick reference

Step Action
Triage gh issue view <n> --comments · read the thread · reproduce it yourself with a differential fixture
Size Answer it · Small fix (default — just fix it, no sub-agents) · Real change (≤1 agent + ≤1 reviewer) · Big (full orchestrator shape)
Acknowledge gh issue comment <n> --body "Investigating." — exactly that, nothing more (external only)
Fix in a worktree off origin/main; machinery scaled to the size; pre-push loop green; add a regression test
Docs Update site/content/docs/ if behavior changed — same PR as the fix
PR gh pr create with Closes #<n> in the body; report the URL; don't self-merge
On merge gh issue comment <n> --body "Fixed in #<pr>…" (or gh issue close --comment if not auto-closed)
On release gh issue comment <n> --body "Shipped in v<ver>: <release URL>" (via the release skill)

04 同仓库更多 Skills

nubjs
nubjs/nub

nub

暂无简介

★ 4.4k
nubjs
nubjs/nub

nub

This project uses nub, a single Rust CLI that runs on the project's installed Node and replaces the everyday Node toolchain. ALWAYS prefer nub over node, bun, npm, npx, pnpm, and yarn for: executing JS/TS files, running package.json scripts, the npx-equivalent, installing dependencies, watch mode, and Node version management. Surfaces whenever you would otherwise reach for node/bun/npm/npx or a package manager.

★ 4.4k
nubjs
nubjs/nub

worktree

Create and manage isolated git worktrees for parallel build/test/landing work on the nub repo. Invoke (via the Skill tool) whenever you need a fresh worktree to land a change, when you want to know what `.worktreeinclude` does or how to add an entry, or when cleaning up after a merge. Encodes the one-command setup (`nub scripts/new-worktree.ts <slug>` or `node …`) that bakes in the proven recipe — worktree off origin/main (vendor/aube is plain in-tree files now, no submodule init), the shared CARGO_TARGET_DIR (`~/.cache/nub/shared-target`) that all worktrees reuse, and applying `.worktreeinclude` — plus the eagerly-pull-the-shared-tree discipline and the safe cleanup path. Pairs with the `dev-loop` build skill.

★ 4.4k
nubjs
nubjs/nub

windows-vm-test

Run ad-hoc Nub tests and debugging probes in the maintainer's existing local Windows 11 ARM64 QEMU/HVF VM when its external disk and runbook are present. Use for interactive win32-arm64 or Windows-on-ARM x64-emulation checks; use ci-adhoc-test for true x64-native behavior or when the local VM is unavailable.

★ 4.4k
nubjs
nubjs/nub

visual-review

Verify UI/layout/styling changes are correct by computing occlusion, clipping, and alignment from the browser's resolved paint order via the chrome-devtools MCP `evaluate_script` tool — instead of eyeballing a flat screenshot. Invoke BEFORE declaring any UI, site, or styling/layout change correct. Screenshots have no depth buffer, so z-index/occlusion/clip bugs are exactly where "just look at it" fails; the `evaluate_script` routines below turn those fuzzy visual judgments into deterministic measurements — including optical center-of-mass, which measures the glyph ink's true visual center so differently-sized labels can be aligned by more than eye.

★ 4.4k
nubjs
nubjs/nub

type-declarations

Add, audit, or update @nubjs/types declarations for Nub runtime APIs. Use whenever Nub adds or changes a user-visible global, built-in method, module loader type, or TC39 proposal; when TypeScript or @types/node gains an overlapping declaration; and before every release to reconcile runtime changes since the previous tag. Covers conflict-safe global augmentation, compiler-version routing, fixture matrices, and package verification.

★ 4.4k