Skip to content

Commit dc5d714

Browse files
prekshivyasprekshivyas
authored
Merge branch 'main' into feat/verify-stale-skill
2 parents 4ee3750 + eacfd1f commit dc5d714

586 files changed

Lines changed: 26706 additions & 8458 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.agents/skills/nemoclaw-contributor-create-pr/SKILL.md‎

Lines changed: 16 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -37,14 +37,25 @@ Before creating a PR, verify the branch.
3737

3838
## Step 2: Run Pre-PR Checks
3939

40-
Run both checks and confirm they pass before proceeding. Do not skip this step.
40+
Choose checks based on the files changed.
41+
42+
For code changes, run both checks and confirm they pass before proceeding:
4143

4244
```bash
4345
npx prek run --all-files
4446
npm test
4547
```
4648

47-
If either fails, fix the issues before creating the PR.
49+
For doc-only changes, do not run the full test suite unless the docs change requires it.
50+
Run the docs and hook checks instead:
51+
52+
```bash
53+
npx prek run --all-files
54+
make docs
55+
```
56+
57+
If a required check fails, fix the issue before creating the PR.
58+
When preparing the PR body for a doc-only change, leave the `npm test` verification box unchecked unless you actually ran it.
4859

4960
## Step 3: Push the Branch
5061

@@ -117,7 +128,7 @@ Use the exact template structure below. Fill in each section based on the diff (
117128
- [ ] Doc only (includes code sample changes)
118129

119130
## Verification
120-
<!-- Check each item you ran and confirmed. Leave unchecked items you skipped. -->
131+
<!-- Check each item you ran and confirmed. Leave unchecked items you skipped. Doc-only changes do not require npm test unless you ran it. -->
121132
- [ ] `npx prek run --all-files` passes
122133
- [ ] `npm test` passes
123134
- [ ] Tests added or updated for new or changed behavior
@@ -140,7 +151,7 @@ Follow these rules when filling in the template:
140151
- **Related Issue:** Include `Fixes #NNN` or `Closes #NNN` if an issue exists. Remove the section entirely if there is no related issue.
141152
- **Changes:** Bullet list of key changes. Be specific — reference file names, commands, or behaviors that changed.
142153
- **Type of Change:** Check exactly one box. Use `[x]` for checked, `[ ]` for unchecked.
143-
- **Verification:** Check only the boxes for steps you actually ran and confirmed passing. Do not check boxes for steps you skipped or did not verify.
154+
- **Verification:** Check only the boxes for steps you actually ran and confirmed passing. Do not check boxes for steps you skipped or did not verify. For doc-only changes, `npm test` is not required; leave it unchecked unless you ran it.
144155
- **DCO Sign-Off:** Replace `{name}` and `{email}` with values from `git config user.name` and `git config user.email`.
145156

146157
## Step 6: Create the PR
@@ -187,6 +198,7 @@ Created PR [#NNN](https://github.com/NVIDIA/NemoClaw/pull/NNN)
187198
- **Do not invent your own PR body format.** Use the template from Step 5 exactly.
188199
- **Do not omit sections.** Even if a section is not applicable, keep it with the "Skip if..." comment.
189200
- **Do not check boxes for steps you did not run.** If you did not run `make docs`, leave that box unchecked.
201+
- **Do not run the full test suite for doc-only changes by default.** Run docs and hook checks instead, and leave `npm test` unchecked unless you actually ran it.
190202
- **Do not forget the DCO sign-off.** CI will reject the PR without it.
191203
- **Do not forget `--assignee @me`.** Every PR must be assigned to its creator.
192204
- **Do not create PRs from main.** Always use a feature branch.

‎.agents/skills/nemoclaw-contributor-update-docs/SKILL.md‎

Lines changed: 39 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
name: nemoclaw-contributor-update-docs
3-
description: Scan recent git commits for changes that affect user-facing behavior, then draft or update the corresponding documentation pages. Use when docs have fallen behind code changes, after a batch of features lands, or when preparing a release. Trigger keywords - update docs, draft docs, docs from commits, sync docs, catch up docs, doc debt, docs behind, docs drift.
3+
description: Scan recent git commits for changes that affect user-facing behavior, then draft or update the corresponding documentation pages and refresh generated user skills for release prep. Use when docs have fallen behind code changes, after a batch of features lands, during daily release prep, or when preparing a release. Trigger keywords - update docs, draft docs, docs from commits, sync docs, catch up docs, doc debt, docs behind, docs drift, release prep docs, refresh user skills.
44
---
55

66
# Update Docs from Commits
@@ -16,6 +16,7 @@ Scan recent git history for commits that affect user-facing behavior and draft d
1616

1717
- After a batch of features or fixes has landed and docs may be stale.
1818
- Before a release, to catch any doc gaps.
19+
- During daily release prep, before opening the docs refresh PR.
1920
- When a contributor asks "what docs need updating?"
2021

2122
## Step 0: Load the Skip List
@@ -154,7 +155,21 @@ After drafting all updates, present a summary to the user:
154155
- `test: add launch command test` (def5678) — test-only change.
155156
```
156157

157-
## Step 7: Build and Verify
158+
## Step 7: Apply Release Prep Updates
159+
160+
Skip this step when the user only asked for ordinary doc catch-up and no release prep is involved.
161+
162+
If the user invoked this skill for release prep, finish the release-specific doc work before verification:
163+
164+
1. Make any requested doc version bumps in `versions1.json` and `project.json` in the `docs/` directory.
165+
2. Determine the release label from the release version. Release labels use `vX.Y.Z` format. For example, if `docs/project.json` has `"version": "0.0.37"`, the release label is `v0.0.37`. Use the version requested by the user if one was provided; otherwise use the version in `docs/project.json` after the bump.
166+
3. Refresh the NemoClaw user skills:
167+
168+
```bash
169+
python3 scripts/docs-to-skills.py docs/ .agents/skills/ --prefix nemoclaw-user
170+
```
171+
172+
## Step 9: Build and Verify
158173

159174
After making changes, build the docs locally:
160175

@@ -167,15 +182,20 @@ Check for:
167182
- Build warnings or errors.
168183
- Broken cross-references.
169184
- Correct rendering of new content.
185+
- Generated skill changes that do not correspond to source doc changes.
170186

171-
## Step 8: Label PRs
187+
## Step 10: Open the Docs PR
172188

173-
When the workflow produces a pull request, apply the `documentation` label so reviewers can identify doc-only changes:
189+
Commit changes and open a pull request with a concise summary of the doc updates and a source summary that links each identified merged PR to its matching doc page. Include the PR number, affected doc page, links, and description of the doc change in this shape:
174190

175-
```bash
176-
gh pr edit <number> --add-label documentation
191+
```markdown
192+
- #<doc-impacting-PR-number> -> `docs/path.md`: Description of the doc change reflecting the source code changes in the PR.
177193
```
178194

195+
Apply the `documentation` label and the corresponding release label so reviewers can identify doc-only changes for the target release.
196+
When creating the PR with `gh pr create`, pass both labels, for example `--label documentation --label v0.0.37`.
197+
If the release label does not exist, report that instead of substituting another label.
198+
179199
## Tips
180200

181201
- When in doubt about whether a commit needs a doc update, check if the commit message references a CLI flag, config option, or user-visible behavior.
@@ -184,14 +204,23 @@ gh pr edit <number> --add-label documentation
184204
- PRs that are purely internal refactors with no behavior change do not need doc updates, even if they touch high-signal directories.
185205
- To suppress documentation for a merged feature that is not ready for public docs, add it to `docs/.docs-skip`. Remove the entry once the feature is ready to document.
186206

187-
## Example Usage
207+
## Summary of Steps
188208

189209
User says: "Catch up the docs for everything merged since v0.1.0."
190210

191211
1. Run `git log v0.1.0..HEAD --oneline --no-merges --name-only`.
192212
2. Filter to `feat`, `fix`, `refactor`, `perf` commits touching user-facing code.
193213
3. Map each to a doc page.
194214
4. Read the commit diffs and current doc pages.
195-
5. Draft updates following the style guide.
196-
6. Present the summary.
197-
7. Build with `make docs` to verify.
215+
5. Draft doc updates reflecting the source code changes in the commits following the style guide.
216+
6. **Release prep only:** Apply release-prep version bumps if the user requested release prep.
217+
7. **Release prep only:** Run `python3 scripts/docs-to-skills.py docs/ .agents/skills/ --prefix nemoclaw-user`.
218+
8. Present the summary.
219+
9. Build with `make docs` to verify.
220+
10. **Release prep only:** Commit changes and open a pull request with the `documentation` label and the corresponding `vX.Y.Z` release label. Include a concise summary of the doc updates and a source summary that links each identified merged PR to its matching doc page. Include the PR number, affected doc page, links, and description of the doc change in this shape:
221+
222+
```markdown
223+
- #<doc-impacting-PR-number> -> `docs/path.md`: Description of the doc change reflecting the source code changes in the PR.
224+
```
225+
226+
If the release label does not exist, report that the PR was created without the release label or that PR creation failed because the label was missing.

‎.agents/skills/nemoclaw-maintainer-cross-issue-sweep/SKILL.md‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
---
2+
name: nemoclaw-maintainer-cross-issue-sweep
3+
description: Scans other open issues to find ones a given PR may also fix or accidentally break. Outputs adjacent-fix opportunities and contradiction risks with file:line evidence. Use when reviewing a PR to discover bundling opportunities or downstream impact across the issue queue.
4+
user_invocable: true
5+
---
6+
7+
# Cross-Issue Regression Sweep
8+
9+
Surfaces the issues a single PR may also fix or accidentally break beyond the one it claims to address. Two outputs:
10+
11+
- **Adjacent fixes** — "PR may also close #X" → bundling intel (ship one PR, close multiple issues)
12+
- **Contradicting risks** — "PR may break what #Y wants" → coordination needed before merge
13+
14+
## Prerequisites
15+
16+
- `gh` CLI authenticated
17+
- A target repository with open issues
18+
- An open PR to scan
19+
20+
## Repo policy
21+
22+
Defaults assume NemoClaw conventions. Edit `repo-policy.md` to override per-repo (bot logins, candidate caps, language regex).
23+
24+
## Workflow
25+
26+
Copy this checklist into your response and check off each step:
27+
28+
```text
29+
Cross-issue sweep progress:
30+
- [ ] Step 1: Extract fingerprint (files, symbols, error strings, primary issue)
31+
- [ ] Step 2: Search candidate issues (capped at 30, primary excluded)
32+
- [ ] Step 3: Classify each candidate (4-class with evidence)
33+
- [ ] Step 4: Apply reverse-link boost
34+
- [ ] Step 5: Filter (drop UNRELATED, SAME_ISSUE_DIFF, low-confidence)
35+
- [ ] Step 6: Render report using templates/report.md
36+
```
37+
38+
### Step 1: Extract fingerprint
39+
40+
```bash
41+
scripts/extract-fingerprint.sh <pr-number>
42+
```
43+
44+
Pulls four dimensions: touched files, touched symbols (per-language regex), error-string tokens, and the PR's primary linked issue (for exclusion). See `checks/fingerprint-extraction.md`.
45+
46+
### Step 2: Search candidate issues
47+
48+
```bash
49+
scripts/search-candidate-issues.sh <fingerprint-json>
50+
```
51+
52+
Three search dimensions, capped at 30 total candidates:
53+
54+
- Per symbol: top 10 by recency
55+
- Per file path: top 5 by recency
56+
- Per error string: top 5 by recency
57+
58+
Dedupes; excludes the PR's primary linked issue.
59+
60+
### Step 3: Classify each candidate
61+
62+
For each candidate, the LLM classifies as one of four classes per `checks/relationship-judgment.md`:
63+
64+
- **ADJACENT_FIX** — PR's changes likely also resolve this issue
65+
- **CONTRADICTING** — PR's approach blocks what this issue wants
66+
- **SAME_ISSUE_DIFF** — same root bug as PR's primary issue (dedup filter)
67+
- **UNRELATED** — no meaningful relationship
68+
69+
Required for ADJACENT_FIX or CONTRADICTING:
70+
71+
- Cite specific PR diff line
72+
- Cite specific issue symptom
73+
- Confidence: high / medium / low
74+
75+
If no specific evidence can be cited, the LLM must answer UNRELATED. This floors hallucination.
76+
77+
### Step 4: Reverse-link boost
78+
79+
If the candidate issue's body or comments already mention this PR's number, the relationship is already in someone's mental model. Boost confidence by one tier (low → medium, medium → high).
80+
81+
### Step 5: Filter
82+
83+
- Suppress UNRELATED + SAME_ISSUE_DIFF
84+
- Drop low-confidence judgments
85+
- Keep ADJACENT_FIX and CONTRADICTING with high or medium confidence
86+
87+
### Step 6: Render report
88+
89+
```bash
90+
scripts/render-report.py < classifications.json
91+
```
92+
93+
See `templates/report.md` for the format.
94+
95+
## Reference files
96+
97+
- `repo-policy.md` — configurable per-repo defaults
98+
- `relationship-rules.md` — 4-class definitions with worked examples
99+
- `checks/fingerprint-extraction.md` — what to pull from the diff, per language
100+
- `checks/relationship-judgment.md` — LLM judgment criteria + evidence requirement
101+
- `templates/report.md` — output template
102+
- `validation/backtest.md` — backtest the skill against historical PRs
103+
104+
## Scripts (execute, do not read)
105+
106+
- `scripts/extract-fingerprint.sh` — symbols + paths + error strings, deterministic
107+
- `scripts/search-candidate-issues.sh` — GitHub Search wrapper, dedupe, cap
108+
- `scripts/render-report.py` — report renderer
109+
110+
## Composition with other skills
111+
112+
The pr-comparator (`nemoclaw-maintainer-pr-comparator`) calls this skill as a sub-step when comparing competing PRs. Adjacent-fix counts feed Tier 3 tiebreakers; contradicting hits factor into Tier 2 quality scoring.
113+
114+
## What this skill does NOT do (deferred)
115+
116+
These would raise the ceiling but require infrastructure beyond GitHub API + LLM:
117+
118+
- Run PR code against adversarial inputs (sandboxed)
119+
- Static-analyzer dataflow tracing (CodeQL, Semgrep)
120+
- ML-based symbol disambiguation across codebases

‎.agents/skills/nemoclaw-maintainer-cross-issue-sweep/checks/fingerprint-extraction.md‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
# Fingerprint Extraction
2+
3+
What to pull from the PR diff and how. Run `scripts/extract-fingerprint.sh <pr>` to do this mechanically.
4+
5+
## Contents
6+
7+
- Touched files (paths)
8+
- Touched symbols (per-language)
9+
- Error-string tokens
10+
- Primary linked issue
11+
12+
## Touched files
13+
14+
From `gh pr view <pr> --json files`. Filter to source paths (drop test fixtures, generated files, lockfiles).
15+
16+
**Why baseline:** Some issues mention a file path but no symbol. Without file matching, those go uncaught.
17+
18+
## Touched symbols
19+
20+
Per-language regex against added/modified lines in the diff. Defaults live in `repo-policy.md`.
21+
22+
**Why this is the killer angle:** Most matchers stop at file paths. A user issue saying "validateInput rejects empty strings" pinpoints a function — file-path matching alone misses it if the function is in a different module than expected.
23+
24+
**Filtering rules:**
25+
26+
- Only extract symbols from added/modified lines, not deleted lines (those are going away)
27+
- Drop common short names (`do`, `if`, `as`) — too noisy
28+
- Drop language keywords
29+
- Drop test-helper names (`describe`, `it`, `test`) — they match too many issues
30+
31+
## Error-string tokens
32+
33+
Strings inside:
34+
35+
- `throw new Error("...")` / `throw Error("...")`
36+
- `console.error("...")`
37+
- `print(f"...")` / Python f-strings flagged with error-shape (`Error:`, `Failed`)
38+
- Distinctive flag/option names (`--no-color`, `--verbose`)
39+
40+
**Why this catches symptoms:** When a user files an issue, they often paste the error message they saw. That string is high-info and rarely false-matches.
41+
42+
**Filtering rules:**
43+
44+
- Skip strings <8 chars (too generic)
45+
- Skip strings with no alpha chars
46+
- Strip placeholders (`%s`, `${var}`, `{0}`) before searching
47+
48+
## Primary linked issue
49+
50+
From the PR body, parse:
51+
52+
- `closes #N` / `fixes #N` / `resolves #N`
53+
- `Linked Issue: #N` block
54+
55+
Captured for **exclusion** during search. Without this, every PR self-matches its own issue.
56+
57+
## Output
58+
59+
Fingerprint JSON shape:
60+
61+
```json
62+
{
63+
"pr": 2851,
64+
"files": ["src/lib/shields.ts", "Dockerfile.base"],
65+
"symbols": ["normalize_mutable_config_perms", "applyStateDirLockMode"],
66+
"error_strings": ["EACCES on .openclaw"],
67+
"primary_issue": 2681
68+
}
69+
```
70+
71+
Consumed by `scripts/search-candidate-issues.sh`.

0 commit comments

Comments
 (0)