diff --git a/.agents/skills/nemoclaw-maintainer-community-response/SKILL.md b/.agents/skills/nemoclaw-maintainer-community-response/SKILL.md new file mode 100644 index 000000000..d2e8488f5 --- /dev/null +++ b/.agents/skills/nemoclaw-maintainer-community-response/SKILL.md @@ -0,0 +1,429 @@ +--- +name: nemoclaw-maintainer-community-response +description: Drafts community-facing responses to GitHub issues and PRs for NemoClaw maintainers. For each item, recommends an action (comment, close, close+comment, request changes, escalate) and drafts the response text. Handles won't-fix closures, out-of-scope closures, superseded PRs, poorly designed PR rejections, security acknowledgments, duplicate issues, feature request routing, needs-info labeling, and general triage. Logs approved responses to a local monthly file — path configured in ~/.claude/skills/nemoclaw-maintainer-community-response/config.md. Tone: community first, firm and friendly. Trigger keywords - respond to issue, close issue, respond to PR, community response, won't fix, out of scope, reject PR, triage response, draft response, what should I say, needs info, duplicate issue, feature request, stale sweep, 7-day warning, 14-day close, run stale sweep, find stale. +user_invocable: true +--- + + + + +# NemoClaw Maintainer — Community Response + +Draft a response to a GitHub issue or PR, recommend an action, and log the approved response. + +**Tone:** Community first, firm and friendly. Lead with acknowledgment. Hold the line when needed. Never dismissive. + +## Step 1: Read the Guides + +Before drafting, read both reference docs: + +```bash +cat docs/maintainer-guide-snippet.md +cat docs/project-workflow.md +``` + +Do not draft from memory. The guides may have been updated. `maintainer-guide-snippet.md` has the response templates. `project-workflow.md` has the status semantics and full label structure. + +## Step 2: Gather Context + +Ask the user (or infer from context) for: + +- Issue or PR number and title +- Body text (or summary if long) +- Any existing comments relevant to the response +- Whether this is an issue or a PR + +If the user provides a URL or number only, ask for the body text — don't assume. + +## Step 3: Identify the Situation + +Map the item to one of the situations in the guide: + +| Situation | When | +|---|---| +| Won't fix / out of scope / needs design | Valid item, but won't be addressed or is outside scope | +| Superseded PR | Another PR was merged that covers the same ground | +| Security acknowledgment | Contributor reported or fixed a vulnerability | +| Poorly designed PR | PR cannot merge as-is; needs specific changes | +| Duplicate | Same issue or PR already exists | +| Feature request | Valid suggestion, not a bug — route to parking | +| Redirect to Discussions | Open-ended question or design topic, not actionable | +| Triage acknowledgment | Valid open issue, confirmed, no timeline yet | +| Needs info (first contact) | Can't investigate without more information from contributor | +| Needs info (7-day warning) | Labeled `status: needs-info`, 7 days elapsed, no response — post warning | +| Needs info (close) | Labeled `status: needs-info`, 14 days elapsed, no response — close | +| Rebase (7-day warning) | Labeled `status: rebase`, 7 days elapsed, no response — post warning | +| Rebase (close) | Labeled `status: rebase`, 14 days elapsed, no response — close | + +If the situation is ambiguous, ask: "Is this a closure, a needs-info, a routing decision, or something else?" + +### Supersession verification gate (mandatory before classifying any PR as superseded) + +Do not classify a PR as superseded based on a hunch or a keyword match in `git log`. Before presenting a supersession recommendation, verify all three of the following: + +1. **The superseding work is actually merged to main:** + ```bash + git fetch origin + git log origin/main --oneline | grep -iE "" + ``` + +2. **The files the candidate PR touches still exist and were changed by the superseding work** — check both: + ```bash + git ls-tree -r origin/main --name-only | grep "" + gh api repos/NVIDIA/NemoClaw/pulls//files --jq '.[].filename' + ``` + If the candidate PR's target files no longer exist (e.g., removed in the TypeScript migration), note this explicitly — the changes are moot, which is a valid supersession basis but a different one. + +3. **The core intent is covered, not just surface-level overlap** — read both PR bodies and confirm the superseding PR addresses the same root problem. Keyword overlap alone is not enough. If the approaches differ significantly (e.g., external bridge vs. in-sandbox token injection), name the difference explicitly in the draft and in the recommendation. + +If any of the three checks fails or is ambiguous, do not classify as superseded. Present the finding to the user and ask how to proceed. + +## Step 4: Recommend an Action and Project Status + +State the recommended action and **project status** clearly before drafting. The project status field must be set on every item — do not leave it as "Done" by default. + +**Actions:** + +| Action | When | +|---|---| +| `comment` | Post a reply, leave open (triage ack, needs-info first contact, redirect to Discussions) | +| `close` | Close with comment | +| `request changes` | PR needs revision — post comment, leave open | +| `comment + label` | Post comment AND apply a label (e.g., rebase nudge → apply `status: rebase`) | +| `escalate` | Security report that should go through PSIRT — do not respond publicly | +| `rebase nudge` | PR has **verified** merge conflicts (`mergeable_state=dirty` only) — post comment asking author to rebase, apply `status: rebase`. See rebase gate in Step 5. | +| `integration hold` | PR has any `Integration: *` label — post integration evaluation holding comment instead of rebase nudge. Never apply `status: rebase` to integration PRs regardless of merge state. | + +**Project status mapping (NemoClaw Development Tracker):** + +| Situation | Project Status | +|---|---| +| Won't fix | `Won't Fix` | +| Out of scope / needs design | `Won't Fix` | +| Duplicate / superseded PR | `Duplicate` | +| Feature request (new, unreviewed) | `No Status` | +| Feature request (approved for future) | `Backlog` — only set this if maintainer has explicitly approved | +| Needs review / poorly designed PR | `Needs Review` | +| Triage acknowledgment (confirmed, backlogged) | `Backlog` | +| Needs info (first contact or close) | `No Status` | +| Completed / merged | `Done` | +| NVQA-tracked item | `NVQA` | + +**For feature requests — also suggest labels** (read label structure from `project-workflow.md`): +1. Always suggest `enhancement` as the base label +2. Suggest the most specific Tier 2 sub-label that fits (e.g., `enhancement: inference`, `enhancement: ui`) +3. Suggest Tier 3 dimension label(s) if platform-, integration-, or provider-specific (e.g., `Integration: Slack`, `Platform: MacOS`) + +Present as: **Action:** `comment` · **Project status:** `No Status` · **Suggested labels:** `enhancement`, `enhancement: inference` + +Always present as: **Action:** `close` · **Project status:** `Won't Fix` (for closures) + +## Step 5: Draft the Response + +Write the response following the template from the guide. Apply these rules: + +- **Always explain why** when closing — never close silently. +- **Acknowledge contributors** when their work informed a solution, even if it didn't land. +- **Be specific** — name the exact reason, the exact information needed, the exact problem with the PR. +- **One sentence on why.** Not a paragraph. Not a list. +- Write in second person, direct address to the contributor. +- Warm but specific — generic phrases without substance read as dismissive. +- Never reference internal systems, roadmap items, or org decisions that shouldn't be public. +- **7-day notice in first-contact comments:** When posting a `needs-info` comment or `rebase nudge`, include a one-sentence notice at the end of the comment: "If we don't hear back within 7 days, we'll post a reminder; items with no response at 14 days are closed to keep the queue healthy." +- **Hedged language for risks and impacts:** Do not assert that something IS a risk or problem. Use acknowledging, hedged language: "could be", "may", "worth noting", "potentially". Example: "unbounded CPU/memory could be an operational risk" — not "is a real operational risk". This applies to security, performance, correctness, and other concerns raised in response comments. +- **Rebase verification gate (mandatory before any rebase nudge):** Before posting a rebase nudge or applying `status: rebase`, check the PR's actual merge state: + ```bash + gh api repos/NVIDIA/NemoClaw/pulls/ --jq '"\(.mergeable) \(.mergeable_state)"' + ``` + Only proceed with the rebase nudge if `mergeable_state` is `dirty` (actual merge conflict). Do NOT send a rebase nudge if the state is: + - `blocked` — PR merges cleanly, needs review or CI sign-off + - `unstable` — PR merges cleanly, CI is failing + - `unknown` — GitHub hasn't computed yet; re-check before acting + + If the state is not `dirty`, do not apply `status: rebase`. Choose the correct action for the actual state instead. + +- **Integration PRs — no rebase nudge:** If the PR already has any `Integration: *` label, post the integration evaluation holding comment instead. Do not apply `status: rebase` to integration PRs regardless of merge state. + +- **PRs requiring rebase:** After posting the comment, always apply `status: rebase` via: + ```bash + gh pr edit --repo NVIDIA/NemoClaw --add-label "status: rebase" + ``` + This keeps rebase-blocked PRs distinct from needs-info PRs and surfaces them for follow-up separately. +- **Same contributor on multiple PRs needing rebase:** If the contributor who owns this PR also has another open PR that needs a rebase, note it in the comment — suggest a joint rebase on both at once. Example addition: "Note this is from the same contributor as #[N] — a joint rebase on both would be ideal." Apply `status: rebase` to both PRs. Check for contributor overlap before sending any rebase nudge. + +- **Author identification:** For every PR, check whether the author is an NVIDIA org member before drafting: + ```bash + gh api orgs/NVIDIA/members/ --silent 2>/dev/null && echo "NVIDIA member" || echo "external" + ``` + Include in the draft presentation header as: **Author:** username (NVIDIA) or **Author:** username (external). + +- **Git fetch rule:** Always run `git fetch origin` before any supersession check, especially in long sessions. Re-fetch at the start of any session that resumes after more than 2 hours of inactivity. + +- **Session resume validation:** When resuming after a break: + 1. Run `git fetch origin` to get the latest main + 2. For any PRs already queued but not yet actioned, verify they are still open before proceeding: + ```bash + gh api repos/NVIDIA/NemoClaw/pulls/ --jq '.state' + ``` + Skip any PR that returns `"closed"`. + +## Step 6: Present for Approval + +Show the user: + +1. **Recommended action and project status** (e.g., `close` · project status: `Won't Fix`) + **Author:** username (NVIDIA) or username (external) + **Opened:** YYYY-MM-DD (N days ago) +2. **Draft response** (ready to paste into GitHub) +3. Any follow-up note (e.g., "add the label before closing") + +Ask: "Want me to adjust the tone or any specific wording?" + +## Step 7: Log the Approved Response + +**First, determine the log directory:** + +```bash +cat ~/.claude/skills/nemoclaw-maintainer-community-response/config.md +``` + +Extract the line immediately after `## community_responses_dir` — that is the directory path. + +If the config file does not exist or contains no `community_responses_dir` value, ask: +> "Where should I log community responses? Provide the full directory path (e.g. `/Users/yourname/development/daily-rhythm/activity/community-responses`)." + +After the user provides the path, write it to config before proceeding: +```bash +cat > ~/.claude/skills/nemoclaw-maintainer-community-response/config.md << 'EOF' +# nemoclaw-maintainer-community-response — Config + +## community_responses_dir +/path/provided/by/user + +The skill appends to `{community_responses_dir}/{YYYY-MM}.md` where YYYY-MM is the +current month in America/Los_Angeles time. Update this path if the daily-rhythm repo moves. +EOF +``` + +**Compute the monthly file path:** +```bash +YM=$(python3 -c "from datetime import datetime; from zoneinfo import ZoneInfo; print(datetime.now(ZoneInfo('America/Los_Angeles')).strftime('%Y-%m'))") +# LOG_FILE = {community_responses_dir}/${YM}.md +``` + +Create the monthly file if it doesn't exist. Never stage or commit this file to the NemoClaw repo. + +**Format v2** — all fields required, in this order: + +``` +## [ISSUE|PR] # — +**Date:** YYYY-MM-DD +**Time:** HH:MM PDT +**Author:** @github-username (external | NVIDIA | bot) +**Action:** closed | commented | labeled | reopened +**Resolution:** resolved | duplicate | stale | wontfix | superseded | needs-info | other | — +**Labels:** label1, label2 | (none) + +**Response:** +<approved response text> + +=== +``` + +**Field rules:** +- **Action**: pipe-separated for compound actions — `closed | commented` is the most common (close with a public response); `commented` alone for rebase nudges or info requests; `labeled` for label-only actions +- **Resolution**: why it was closed — use `—` when Action does not include `closed` +- **Labels**: labels actually applied, comma-separated — use `(none)` if no labels were added +- **Author**: the GitHub handle of the issue/PR reporter, not the maintainer responding +- **Time**: current time in PDT/PST (America/Los_Angeles) +- **Response section**: include if a public comment was posted; omit entirely for label-only actions with no comment + +**Batch entries** (multiple numbers in one heading): +``` +## PR #1482, #1485, #1487 — Rebase nudges (batch 13) +**Date:** 2026-04-15 +**Time:** 10:15 PDT +**Author:** various +**Action:** commented +**Resolution:** — +**Labels:** (none) + +**Response:** +#1482 by ColinM-sys — joint rebase suggested. #1485 by kagura-agent — rebase suggested. + +=== +``` + +**After appending, verify the entry landed:** +```bash +tail -25 "$LOG_FILE" +``` + +## Batch Mode + +When processing multiple PRs in one session, present a batch analysis table before drafting any individual responses: + +``` +┌───────┬──────────┬──────────┬────────┬──────────────┬───────┐ +│ PR │ Author │ NV? │ Opened │ Action │ Notes │ +├───────┼──────────┼──────────┼────────┼──────────────┼───────┤ +│ #1234 │ username │ external │ Apr 10 │ rebase nudge │ dirty │ +└───────┴──────────┴──────────┴────────┴──────────────┴───────┘ +``` + +Columns: +- **PR** — number with # +- **Author** — GitHub username +- **NV?** — `NVIDIA` or `external` +- **Opened** — `Mon DD` format +- **Action** — recommended action from Step 4 +- **Notes** — merge state (dirty/blocked/unknown), label flags, or other relevant context + +Ask the user to confirm or adjust the batch plan before proceeding to draft responses one by one. + +## Stale Sweep + +**Trigger phrases:** "stale sweep", "run stale sweep", "7-day warnings", "14-day closures", "find stale", "stale check" + +Runs Stage 2 (7-day warning) and/or Stage 3 (14-day close) for items carrying `status: needs-info` or `status: rebase`. Ask the user which stage(s) to run if not specified. + +### Step A: Discover candidates + +Run all queries: + +```bash +# Issues with status: needs-info +gh issue list --repo NVIDIA/NemoClaw --label "status: needs-info" --state open \ + --json number,title,author,url --limit 200 + +# PRs with status: needs-info +gh pr list --repo NVIDIA/NemoClaw --label "status: needs-info" --state open \ + --json number,title,author,url --limit 200 + +# PRs with status: rebase +gh pr list --repo NVIDIA/NemoClaw --label "status: rebase" --state open \ + --json number,title,author,url --limit 200 +``` + +### Step B: Determine label age and author activity + +For each candidate, check when the relevant label was last applied: + +```bash +gh api repos/NVIDIA/NemoClaw/issues/<number>/events \ + --jq '[.[] | select(.event == "labeled" and .label.name == "status: needs-info")] | last | .created_at' +``` + +Use `"status: rebase"` for rebase items. Compute age in days from today. + +**For `status: needs-info` items only** — also check when the author last commented: + +```bash +gh api repos/NVIDIA/NemoClaw/issues/<number>/comments \ + --jq '[.[] | select(.user.login == "<author>")] | last | .created_at' +``` + +If the author's last comment is **after** the label was applied, the author has responded since labeling. Do NOT include this item in the warning or close buckets. Move it to the "responded" group (Step D) for label review. The `status: needs-info` label may no longer apply — the maintainer should re-triage. + +Note: this author-activity check does not apply to `status: rebase` items. A PR comment does not resolve merge conflicts; rebase state is determined by code, not by conversation. + +Bucket each item: +- **Author commented after label** → responded — review for label removal (needs-info only) +- **7–13 days, no author response** → Stage 2 candidate (warning) +- **14+ days, no author response** → Stage 3 candidate (close) +- **< 7 days, no author response** → ignore + +### Step C: Check author NVIDIA membership + +For every candidate: + +```bash +gh api orgs/NVIDIA/members/<username> --silent 2>/dev/null && echo "NVIDIA member" || echo "external" +``` + +### Step D: Present candidates by stage + +Present tables by category. If a category has no candidates, say so explicitly. + +**Responded since labeled — review for label removal (needs-info only):** +``` +┌───────┬────────┬────────────┬──────────┬──────────┬─────────────────────┐ +│ # │ Type │ Author │ NV? │ Label Age│ Last Author Comment │ +├───────┼────────┼────────────┼──────────┼──────────┼─────────────────────┤ +│ #1234 │ issue │ username │ external │ 8d │ Apr 13 (after label)│ +└───────┴────────┴────────────┴──────────┴──────────┴─────────────────────┘ +``` +These items need re-triage, not automated action. Ask the maintainer: "Author has responded — does their reply address the request? If yes, remove `status: needs-info` and re-triage. If no, leave the label in place." + +**Stage 2 — Warning (7–13 days):** +``` +┌───────┬────────┬────────────┬──────────┬────────────┬──────┬─────────┐ +│ # │ Type │ Author │ NV? │ Label │ Age │ Action │ +├───────┼────────┼────────────┼──────────┼────────────┼──────┼─────────┤ +│ #1234 │ issue │ username │ external │ needs-info │ 8d │ warning │ +└───────┴────────┴────────────┴──────────┴────────────┴──────┴─────────┘ +``` + +**Stage 3 — Close (14+ days):** +``` +┌───────┬────────┬────────────┬──────────┬────────────┬──────┬─────────┐ +│ # │ Type │ Author │ NV? │ Label │ Age │ Action │ +├───────┼────────┼────────────┼──────────┼────────────┼──────┼─────────┤ +│ #1235 │ PR │ username2 │ external │ rebase │ 21d │ close │ +└───────┴────────┴────────────┴──────────┴────────────┴──────┴─────────┘ +``` + +Ask: "Confirm which items to action — remove any to skip." + +If no candidates in either stage, report that and stop. + +### Step E: Draft and post — Stage 2 (warning) + +For each confirmed Stage 2 item, present the draft before posting. Leave the item **open** — do NOT close at Stage 2. + +**Template — needs-info warning:** +> Just a friendly nudge — we're still waiting on the information requested above. If we don't hear back within 7 days, we'll close this to keep the queue healthy. Feel free to reopen any time if you'd like to continue. + +**Template — rebase warning:** +> Just a friendly nudge — this PR still has merge conflicts. If the rebase isn't completed within 7 days, we'll close this to keep the queue healthy. Feel free to reopen once it's rebased, or open a new PR. + +```bash +gh issue comment <number> --repo NVIDIA/NemoClaw --body "<warning comment>" +gh pr comment <number> --repo NVIDIA/NemoClaw --body "<warning comment>" +``` + +### Step F: Draft and post — Stage 3 (close) + +For each confirmed Stage 3 item, present the draft before posting. + +**Template — needs-info close:** +> Closing due to inactivity — it's been 14 days since we requested additional information and we haven't heard back. Feel free to reopen if you're able to follow up, or open a new issue with the requested details included. Thanks for contributing to NemoClaw. + +**Template — rebase close:** +> Closing due to inactivity — this PR has had merge conflicts for 14 days without an update. Feel free to reopen once it's rebased against the latest main, or open a new PR to continue the work. Thanks for contributing to NemoClaw. + +```bash +gh issue close <number> --repo NVIDIA/NemoClaw --comment "<closing comment>" +gh pr close <number> --repo NVIDIA/NemoClaw --comment "<closing comment>" +``` + +### Step G: Log each actioned item + +For every Stage 2 warning and Stage 3 closure, append to the log using the Step 7 format: + +- Stage 2: **Action:** `comment` · **Project status:** `No Status` +- Stage 3: **Action:** `close` · **Project status:** `No Status` + +## Response Time Check + +If the user asks whether a response window is at risk, check against: + +| Situation | Target | +|---|---| +| New issue | First response ≤ 5 business days | +| Open PR, no review | First comment ≤ 7 business days | +| Contributor asks for update | Reply ≤ 3 business days | +| `status: needs-info` labeled | Warning at 7 days, close at 14 days | +| `status: rebase` labeled | Warning at 7 days, close at 14 days | + +A window is "at risk" when 80% of the target has elapsed. Surface as a flag, not an alarm. diff --git a/.gitignore b/.gitignore index 10836b712..c6ce7d571 100644 --- a/.gitignore +++ b/.gitignore @@ -46,3 +46,7 @@ secrets.json secrets.yaml service-account*.json token.json + +# Devlogs are local only +DEVLOG.md +**/DEVLOG.md diff --git a/docs/maintainer-guide-snippet.md b/docs/maintainer-guide-snippet.md new file mode 100644 index 000000000..03f495a3d --- /dev/null +++ b/docs/maintainer-guide-snippet.md @@ -0,0 +1,147 @@ +--- +orphan: true +title: "NemoClaw Community Engagement Quick Reference" +description: "Quick reference card for NemoClaw maintainers — closing, merging, rejecting, duplicates, feature requests, triage, and needs-info flows." +keywords: maintainer, community, triage, quick reference +topics: [maintainer, community] +tags: [maintainer, community] +content_type: reference +difficulty: beginner +audience: maintainers +status: active +--- + +<!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. --> +<!-- SPDX-License-Identifier: Apache-2.0 --> + +# NemoClaw — Community Engagement Quick Reference + +> - **Always explain why** when closing — never close silently. +> - **Acknowledge contributors** when their work informs a merged solution, even if their PR didn't land. +> - **Security reporters get credit** — even when the fix goes through PSIRT, not GitHub. +> - **Be specific when declining** — vague feedback wastes everyone's time and damages trust. +> - **Route, don't reject** feature requests — backlog or Discussions, never silence. +> - **Name what you need** when asking for info — and give the contributor 7 days to respond. + +--- + +## Closing Won't Fix / Out of Scope + +| Reason | Label | Board status | +|---|---|---| +| Valid issue, won't address | `wontfix` | `Won't Fix` | +| Outside project design/scope | `wontfix` | `Won't Fix` | +| Good idea, needs a proposal first | `wontfix` | `Won't Fix` | + +> Thanks for raising this. +> After review, we're closing as **[label]** because [one sentence]. +> See [CONTRIBUTING.md](https://github.com/NVIDIA/NemoClaw/blob/main/CONTRIBUTING.md) for scope guidance. +> We appreciate you taking the time. + +--- + +## When Your Merge Supersedes Another PR + +Comment on the closed PR before you merge: + +> Closing in favor of #[N], which was merged and covers the same ground. Your [approach / test cases / edge case] helped shape the solution that landed — thanks for working on this. + +**Security PRs:** Always acknowledge the finding explicitly, even when the fix went through PSIRT: + +> Thanks for identifying this. The fix followed our [coordinated disclosure process](https://github.com/NVIDIA/NemoClaw/blob/main/SECURITY.md), but your report is a real contribution and we want to recognize it. + +--- + +## Rejecting a Poorly Designed PR + +1. **Acknowledge intent** — one sentence on what they were solving +2. **Name the specific problem** — don't say "not quite right," say why +3. **Give a path forward** — what would need to change, or ask them to start in an issue first + +> Thanks for tackling [X] — it's a real gap. The approach here [specific problem]. Before we could accept this, we'd need [specific ask]. Happy to discuss the right approach in the issue first. + +--- + +## Closing Duplicates + +> Thanks for the report. +> This is a duplicate of #[N] — all discussion is happening there. +> Closing in favor of the original thread. +> Feel free to add context or subscribe to #[N] to follow along. + +**Label:** `duplicate` · **Board status:** `Duplicate` + +--- + +## Feature Requests + +> Thanks for the suggestion. We've noted this and will review it — we'll update this issue if it moves forward. We don't have a timeline to share yet. + +**Project status:** `No Status` (do NOT say "added to backlog" — that implies approval) + +**Labels:** Always apply `enhancement` + the most specific sub-label (`enhancement: inference`, `enhancement: ui`, etc.) + any Tier 3 dimension labels (`Integration: Slack`, `Platform: macOS`, `Provider: NVIDIA`, etc.) + +*Full label reference: [docs/project-workflow.md](project-workflow.md)* + +--- + +## Redirecting to Discussions + +> This looks like a great topic for an open conversation rather than a bug or feature request. I've moved this to Discussions here: [link]. Closing the issue to keep the tracker focused on actionable items. + +--- + +## Triage Acknowledgment + +> Thanks for the detailed report — we've confirmed this and added it to our backlog. We don't have a timeline to share yet, but we've got it on our radar. We'll update this issue when work begins. + +--- + +## Needs Info + +**Day 0 — first contact:** label `status: needs-info`, leave open: + +> Thanks for the report. To move forward, we need: [specific ask]. We'll keep this open for 14 days. + +**Day 7 — warning** (no response yet): + +> We haven't heard back yet. If this is still affecting you, please share [repeat specific ask]. We'll close this in 7 days if we don't hear back. + +**Day 14 — close:** + +> Closing due to no response. If this is still happening, please open a new issue and include [repeat the specific ask]. Happy to take another look. + +## Needs Rebase + +**Day 0 — rebase nudge:** apply `status: rebase`, post comment asking to rebase. + +**Day 7 — warning** (no rebase yet): + +> This PR still needs a rebase. Please rebase against `main` within the next 7 days. + +**Day 14 — close:** + +> Closing due to inactivity — please open a new PR rebased against `main` if you'd like to continue. + +--- + +## Response Time Commitments + +| Situation | Target | +|---|---| +| New issue | First response < 3 business days | +| Open PR, no review | First comment < 5 business days | +| Contributor asks for update | Reply ≤ 3 business days | + +If you'll miss a window — post an update before it lapses. + +--- + +*Full guide: [docs/maintainer-guide.md](maintainer-guide.md) · Scope: [CONTRIBUTING.md](https://github.com/NVIDIA/NemoClaw/blob/main/CONTRIBUTING.md) · Security: [SECURITY.md](https://github.com/NVIDIA/NemoClaw/blob/main/SECURITY.md)* + +--- + +## Next Steps + +- [Maintainer Guide](maintainer-guide.md) — full workflows, decision trees, and templates +- [Project Workflow](project-workflow.md) — board status semantics and label taxonomy diff --git a/docs/maintainer-guide.md b/docs/maintainer-guide.md new file mode 100644 index 000000000..eedc2ef24 --- /dev/null +++ b/docs/maintainer-guide.md @@ -0,0 +1,265 @@ +--- +orphan: true +title: "NemoClaw Maintainer Guide" +description: "Reference for NVIDIA engineers handling issues and PRs from external contributors. Covers closing, merging, rejecting, duplicates, feature requests, triage, and needs-info flows." +keywords: maintainer, community, issues, pull requests, triage, response +topics: [maintainer, community] +tags: [maintainer, community] +content_type: reference +difficulty: intermediate +audience: maintainers +status: active +--- + +<!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. --> +<!-- SPDX-License-Identifier: Apache-2.0 --> + +# NemoClaw Maintainer Guide + +A reference for NVIDIA engineers handling issues and PRs from external contributors. + +## TL;DR + +- **Always explain why** when closing an issue or rejecting a PR — never close silently. +- **Acknowledge contributors** when their work informs a merged solution, even if their PR didn't land. +- **Security reporters get credit** — even when the fix goes through PSIRT, not GitHub. +- **Be specific when declining** — vague feedback wastes everyone's time and damages trust. +- **Route, don't reject** feature requests — backlog or Discussions, never silence. +- **Name what you need** when asking for info — and give the contributor 7 days to respond. + +--- + +## Closing Issues as Won't Fix or Out of Scope + +These are different signals — use the right one. + +| Close reason | When to use | Label | Board status | +|---|---|---|---| +| **Won't fix** | Valid bug or gap, but not something we intend to address | `wontfix` | `Won't Fix` | +| **Out of scope** | Doesn't fit the project's design or intended use case | `wontfix` | `Won't Fix` | +| **Needs design first** | Technically feasible but needs a proposal before code | `wontfix` | `Won't Fix` | + +**Response template:** + +> Thanks for raising this. After review, we're closing it as **[won't fix / out of scope]** because [one sentence: e.g., "this behavior is intentional — NemoClaw delegates session management to the host environment" / "this use case is better addressed at the blueprint layer"]. +> +> [Optional: link to the relevant section of CONTRIBUTING.md, a prior decision thread, or a doc page that explains the scope boundary.] +> +> We appreciate you taking the time — this kind of feedback helps us clarify what NemoClaw is and isn't designed to do. + +**Rules:** + +- Name the reason, not just the verdict. +- Don't say "maybe later" unless you mean it. Vague deferral creates false expectations. +- If scope is genuinely unclear, open an internal discussion before closing — don't leave the contributor waiting while you debate it. +- Add the label before you close, not after. + +--- + +## Merging a PR That Makes Another PR Redundant + +When your merge closes out another contributor's open PR, comment on the superseded PR before or immediately after merging. + +**Template:** + +> Closing this in favor of #[PR number], which was merged and addresses the same issue. Thanks for working on this — [the approach you took / your test cases / the edge case you identified] helped shape the solution that landed. + +If their PR directly influenced the merged implementation, be specific: + +> Your handling of [X] in this PR informed how we approached [Y] in #[merged PR]. That contribution matters even though the final code came from a different direction. + +**For security-related PRs specifically:** + +If someone submitted a PR to fix a vulnerability — regardless of whether the fix merged — acknowledge the finding explicitly: + +> Thanks for identifying and reporting this. The fix went through our [coordinated disclosure process](https://github.com/NVIDIA/NemoClaw/blob/main/SECURITY.md), but we want to recognize that you spotted this and brought it to our attention. That's a real contribution. + +NVIDIA's SECURITY.md notes that acknowledgement is offered under the coordinated vulnerability disclosure policy. Maintainers should treat this as a commitment, not a courtesy — make sure credit is given. + +--- + +## Rejecting Poorly Designed Contributions + +Clear, specific feedback is more respectful than silence or vague encouragement. If something can't merge as-is, say why and give the contributor a concrete path forward. + +**Structure:** + +1. **Acknowledge the intent** — one sentence on the problem they were solving. +2. **Name the specific issue** — design mismatch, missing tests, security concern, breaks an existing contract, performance tradeoff, etc. Be precise. +3. **Offer a path forward** — "here's what we'd need to accept this" or "start with a design discussion in the issue tracker." + +**Example:** + +> Thanks for tackling the connection retry logic — this is a real pain point. The approach here bypasses the existing error normalization layer in `nemoclaw/src/errors.ts`, which means consumers downstream would need to handle two different error shapes. Before we could accept something like this, we'd need the retry logic to sit on top of that layer rather than beside it, and unit tests covering the backoff behavior. +> +> Happy to discuss the right entry point in the issue if you want to take another pass. + +**Don't:** + +- Say "this isn't quite right" without saying what's wrong. +- Ask for changes and then go quiet. If you request revisions, follow through on the review. +- Leave a PR open for weeks with no feedback. If it's blocked on your side, say so. + +**When the contribution is too far off to be revised:** + +> This takes the architecture in a direction we're not planning to go — we'd need [X] to be true first before this kind of change makes sense. Closing for now, but if [X] changes, this problem is worth revisiting. + +--- + +## Response Time Norms + +These are team commitments, not aspirational targets. + +| Situation | Target | +|---|---| +| New issue from external contributor | First response within 3 business days | +| PR with no review | First comment within 5 business days | +| Contributor asks for an update | Respond within 3 business days | +| Security report via <psirt@nvidia.com> | Handled by PSIRT — not in scope here | + +If you're going to miss a window, post an update before it lapses — even one sentence ("We're reviewing this, expect feedback by [date]") resets the contributor's expectations and preserves trust. + +--- + +## Closing Duplicates + +When an issue or PR covers the same ground as an existing open or closed item, close the newer one and point to the original. + +**Response template:** + +> Thanks for the report. This is a duplicate of #[N] — all discussion is happening there. Closing in favor of the original thread. Feel free to add context or subscribe to #[N] to follow along. + +**Label:** `duplicate` · **Board status:** `Duplicate` + +**Rules:** + +- Always link to the original. Don't close silently against a label alone. +- If the duplicate adds meaningful new context not in the original, say so: "You've added [X] — I'll note that in #[N]." +- If you're not sure which is the "original," close the one with less discussion. + +--- + +## Feature Requests + +Feature requests are not rejections — they're routing decisions. Route to the Enhancement Parking board; don't close without acknowledgment. + +**Response template:** + +> Thanks for the suggestion. We've noted this and will review it — we'll update this issue if it moves forward. We don't have a timeline to share yet. + +**Project status:** `No Status` (unreviewed). A maintainer sets `Backlog` when approved for future work. + +**Labels to apply** (see [project-workflow.md](project-workflow.md) for the full label structure): + +1. Always apply `enhancement` as the base label +2. Add the most specific Tier 2 sub-label: `enhancement: inference`, `enhancement: ui`, `enhancement: security`, etc. +3. Add Tier 3 dimension labels if platform-, integration-, or provider-specific: `Platform: macOS`, `Integration: Slack`, `Provider: NVIDIA`, etc. + +**Rules:** + +- Do NOT say "added to backlog" — that implies maintainer approval. Use "we'll review it." +- Don't commit to a timeline unless one is confirmed. +- If the request is clearly outside NemoClaw's scope, use § 1 (Out of Scope) instead. +- If the request is better suited for an open design conversation, use § 7 (Redirect to Discussions). + +**Promotion flow:** `No Status` → maintainer reviews → `Backlog` → approved for release → `In Progress` + +*Full workflow and label reference: [docs/project-workflow.md](project-workflow.md)* + +--- + +## Redirecting to Discussions + +Some issues are better suited to open conversation than bug or feature tracking. Move them to Discussions rather than closing without a destination. + +**Response template:** + +> This looks like a great topic for an open conversation rather than a bug or feature request. I've moved this to Discussions here: [link] — would love to hear more there. Closing the issue to keep the tracker focused on actionable items. + +**Rules:** + +- Only redirect when a Discussion thread exists or you're creating one at the same time. Don't close without a destination. +- Good candidates: architecture questions, "how do you handle X?" questions, general feedback, use-case exploration. +- Don't redirect bug reports or clear feature requests — route those properly via § 1 or § 6. + +--- + +## Triage Acknowledgment + +Use when an issue is valid and understood but not yet scheduled. This is an acknowledgment, not a closure. + +**Response template:** + +> Thanks for the detailed report — we've confirmed this and added it to our backlog. We don't have a timeline to share yet, but we've got it on our radar. We'll update this issue when work begins. + +**Rules:** + +- Don't add a closure label — leave the issue open. +- Don't say "soon" or imply urgency unless it's true. +- If you need more information before confirming, use § 9 instead. + +--- + +## Needs Info + +Three-stage flow — label, warn, close. + +**Situation 1 — First contact (day 0):** + +> Thanks for the report. To move forward, we need a bit more information: [specific ask — e.g., reproduction steps, NemoClaw version, output of `nemoclaw status`]. We'll keep this open for 14 days — feel free to reopen or file a new issue once you have the details. + +**Action:** Add label `status: needs-info`, post comment, leave open. + +**Situation 2 — 7 days, no response (warning):** + +> We haven't heard back yet on the information we requested. If this is still affecting you, please share [repeat specific ask] and we'll keep the investigation going. We'll close this in 7 days if we don't hear back. + +**Action:** Post comment only — do not close yet. + +**Situation 3 — 14 days total, still no response (close):** + +> Closing due to no response — we weren't able to get the information needed to investigate. If this is still happening, please open a new issue and include [repeat the specific ask]. Happy to take another look. + +**Action:** `close + comment`. No additional label needed — `status: needs-info` already set. + +**Rules:** + +- Always name the specific information you need. "More details" wastes everyone's time. +- The window starts from when the label is applied, not when the issue was opened. +- Don't close at day 7 — warn first, close at day 14. + +--- + +## Needs Rebase + +Same three-stage flow applies to PRs labeled `status: rebase`. + +**Stage 1 — Rebase nudge (day 0):** Post rebase comment, apply `status: rebase`. *(See § 5 in SKILL.md for template.)* + +**Stage 2 — 7 days, no rebase (warning):** + +> This PR still needs a rebase before we can review it. If you're planning to update it, please rebase against `main` within the next 7 days. Happy to help if you run into conflicts. + +**Action:** Post comment only — do not close yet. + +**Stage 3 — 14 days total, no rebase (close):** + +> Closing due to inactivity — the PR needed a rebase and we didn't hear back. If you'd like to continue, please open a new PR rebased against the current `main`. We'd be glad to review it. + +**Action:** `close + comment`. + +--- + +## References + +- [CONTRIBUTING.md](https://github.com/NVIDIA/NemoClaw/blob/main/CONTRIBUTING.md) — scope, PR process, commit conventions +- [SECURITY.md](https://github.com/NVIDIA/NemoClaw/blob/main/SECURITY.md) — vulnerability disclosure; direct reporters here, not GitHub issues +- [CODE_OF_CONDUCT.md](https://github.com/NVIDIA/NemoClaw/blob/main/CODE_OF_CONDUCT.md) — all community interactions are governed by this +- [Bug report template](https://github.com/NVIDIA/NemoClaw/blob/main/.github/ISSUE_TEMPLATE/bug_report.yml) — what we ask contributors to provide + +--- + +## Next Steps + +- [Project Workflow](project-workflow.md) — board status semantics and label taxonomy +- [Agent Skills](resources/agent-skills.md) — community response and triage skills diff --git a/docs/project-workflow.md b/docs/project-workflow.md new file mode 100644 index 000000000..1aaf5e8da --- /dev/null +++ b/docs/project-workflow.md @@ -0,0 +1,185 @@ +--- +orphan: true +title: "NemoClaw Project Workflow Reference" +description: "Reference for maintainers covering project board status semantics, label taxonomy, board setup, and triage checklist." +keywords: workflow, project board, labels, triage, maintainer +topics: [maintainer, workflow] +tags: [maintainer, workflow] +content_type: reference +difficulty: beginner +audience: maintainers +status: active +--- + +<!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. --> +<!-- SPDX-License-Identifier: Apache-2.0 --> + +# NemoClaw Project Workflow Reference + +A reference for maintainers and the community response skill. Covers project board status semantics, the label structure for categorizing issues, and step-by-step instructions for configuring the NemoClaw Development Tracker. + +--- + +## Project Status Semantics + +| Status | Meaning | +|---|---| +| `No Status` | Unreviewed — just arrived, not yet triaged by a maintainer | +| `Backlog` | Reviewed and approved for future work — not yet scoped to a release | +| `In Progress` | Actively being worked on in the current cycle | +| `Needs Review` | PR open, awaiting maintainer review | +| `Done` | Completed and merged | +| `Won't Fix` | Declined — valid but won't be addressed | +| `Duplicate` | Duplicate of an existing item | +| `NVQA` | NVQA-tracked item | + +### Promotion Flow + +```text +No Status → Backlog → In Progress → Done + ↓ + Won't Fix (declined) + ↓ + Duplicate (superseded) +``` + +**Rules:** + +- Items only leave `No Status` when a maintainer has reviewed them. +- Items only leave `Backlog` when explicitly approved for a release cycle. +- Do not set `Backlog` in a community response — that implies maintainer approval. Set `No Status` for new incoming items. + +--- + +## Label Structure + +NemoClaw uses a three-tier label system. Apply labels in combination — start with Tier 1, add Tier 2, add Tier 3 if applicable. + +### Tier 1 — Issue Type (always apply one) + +| Label | When | +|---|---| +| `enhancement` | Feature request — always apply this as the base label alongside any sub-label | +| `bug` | Something isn't working as expected | +| `documentation` | Documentation improvement | +| `question` | User question or clarification request | +| `duplicate` | Duplicate of an existing issue | + +### Tier 2 — Sub-type (apply the most specific that fits) + +For feature requests, apply `enhancement` (Tier 1) plus one of: + +| Label | When | +|---|---| +| `enhancement: feature` | General new capability | +| `enhancement: inference` | Inference routing, model support, providers | +| `enhancement: security` | Security controls, policies, audit | +| `enhancement: policy` | Network policy, egress rules | +| `enhancement: ui` | CLI UX, output formatting | +| `enhancement: platform` | Cross-platform support (pair with `Platform: *`) | +| `enhancement: provider` | Cloud/inference provider support (pair with `Provider: *`) | +| `enhancement: performance` | Speed, resource usage, efficiency | +| `enhancement: reliability` | Stability, error handling, recovery | +| `enhancement: testing` | Test coverage, CI/CD quality | +| `enhancement: MCP` | MCP protocol support | +| `enhancement: CI/CD` | Pipeline, build, automation | +| `enhancement: documentation` | Documentation improvements | +| `enhancement: refactoring` | Code quality, internal cleanup | + +### Tier 3 — Dimension (apply when platform-, integration-, or provider-specific) + +**Platforms:** +`Platform: DGX Spark` · `Platform: macOS` · `Platform: Ubuntu` · `Platform: Brev` · `Platform: Windows/WSL` · `Platform: ARM64` · `Platform: AGX Thor/Orin` · `Platform: Fedora` + +**Integrations:** +`Integration: Telegram` · `Integration: Slack` · `Integration: Discord` · `Integration: GitHub` · `Integration: OpenClaw` · `Integration: WhatsApp` · `Integration: IRC` · `Integration: Brave` · `Integration: Feishu` · `Integration: Outlook` + +**Providers:** +`Provider: NVIDIA` · `Provider: OpenAI` · `Provider: Anthropic` · `Provider: Azure` · `Provider: AWS` · `Provider: GCP` · `Provider: Oracle` · `Provider: HuggingFace` + +### Labeling Examples + +| Request | Labels to apply | +|---|---| +| Add Slack bridge support | `enhancement` + `enhancement: feature` + `Integration: Slack` | +| Support NVIDIA NIM inference provider | `enhancement` + `enhancement: inference` + `Provider: NVIDIA` | +| Fix macOS install failure | `bug` + `Platform: macOS` | +| GPU flag for `nemoclaw onboard` | `enhancement` + `enhancement: ui` | +| Audio transcription routing through gateway | `enhancement` + `enhancement: inference` | + +### Status Labels (GitHub labels, separate from project board status) + +| Label | When | +|---|---| +| `status: triage` | Needs maintainer triage before categorization | +| `status: needs-info` | Waiting on contributor response — 7-day window, then close | +| `priority: high` | Needs to be addressed in the next release | +| `priority: medium` | Should be addressed in upcoming releases | +| `priority: low` | Nice to have, no urgency | + +--- + +## Board Setup Instructions + +One-time configuration for the NemoClaw Development Tracker (GitHub Projects UI). + +### Enhancement Parking + +This is the holding area for all unreviewed and approved-but-unscheduled feature requests. + +1. Create a new view, name it **"Enhancement Parking"** +2. Layout: Board or Table +3. Filter: `label:enhancement` +4. Group by: Label +5. Add status filter: show only `No Status` and `Backlog` + +### Platform and Integration Requests + +Separate view for platform-, integration-, and provider-specific requests (triaged separately from general enhancements). + +1. Create a new view, name it **"Platform & Integration Requests"** +2. Layout: Board or Table +3. Filter: `label:"Platform:"` OR `label:"Integration:"` OR `label:"Provider:"` +4. Group by: Label +5. Add status filter: show only `No Status` and `Backlog` + +### Main Board (update existing) + +Keep the main working board clean of unreviewed enhancements. + +1. Open the existing main board view +2. Add filter: exclude items where `label:enhancement` AND `status:No Status` +3. Result: unreviewed enhancements are hidden; approved enhancements (`Backlog`, `In Progress`, `Needs Review`) remain visible + +### Promoting an Enhancement to Active Work + +1. Open Enhancement Parking view +2. Review the issue — confirm it's worth pursuing +3. Set project status to `Backlog` (approved, unscheduled) → now appears on main board +4. When scoped to a release: set status to `In Progress` + +--- + +## Triage Checklist + +When processing a new incoming issue: + +- [ ] Is it a bug, feature request, question, or duplicate? +- [ ] Apply Tier 1 label +- [ ] Apply Tier 2 sub-label (for enhancements) +- [ ] Apply Tier 3 dimension label(s) if platform/integration/provider-specific +- [ ] Set project status (`No Status` for new items; maintainer sets `Backlog` when approved) +- [ ] Apply `status: needs-info` + comment if more information is needed +- [ ] Apply `priority: *` if urgency is clear + +--- + +*Maintainer community response guide: [docs/maintainer-guide.md](maintainer-guide.md)* +*Skill reference: [.agents/skills/nemoclaw-maintainer-community-response/SKILL.md](https://github.com/NVIDIA/NemoClaw/blob/main/.agents/skills/nemoclaw-maintainer-community-response/SKILL.md)* + +--- + +## Next Steps + +- [Maintainer Guide](maintainer-guide.md) — community response workflows and comment templates +- [Agent Skills](resources/agent-skills.md) — all available maintainer and user skills