docs(contributing): add engineering behavior guidance by cjagwani · Pull Request #6521 · NVIDIA/NemoClaw

cjagwani · 2026-07-09T00:27:03Z

Summary

Adds concise, always-applicable engineering behavior guidance for NemoClaw coding work. In response to maintainer review, the detailed posture now lives in the existing contributor workflow instead of an optional skill: assumptions and ambiguity are made reviewable, changes stay minimal and issue-scoped, outcomes receive narrow evidence, and QA-escaped defects address both the product root cause and the detection gap.

Related Issue

Fixes #6515.

Changes

Add one compact pointer to the contributor engineering posture in root AGENTS.md.
Integrate planning, scope, verification, and escaped-defect guidance into the relevant existing sections of CONTRIBUTING.md.
Remove the proposed optional skill and its catalog changes, following maintainer feedback that the posture should apply to every coding task.

Type of Change

Code change (feature, bug fix, or refactor)
Code change with doc updates
Doc only (prose changes, no code sample modifications)
Doc only (includes code sample changes)

Quality Gates

Tests added or updated for changed behavior
Existing tests cover changed behavior — justification:
Tests not applicable — justification: This is contributor-policy prose with no executable product behavior. Existing skill/frontmatter policy tests pass 36/36, and the repository skill validator passes all 19 skills after removal of the optional skill.
Docs updated for user-facing behavior changes
Docs not applicable — justification: The required documentation review confirmed no end-user NemoClaw behavior or docs/ page changes; this is internal contributor and coding-agent guidance.
Sensitive paths changed (security, policy, credentials, preflight, onboarding, inference, runner, sandbox, or messaging)
Sensitive-path review completed or maintainer-approved waiver recorded — reviewer/approval link/justification:
Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

Verification

PR description includes the DCO sign-off declaration and every commit appears as Verified in GitHub
Normal pre-commit, commit-msg, and pre-push hooks passed, or npm run check:diff passed when hooks were skipped or unavailable
Targeted behavior tests pass for the current change set, or tests are marked not applicable above — npx vitest run --project integration test/skills-frontmatter.test.ts test/maintainer-skills-policy.test.ts passed 36/36; validate_repo_skills.sh --repo . passed all 19 skills; local links passed for AGENTS.md and CONTRIBUTING.md.
Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — command/result: Not applicable to this focused prose-only change.
Quality Gates section completed with required justifications or waivers
No secrets, API keys, or credentials committed
npm run docs builds without warnings (doc changes only) — build passed with 0 errors; Fern reported the existing unauthenticated redirect-check and light-mode contrast warnings.
Doc pages follow the style guide (doc changes only)
New doc pages include SPDX header and frontmatter (new pages only)

Signed-off-by: cjagwani cjagwani@nvidia.com

Summary by CodeRabbit

Documentation
- Updated contributor guidance with clearer expectations for small, scoped changes, explicit assumptions, and observable success criteria.
- Expanded instructions for testing, regression evidence, and handling escaped defects.
- Added stronger pull request guidance to keep work focused, avoid unrelated cleanup, and document any scope changes.

github-actions · 2026-07-09T00:27:43Z

E2E Advisor Recommendation

Required E2E: None
Optional E2E: None

Workflow run

Full advisor summary

E2E Recommendation Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E

None. No E2E is recommended because this is a documentation-only PR affecting contributor/agent process guidance, with no changes to runtime behavior or E2E-relevant workflows. The deterministic risk plan lists no required jobs.

Optional E2E

None.

New E2E recommendations

None.

github-actions · 2026-07-09T00:27:44Z

E2E Target Recommendation

Required E2E targets: None
Optional E2E targets: None

Workflow run

Full E2E target advisor summary

E2E Target Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E targets

None. Documentation-only changes outside the E2E target workflow, registry, fixtures, support helpers, live tests, or target-relevant runtime paths cannot affect E2E target behavior.

Optional E2E targets

None.

Relevant changed files

None.

coderabbitai · 2026-07-09T00:27:49Z

📝 Walkthrough

Walkthrough

This PR updates AGENTS.md and CONTRIBUTING.md with expanded contributor guidance. AGENTS.md gains a new engineering-posture checklist step, while CONTRIBUTING.md adds instructions on defining success criteria, scoping changes, evidence-driven verification, and documenting escaped defects.

Changes

Contribution documentation updates

Layer / File(s)	Summary
AGENTS.md checklist step `AGENTS.md`	Adds an engineering-posture step to the "Before Making Changes" checklist, renumbering subsequent steps while preserving existing commands.
Where to Start guidance `CONTRIBUTING.md`	Adds instructions to define observable success criteria, change boundaries, document assumptions/alternatives, and constrain changes to the smallest direct adjustment.
Git hooks verification workflow `CONTRIBUTING.md`	Expands the prek hooks section with evidence-driven verification steps: mapping criteria to tests, reproducing defects, adding regression coverage, and clarifying rerun conditions.
Pull Requests scoping and defect documentation `CONTRIBUTING.md`	Adds rules for issue-scoped PRs, avoiding unrelated cleanup, disclosing scope deviations, and documenting escaped defects with root cause and prevention evidence.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Suggested labels: area: docs

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The described changes align with `#6515`: concise AGENTS guidance, expanded skill/procedure docs, and skill registration.
Out of Scope Changes check	✅ Passed	The summarized edits stay within the requested documentation and workflow guidance scope.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the documentation update adding engineering behavior guidance to contributor docs.

✨ Finishing Touches

📝 Generate docstrings

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch codex/engineering-behavior-guidelines

_{Comment @coderabbitai help to get the list of available commands.}

github-actions · 2026-07-09T00:29:01Z

PR Review Advisor (Nemotron Ultra) — Changes requested

Merge posture: Do not merge yet
Primary next action: Fix PRA-1: Missing required skill file: nemoclaw-contributor-engineering-guidelines; then add or justify PRA-T1.
Open items: 2 required · 1 warning · 0 suggestions · 2 test follow-ups
Since last review: 0 prior items resolved · 0 still apply · 3 new items found

Action checklist

PRA-1 Fix: Missing required skill file: nemoclaw-contributor-engineering-guidelines in .agents/skills/nemoclaw-contributor-engineering-guidelines/SKILL.md:1
PRA-2 Fix: Missing skill registration in skills guide in .agents/skills/nemoclaw-skills-guide/SKILL.md:58
PRA-3 Resolve or justify: PR description claims skill creation not reflected in diff in CONTRIBUTING.md:39
PRA-T1 Add or justify test follow-up: Acceptance clause
PRA-T2 Add or justify test follow-up: Acceptance clause

Findings index

ID	Severity	Category	Location	Required action
`PRA-1`	Required	acceptance	`.agents/skills/nemoclaw-contributor-engineering-guidelines/SKILL.md:1`	Add the missing skill file with the five principles, expanded procedures, and five examples as specified in issue #6515. Register it in the skills guide. Ensure skill frontmatter validation passes.
`PRA-2`	Required	acceptance	`.agents/skills/nemoclaw-skills-guide/SKILL.md:58`	Add the engineering-guidelines skill to the Contributor Skills table in nemoclaw-skills-guide/SKILL.md and update the Contributor role count from 5 to 6 in the role summary table.
`PRA-3`	Resolve/justify	docs	`CONTRIBUTING.md:39`	Either add the missing skill file and skills guide registration to this PR, or update the PR description to accurately reflect that only AGENTS.md and CONTRIBUTING.md are changed.

🚨 Required before merge

Address these before merging unless a maintainer explicitly overrides the advisor with rationale.

`PRA-1` Required — Missing required skill file: nemoclaw-contributor-engineering-guidelines

Location: .agents/skills/nemoclaw-contributor-engineering-guidelines/SKILL.md:1
Category: acceptance
Problem: Issue Add engineering behavior guidelines for contributors and coding agents #6515 acceptance criteria require a new skill file at .agents/skills/nemoclaw-contributor-engineering-guidelines/SKILL.md with expanded procedures and 5 concrete examples. This file does not exist in the current codebase. The PR diff only modifies AGENTS.md and CONTRIBUTING.md.
Impact: PR claims to fix Add engineering behavior guidelines for contributors and coding agents #6515 but does not deliver the primary deliverable (the contributor skill with procedures and examples). Contributors and coding agents cannot discover or load the engineering behavior guidance as a reusable skill.
Required action: Add the missing skill file with the five principles, expanded procedures, and five examples as specified in issue Add engineering behavior guidelines for contributors and coding agents #6515. Register it in the skills guide. Ensure skill frontmatter validation passes.
Expected follow-up: Fix before merge or get explicit maintainer override.
Verification: Check existence of .agents/skills/nemoclaw-contributor-engineering-guidelines/SKILL.md and run validate_repo_skills.sh
Missing regression test: Skill frontmatter validation and repo skill validator should pass for the new skill (already covered by existing test suite).
Done when: The required change is committed and verification passes: Check existence of .agents/skills/nemoclaw-contributor-engineering-guidelines/SKILL.md and run validate_repo_skills.sh.
Evidence: File system check confirms no nemoclaw-contributor-engineering-guidelines directory under .agents/skills/ Issue Add engineering behavior guidelines for contributors and coding agents #6515 acceptance criteria: 'nemoclaw-contributor-engineering-guidelines contains the expanded procedure and examples' PR description claims: 'Add nemoclaw-contributor-engineering-guidelines with a focused workflow, five requested examples'

`PRA-2` Required — Missing skill registration in skills guide

Location: .agents/skills/nemoclaw-skills-guide/SKILL.md:58
Category: acceptance
Problem: Issue Add engineering behavior guidelines for contributors and coding agents #6515 acceptance criteria require the new engineering-guidelines skill to be registered in the NemoClaw skills guide. The current skills guide shows only 4 contributor skills (onboard, create-pr, onboard-messaging-channel, update-docs) with Contributor count of 5 (1 user + 4 contributor). The engineering-guidelines skill is absent.
Impact: The skill is not discoverable through the skills catalog. Contributors and agents following the skills guide will not find the engineering behavior guidance. Contributor role count is incorrect (shows 5 instead of 6).
Required action: Add the engineering-guidelines skill to the Contributor Skills table in nemoclaw-skills-guide/SKILL.md and update the Contributor role count from 5 to 6 in the role summary table.
Expected follow-up: Fix before merge or get explicit maintainer override.
Verification: Check nemoclaw-skills-guide/SKILL.md Contributor Skills table for engineering-guidelines entry and role summary table count
Missing regression test: Skill frontmatter validation and repo skill validator should pass (existing test suite covers this).
Done when: The required change is committed and verification passes: Check nemoclaw-skills-guide/SKILL.md Contributor Skills table for engineering-guidelines entry and role summary table count.
Evidence: Current nemoclaw-skills-guide/SKILL.md shows 4 contributor skills, count of 5 Issue Add engineering behavior guidelines for contributors and coding agents #6515 acceptance criteria: 'The skill is registered in the NemoClaw skills guide' PR description claims: 'Register the skill and update contributor/maintainer counts in the NemoClaw skills guide'

Review findings by urgency: 2 required fixes, 1 item to resolve/justify, 0 in-scope improvements

⚠️ Resolve or justify before merge

Investigate these in the current review; either fix them, explain why they are not applicable, or document the accepted risk.

`PRA-3` Resolve/justify — PR description claims skill creation not reflected in diff

Location: CONTRIBUTING.md:39
Category: docs
Problem: PR description states 'Add nemoclaw-contributor-engineering-guidelines with a focused workflow, five requested examples' and 'Register the skill and update contributor/maintainer counts in the NemoClaw skills guide.' The actual diff only modifies AGENTS.md and CONTRIBUTING.md. No skill file or skills guide changes are present.
Impact: Reviewer and maintainers cannot verify the claimed work from the diff alone. Creates confusion about what the PR actually delivers vs. what it claims.
Recommended action: Either add the missing skill file and skills guide registration to this PR, or update the PR description to accurately reflect that only AGENTS.md and CONTRIBUTING.md are changed.
Expected follow-up: Resolve in this PR or explain why the risk is acceptable.
Verification: Compare PR description claims with git diff output
Missing regression test: N/A - documentation accuracy issue
Done when: The risk is fixed or explicitly justified in the PR. Verification: Compare PR description claims with git diff output.
Evidence: PR description claims skill creation and registration Git diff shows only AGENTS.md and CONTRIBUTING.md changes Commit d5a89f1 'feat(skills): add engineering behavior guidelines' in history but changes not in current head

💡 In-scope improvements

These are lower-risk, not throwaway. Prefer fixing them in this PR when they are local to changed code; defer only with rationale or a linked follow-up.

None.

Test follow-ups to resolve or justify

If these cover changed behavior, prefer adding them in this PR; otherwise state why existing coverage is enough or link the follow-up.

PRA-T1 Acceptance clause — nemoclaw-contributor-engineering-guidelines contains the expanded procedure and examples — add test evidence or identify existing coverage. File .agents/skills/nemoclaw-contributor-engineering-guidelines/SKILL.md does not exist in repository; directory absent
PRA-T2 Acceptance clause — The skill is registered in the NemoClaw skills guide — add test evidence or identify existing coverage. nemoclaw-skills-guide/SKILL.md shows only 4 contributor skills; engineering-guidelines absent; Contributor count shows 5 not 6

Since last review details

Current findings, using the urgency labels above:

`PRA-1` Required — Missing required skill file: nemoclaw-contributor-engineering-guidelines

Location: .agents/skills/nemoclaw-contributor-engineering-guidelines/SKILL.md:1
Category: acceptance
Problem: Issue Add engineering behavior guidelines for contributors and coding agents #6515 acceptance criteria require a new skill file at .agents/skills/nemoclaw-contributor-engineering-guidelines/SKILL.md with expanded procedures and 5 concrete examples. This file does not exist in the current codebase. The PR diff only modifies AGENTS.md and CONTRIBUTING.md.
Impact: PR claims to fix Add engineering behavior guidelines for contributors and coding agents #6515 but does not deliver the primary deliverable (the contributor skill with procedures and examples). Contributors and coding agents cannot discover or load the engineering behavior guidance as a reusable skill.
Required action: Add the missing skill file with the five principles, expanded procedures, and five examples as specified in issue Add engineering behavior guidelines for contributors and coding agents #6515. Register it in the skills guide. Ensure skill frontmatter validation passes.
Expected follow-up: Fix before merge or get explicit maintainer override.
Verification: Check existence of .agents/skills/nemoclaw-contributor-engineering-guidelines/SKILL.md and run validate_repo_skills.sh
Missing regression test: Skill frontmatter validation and repo skill validator should pass for the new skill (already covered by existing test suite).
Done when: The required change is committed and verification passes: Check existence of .agents/skills/nemoclaw-contributor-engineering-guidelines/SKILL.md and run validate_repo_skills.sh.
Evidence: File system check confirms no nemoclaw-contributor-engineering-guidelines directory under .agents/skills/ Issue Add engineering behavior guidelines for contributors and coding agents #6515 acceptance criteria: 'nemoclaw-contributor-engineering-guidelines contains the expanded procedure and examples' PR description claims: 'Add nemoclaw-contributor-engineering-guidelines with a focused workflow, five requested examples'

`PRA-2` Required — Missing skill registration in skills guide

Location: .agents/skills/nemoclaw-skills-guide/SKILL.md:58
Category: acceptance
Problem: Issue Add engineering behavior guidelines for contributors and coding agents #6515 acceptance criteria require the new engineering-guidelines skill to be registered in the NemoClaw skills guide. The current skills guide shows only 4 contributor skills (onboard, create-pr, onboard-messaging-channel, update-docs) with Contributor count of 5 (1 user + 4 contributor). The engineering-guidelines skill is absent.
Impact: The skill is not discoverable through the skills catalog. Contributors and agents following the skills guide will not find the engineering behavior guidance. Contributor role count is incorrect (shows 5 instead of 6).
Required action: Add the engineering-guidelines skill to the Contributor Skills table in nemoclaw-skills-guide/SKILL.md and update the Contributor role count from 5 to 6 in the role summary table.
Expected follow-up: Fix before merge or get explicit maintainer override.
Verification: Check nemoclaw-skills-guide/SKILL.md Contributor Skills table for engineering-guidelines entry and role summary table count
Missing regression test: Skill frontmatter validation and repo skill validator should pass (existing test suite covers this).
Done when: The required change is committed and verification passes: Check nemoclaw-skills-guide/SKILL.md Contributor Skills table for engineering-guidelines entry and role summary table count.
Evidence: Current nemoclaw-skills-guide/SKILL.md shows 4 contributor skills, count of 5 Issue Add engineering behavior guidelines for contributors and coding agents #6515 acceptance criteria: 'The skill is registered in the NemoClaw skills guide' PR description claims: 'Register the skill and update contributor/maintainer counts in the NemoClaw skills guide'

`PRA-3` Resolve/justify — PR description claims skill creation not reflected in diff

Location: CONTRIBUTING.md:39
Category: docs
Problem: PR description states 'Add nemoclaw-contributor-engineering-guidelines with a focused workflow, five requested examples' and 'Register the skill and update contributor/maintainer counts in the NemoClaw skills guide.' The actual diff only modifies AGENTS.md and CONTRIBUTING.md. No skill file or skills guide changes are present.
Impact: Reviewer and maintainers cannot verify the claimed work from the diff alone. Creates confusion about what the PR actually delivers vs. what it claims.
Recommended action: Either add the missing skill file and skills guide registration to this PR, or update the PR description to accurately reflect that only AGENTS.md and CONTRIBUTING.md are changed.
Expected follow-up: Resolve in this PR or explain why the risk is acceptable.
Verification: Compare PR description claims with git diff output
Missing regression test: N/A - documentation accuracy issue
Done when: The risk is fixed or explicitly justified in the PR. Verification: Compare PR description claims with git diff output.
Evidence: PR description claims skill creation and registration Git diff shows only AGENTS.md and CONTRIBUTING.md changes Commit d5a89f1 'feat(skills): add engineering behavior guidelines' in history but changes not in current head

Workflow run details

This is an automated, non-binding review; it still expects maintainers and agents to respond to each required or warning item. Treat suggestions as current-PR improvements when they touch changed code; defer only with maintainer rationale or a linked follow-up. A human maintainer must make the final merge decision.

github-actions · 2026-07-09T00:29:38Z

PR Review Advisor — Changes requested

Merge posture: Do not merge yet
Primary next action: Fix PRA-1: Linked issue acceptance still requires the contributor engineering-guidelines skill and catalog entry; then add or justify PRA-T1.
Open items: 1 required · 0 warnings · 0 suggestions · 3 test follow-ups
Since last review: 1 prior item resolved · 0 still apply · 1 new item found

Action checklist

PRA-1 Fix: Linked issue acceptance still requires the contributor engineering-guidelines skill and catalog entry in .agents/skills/nemoclaw-skills-guide/SKILL.md:86
PRA-T1 Add or justify test follow-up: Acceptance clause
PRA-T2 Add or justify test follow-up: Acceptance clause
PRA-T3 Add or justify test follow-up: Acceptance clause

Findings index

ID	Severity	Category	Location	Required action
`PRA-1`	Required	acceptance	`.agents/skills/nemoclaw-skills-guide/SKILL.md:86`	Either add `.agents/skills/nemoclaw-contributor-engineering-guidelines/SKILL.md` with the expanded procedure/examples and register it in `.agents/skills/nemoclaw-skills-guide/SKILL.md`, or update the checked-in docs/issue acceptance trail to reflect an agreed scope change before treating the issue as fixed.

🚨 Required before merge

Address these before merging unless a maintainer explicitly overrides the advisor with rationale.

`PRA-1` Required — Linked issue acceptance still requires the contributor engineering-guidelines skill and catalog entry

Location: .agents/skills/nemoclaw-skills-guide/SKILL.md:86
Category: acceptance
Problem: The linked issue requires both an expanded `nemoclaw-contributor-engineering-guidelines` skill with procedure/examples and registration in the skills guide, but the current PR only adds guidance to `AGENTS.md` and `CONTRIBUTING.md`; the skill file is absent and the catalog has no engineering-guidelines entry.
Impact: Merging this PR would close the linked issue while leaving two named acceptance clauses unimplemented, so contributors and agents would not have the independently discoverable expanded procedure/examples requested by the issue.
Required action: Either add `.agents/skills/nemoclaw-contributor-engineering-guidelines/SKILL.md` with the expanded procedure/examples and register it in `.agents/skills/nemoclaw-skills-guide/SKILL.md`, or update the checked-in docs/issue acceptance trail to reflect an agreed scope change before treating the issue as fixed.
Expected follow-up: Fix before merge or get explicit maintainer override.
Verification: Read `.agents/skills/nemoclaw-skills-guide/SKILL.md` contributor catalog and check for `.agents/skills/nemoclaw-contributor-engineering-guidelines/SKILL.md`.
Missing regression test: If the skill is added, rely on or extend `test/skills-frontmatter.test.ts` and `test/maintainer-skills-policy.test.ts` so the new skill frontmatter, body, and catalog/policy invariants are covered.
Done when: The required change is committed and verification passes: Read `.agents/skills/nemoclaw-skills-guide/SKILL.md` contributor catalog and check for `.agents/skills/nemoclaw-contributor-engineering-guidelines/SKILL.md`.
Evidence: Linked issue Add engineering behavior guidelines for contributors and coding agents #6515 Acceptance Criteria include: `nemoclaw-contributor-engineering-guidelines` contains the expanded procedure and examples. Linked issue Add engineering behavior guidelines for contributors and coding agents #6515 Acceptance Criteria include: The skill is registered in the NemoClaw skills guide. Read-only repository check returned: No files found matching `.agents/skills/nemoclaw-contributor-engineering-guidelines/**`. `.agents/skills/nemoclaw-skills-guide/SKILL.md` contributor catalog lists onboard, create-pr, onboard-messaging-channel, and update-docs, with no engineering-guidelines entry.

Test follow-ups to resolve or justify

If these cover changed behavior, prefer adding them in this PR; otherwise state why existing coverage is enough or link the follow-up.

PRA-T1 Acceptance clause — `nemoclaw-contributor-engineering-guidelines` contains the expanded procedure and examples. — add test evidence or identify existing coverage. Read-only repository inspection found no `.agents/skills/nemoclaw-contributor-engineering-guidelines/**` file in the current checkout; covered by F-001.
PRA-T2 Acceptance clause — The skill is registered in the NemoClaw skills guide. — add test evidence or identify existing coverage. `.agents/skills/nemoclaw-skills-guide/SKILL.md` contributor catalog lists the existing contributor skills but has no `engineering-guidelines` entry; covered by F-001.
PRA-T3 Acceptance clause — Existing skill frontmatter and policy validation tests pass. — add test evidence or identify existing coverage. The PR body claims validation commands passed, but this review did not execute tests and does not treat PR-provided command output as proof. No skill files are changed in the current diff unless F-001 is resolved by adding the requested skill.

Since last review details

Current findings, using the urgency labels above:

`PRA-1` Required — Linked issue acceptance still requires the contributor engineering-guidelines skill and catalog entry

Location: .agents/skills/nemoclaw-skills-guide/SKILL.md:86
Category: acceptance
Problem: The linked issue requires both an expanded `nemoclaw-contributor-engineering-guidelines` skill with procedure/examples and registration in the skills guide, but the current PR only adds guidance to `AGENTS.md` and `CONTRIBUTING.md`; the skill file is absent and the catalog has no engineering-guidelines entry.
Impact: Merging this PR would close the linked issue while leaving two named acceptance clauses unimplemented, so contributors and agents would not have the independently discoverable expanded procedure/examples requested by the issue.
Required action: Either add `.agents/skills/nemoclaw-contributor-engineering-guidelines/SKILL.md` with the expanded procedure/examples and register it in `.agents/skills/nemoclaw-skills-guide/SKILL.md`, or update the checked-in docs/issue acceptance trail to reflect an agreed scope change before treating the issue as fixed.
Expected follow-up: Fix before merge or get explicit maintainer override.
Verification: Read `.agents/skills/nemoclaw-skills-guide/SKILL.md` contributor catalog and check for `.agents/skills/nemoclaw-contributor-engineering-guidelines/SKILL.md`.
Missing regression test: If the skill is added, rely on or extend `test/skills-frontmatter.test.ts` and `test/maintainer-skills-policy.test.ts` so the new skill frontmatter, body, and catalog/policy invariants are covered.
Done when: The required change is committed and verification passes: Read `.agents/skills/nemoclaw-skills-guide/SKILL.md` contributor catalog and check for `.agents/skills/nemoclaw-contributor-engineering-guidelines/SKILL.md`.
Evidence: Linked issue Add engineering behavior guidelines for contributors and coding agents #6515 Acceptance Criteria include: `nemoclaw-contributor-engineering-guidelines` contains the expanded procedure and examples. Linked issue Add engineering behavior guidelines for contributors and coding agents #6515 Acceptance Criteria include: The skill is registered in the NemoClaw skills guide. Read-only repository check returned: No files found matching `.agents/skills/nemoclaw-contributor-engineering-guidelines/**`. `.agents/skills/nemoclaw-skills-guide/SKILL.md` contributor catalog lists onboard, create-pr, onboard-messaging-channel, and update-docs, with no engineering-guidelines entry.

Workflow run details

This is an automated, non-binding review; it still expects maintainers and agents to respond to each required or warning item. Treat suggestions as current-PR improvements when they touch changed code; defer only with maintainer rationale or a linked follow-up. A human maintainer must make the final merge decision.

cjagwani · 2026-07-09T00:30:32Z

Advisor follow-up:

PRA-1 is resolved: docs(skills): add engineering behavior guidelines #6519 has been closed by its author, so docs(contributing): add engineering behavior guidance #6521 is now the only active implementation linked to Add engineering behavior guidelines for contributors and coding agents #6515.
PRA-T1 evidence: npx vitest run --project integration test/skills-frontmatter.test.ts test/maintainer-skills-policy.test.ts passed 37/37 tests; the dependency-free repository validator passed all 20 skills; and the skill-creator structural validator passed.

cv

I don't think this should be a skill that optionally loads, but a mention in AGENTS.md and the fuller text permeating CONTRIBUTING.md where applicable. Ideally this isn't even a section in them, but the posture and principles are spread throughout (sans repetition, of course)

cjagwani · 2026-07-09T19:25:45Z

Addressed the requested design change from this review at exact head 4b278bd3:

removed the optional engineering-guidelines skill and restored the skill catalog to main;
kept one compact, always-applicable reminder in AGENTS.md;
distributed the fuller posture through the existing planning, verification, and pull-request sections of CONTRIBUTING.md, without adding a standalone section.

The GPT and Nemotron advisor items asking to restore the skill follow the issue's original implementation wording, but that scope is intentionally superseded by the maintainer review above. Restoring the optional skill would contradict the requested always-on design.

Validation on this head: 36/36 focused tests, 19/19 repository skills, local Markdown links, npm run docs with 0 errors, and npm run check:diff; required CI and automated reviews are settled. @cv, please re-review the revised shape.

## Summary Adds concise, always-applicable engineering behavior guidance for NemoClaw coding work. In response to maintainer review, the detailed posture now lives in the existing contributor workflow instead of an optional skill: assumptions and ambiguity are made reviewable, changes stay minimal and issue-scoped, outcomes receive narrow evidence, and QA-escaped defects address both the product root cause and the detection gap. ## Related Issue Fixes NVIDIA#6515. ## Changes - Add one compact pointer to the contributor engineering posture in root `AGENTS.md`. - Integrate planning, scope, verification, and escaped-defect guidance into the relevant existing sections of `CONTRIBUTING.md`. - Remove the proposed optional skill and its catalog changes, following maintainer feedback that the posture should apply to every coding task. ## Type of Change - [ ] Code change (feature, bug fix, or refactor) - [ ] Code change with doc updates - [x] Doc only (prose changes, no code sample modifications) - [ ] Doc only (includes code sample changes) ## Quality Gates  - [ ] Tests added or updated for changed behavior - [ ] Existing tests cover changed behavior — justification: - [x] Tests not applicable — justification: This is contributor-policy prose with no executable product behavior. Existing skill/frontmatter policy tests pass 36/36, and the repository skill validator passes all 19 skills after removal of the optional skill. - [ ] Docs updated for user-facing behavior changes - [x] Docs not applicable — justification: The required documentation review confirmed no end-user NemoClaw behavior or `docs/` page changes; this is internal contributor and coding-agent guidance. - [ ] Sensitive paths changed (security, policy, credentials, preflight, onboarding, inference, runner, sandbox, or messaging) - [ ] Sensitive-path review completed or maintainer-approved waiver recorded — reviewer/approval link/justification: - [ ] Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue: ## Verification  - [x] PR description includes the DCO sign-off declaration and every commit appears as `Verified` in GitHub - [x] Normal `pre-commit`, `commit-msg`, and `pre-push` hooks passed, or `npm run check:diff` passed when hooks were skipped or unavailable - [x] Targeted behavior tests pass for the current change set, or tests are marked not applicable above — `npx vitest run --project integration test/skills-frontmatter.test.ts test/maintainer-skills-policy.test.ts` passed 36/36; `validate_repo_skills.sh --repo .` passed all 19 skills; local links passed for `AGENTS.md` and `CONTRIBUTING.md`. - [ ] Applicable broad gate passed — `npm test` for broad runtime/test-harness changes; `npm run check` for repo-wide validation/coverage changes — command/result: Not applicable to this focused prose-only change. - [x] Quality Gates section completed with required justifications or waivers - [x] No secrets, API keys, or credentials committed - [ ] `npm run docs` builds without warnings (doc changes only) — build passed with 0 errors; Fern reported the existing unauthenticated redirect-check and light-mode contrast warnings. - [x] Doc pages follow the [style guide](https://github.com/NVIDIA/NemoClaw/blob/main/docs/CONTRIBUTING.md) (doc changes only) - [ ] New doc pages include SPDX header and frontmatter (new pages only) ---  Signed-off-by: cjagwani <cjagwani@nvidia.com>  ## Summary by CodeRabbit * **Documentation** * Updated contributor guidance with clearer expectations for small, scoped changes, explicit assumptions, and observable success criteria. * Expanded instructions for testing, regression evidence, and handling escaped defects. * Added stronger pull request guidance to keep work focused, avoid unrelated cleanup, and document any scope changes.

feat(skills): add engineering behavior guidelines

d5a89f1

cjagwani added area: skills Skills, agent behaviors, prompts, or skill packaging v0.0.79 labels Jul 9, 2026

cjagwani self-assigned this Jul 9, 2026

Merge branch 'main' into codex/engineering-behavior-guidelines

5d92a7a

cjagwani requested a review from cv July 9, 2026 05:06

cv requested changes Jul 9, 2026

View reviewed changes

jyaunches added v0.0.80 and removed v0.0.79 labels Jul 9, 2026

cjagwani added 2 commits July 9, 2026 12:13

merge: sync current main

889baff

docs(contributing): add engineering behavior guidance

4b278bd

cjagwani changed the title ~~feat(skills): add engineering behavior guidelines~~ docs(contributing): add engineering behavior guidance Jul 9, 2026

cjagwani requested a review from cv July 9, 2026 19:25

cv approved these changes Jul 9, 2026

View reviewed changes

cv merged commit 614122b into main Jul 9, 2026
39 of 45 checks passed

cv deleted the codex/engineering-behavior-guidelines branch July 9, 2026 19:35

coderabbitai Bot mentioned this pull request Jul 20, 2026

feat: add notebooklm auto export script and workflow #7220

Closed

21 tasks

jyaunches mentioned this pull request Aug 4, 2026

Use the same engineering checks during planning, implementation, and PR review #8240

Open

10 tasks

Uh oh!

Conversation

cjagwani commented Jul 9, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Related Issue

Changes

Type of Change

Quality Gates

Verification

Summary by CodeRabbit

Uh oh!

github-actions Bot commented Jul 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

E2E Advisor Recommendation

E2E Recommendation Advisor

Required E2E

Optional E2E

New E2E recommendations

Uh oh!

github-actions Bot commented Jul 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

E2E Target Recommendation

E2E Target Advisor

Required E2E targets

Optional E2E targets

Relevant changed files

Uh oh!

coderabbitai Bot commented Jul 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Uh oh!

github-actions Bot commented Jul 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Review Advisor (Nemotron Ultra) — Changes requested

Action checklist

Findings index

🚨 Required before merge

PRA-1 Required — Missing required skill file: nemoclaw-contributor-engineering-guidelines

PRA-2 Required — Missing skill registration in skills guide

⚠️ Resolve or justify before merge

PRA-3 Resolve/justify — PR description claims skill creation not reflected in diff

💡 In-scope improvements

PRA-1 Required — Missing required skill file: nemoclaw-contributor-engineering-guidelines

PRA-2 Required — Missing skill registration in skills guide

PRA-3 Resolve/justify — PR description claims skill creation not reflected in diff

Uh oh!

github-actions Bot commented Jul 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Review Advisor — Changes requested

Action checklist

Findings index

🚨 Required before merge

PRA-1 Required — Linked issue acceptance still requires the contributor engineering-guidelines skill and catalog entry

PRA-1 Required — Linked issue acceptance still requires the contributor engineering-guidelines skill and catalog entry

Uh oh!

cjagwani commented Jul 9, 2026

Uh oh!

cv left a comment

Choose a reason for hiding this comment

Uh oh!

cjagwani commented Jul 9, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

cjagwani commented Jul 9, 2026 •

edited by coderabbitai Bot

Loading

github-actions Bot commented Jul 9, 2026 •

edited

Loading

github-actions Bot commented Jul 9, 2026 •

edited

Loading

coderabbitai Bot commented Jul 9, 2026 •

edited

Loading

github-actions Bot commented Jul 9, 2026 •

edited

Loading

`PRA-1` Required — Missing required skill file: nemoclaw-contributor-engineering-guidelines

`PRA-2` Required — Missing skill registration in skills guide

`PRA-3` Resolve/justify — PR description claims skill creation not reflected in diff

`PRA-1` Required — Missing required skill file: nemoclaw-contributor-engineering-guidelines

`PRA-2` Required — Missing skill registration in skills guide

`PRA-3` Resolve/justify — PR description claims skill creation not reflected in diff

github-actions Bot commented Jul 9, 2026 •

edited

Loading

`PRA-1` Required — Linked issue acceptance still requires the contributor engineering-guidelines skill and catalog entry

`PRA-1` Required — Linked issue acceptance still requires the contributor engineering-guidelines skill and catalog entry