skill: tighten PR-description and CI-authoring guidance for agents

skills/cuopt-developer/SKILL.md

@@ -10,7 +10,7 @@ Contribute to the NVIDIA cuOpt codebase. This skill is for modifying cuOpt itsel
 
 **If you just want to USE cuOpt**, switch to the appropriate problem skill (cuopt-routing, cuopt-lp-milp, etc.)
 
-**First-time dev environment setup?** See [resources/first_time_setup.md](resources/first_time_setup.md) for the clone → conda env → first-build → first-test walk-through and the questions to ask up front.
+**First-time dev environment setup?** See [resources/first_time_setup.md](resources/first_time_setup.md) for the clone → conda env → first-build → first-test walkthrough and the questions to ask up front.
 
 ---
 
@@ -202,7 +202,7 @@ cuOpt uses Cython to bridge Python and C++. See [resources/python_bindings.md](r
 
 ## Contributing — Commits, PRs, Common Tasks
 
-For pre-commit setup, DCO sign-off (`git commit -s`), the fork-based PR workflow, the draft-PR rule for agents, and step-by-step common-task recipes (adding a solver parameter, dependency, server endpoint, or CUDA kernel), see [resources/contributing.md](resources/contributing.md).
+For pre-commit setup, DCO sign-off (`git commit -s`), the fork-based PR workflow, the draft-PR rule for agents, PR-description rules (keep it short — no "how it works" walkthroughs or file tables), script and CI/workflow authoring principles (extend existing files before adding new ones; no speculative flags, restated defaults, or silent fallbacks), and step-by-step common-task recipes (adding a solver parameter, dependency, server endpoint, or CUDA kernel), see [resources/contributing.md](resources/contributing.md).
 
 ## Coding Conventions
 

skills/cuopt-developer/resources/contributing.md

@@ -55,7 +55,25 @@ When an AI agent creates a pull request, it **must be a draft PR** (`gh pr creat
 
 ### PR Descriptions
 
-Keep PR summaries **short and informative**. State what changed and why in a few bullet points. Avoid verbose explanations, full file listings, or restating the diff. Reviewers read the code — the summary should give them context, not a transcript.
+Keep summaries short — a paragraph or 3–5 bullets stating *what* and *why*. Skim recent merges on the target branch to calibrate.
+
+Skip how-it-works walkthroughs, file-by-file tables, exhaustive test-plan checklists, prose restatements of the diff, and screenshots of output the reviewer can reproduce locally. Reviewers read the code; long structured summaries signal LLM-generated and erode trust.
+
+For extra context (a design decision, unusual constraint, follow-up), one or two sentences with a link to an issue or doc beats expanding the body.
+
+### Writing scripts and CI workflows
+
+Shell scripts, Python helper tools, and CI workflows all attract speculative complexity — flags, fallbacks, and config knobs that "might be useful" but trace back to no real problem. Strip it.
+
+- Prefer extending an existing script over adding a new one. If you add a new file, be ready to say why an existing one didn't fit.
+- Every flag, option, env-var override, and configuration knob needs a concrete failure mode it prevents. If you can't name one, drop it.
+- Don't restate framework or platform defaults — it implies the default was wrong and confuses readers.
+- Make required inputs strict: fail loudly when they're missing instead of silently defaulting. Silent fallbacks turn into "this has been broken for months" bugs.
+- Validate inputs at the top, before any expensive work, so misconfiguration surfaces fast.
+- Keep the source readable: one shell command per line over chained `&&`, and no comments that restate the next line — reserve comments for the non-obvious *why*.
+- CI-specific: new informational jobs (reporting, dashboards, comment posting) should not gate merging; keep them out of any required-checks list.
+
+When in doubt, mirror how the surrounding cuOpt code handles the same concern rather than introducing a new convention.
 
 ## Common Tasks