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.

Guardrails

• Tone is factual, neutral, professional — never braggy, competitive, or over-promising. See PROSE.md.
• 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.

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 PROSE.md. 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 fray methodology earns its keep (load the fray skill by name) — you orchestrate, 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 (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.

Step 5 — On merge, comment the resolution

Closes #N auto-closes the issue silently, so add a brief factual comment:

gh issue comment <n> --repo nubjs/nub --body "Fixed in #<pr> (merged to main). Will ship in the next release."

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 "<what fixed 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.

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"

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