rules/workflow.md
GitHubWorkflow: survey, triage, finalize
1. Survey
Run these from the repo root, with ../node being a nodejs/node checkout on
main that is up to date (git -C ../node pull --ff-only).
# Which skills are stale: doc YAML or stability changed in their sources since the pinned commit
node tools/check-drift.mjs --node-dir ../node
# What's new since the last survey baseline, and what no skill mentions yet.
# The baseline is the newest release the previous survey covered (see the
# dated sections in SURVEY.md). For a full re-survey, use v24.0.0.
node tools/survey.mjs --node-dir ../node --since v26.13.0 --changes --uncovered
node tools/survey.mjs --node-dir ../node --since v26.13.0 --module zlib # one module, covered and not
# Features whose docs lag the code (an undocumented export, a new flag):
git -C ../node log --oneline <oldest pinned commit>..HEAD -- lib src doc/api \
| grep -iE '^[0-9a-f]+ [a-z_,/ ]+: (add|implement|introduce|support|expose)'
survey.mjs coverage is a token match, so treat it as triage, not proof. A
"covered" row can still be out of date: drift catches that case.
Record results by appending a dated section to SURVEY.md (baseline,
counts, notable additions). Don't rewrite history.
2. Triage: does it earn coverage?
Include a feature when all of these hold:
- A model can't guess it. It's new, renamed, has a changed default, or was removed. Don't cover a feature that is older than the training cutoff and unchanged.
- It matters to general coding. Users hit it in tasks, or it replaces an npm dependency, or code that uses the old way breaks.
- It's available on a supported line (≥ the floor in
AGENTS.md). Features only onmainare fine if the skill says so.
Usually skip:
- Node-API/C++ internals (they belong in the separate
nodejs-coreskill). - Inspector protocol minutiae.
- Error codes on their own: cover them under their feature.
- Type-only doc entries (
type: ApplicationOptions) unless the feature itself is covered.
Where it goes
| The change is… | Put it in |
|---|---|
| A removal, EOL, runtime deprecation, or changed default | node-modern-migration (one row), plus the owning skill's "Don't" |
| A new API in a module or task that a skill already owns | That skill: rules/ first, the body only if it's behavior-critical |
| A new built-in module, or a distinct task no skill owns | A new skill. Use one skill per task a user would ask for, and keep the boundary at the smallest unit that a single task needs in full |
| A small standalone utility | node-utilities (keep its body a lookup table) |
| An addition that would push a body over 1000 tokens | Move existing body detail to rules/, or split the skill |
Skill ownership is listed in the README table. When two skills touch one feature, the reference material lives in exactly one of them and the other points to it by name (relative paths break when skills install separately).
7. Finalize
- Run the gate in
SKILL.md. Fix anything that fails. Don't weaken a check. - Run
node tools/discrepancies.mjs. Read the new entries: separate upstream doc bugs from real Node.js bugs, and tell the user about the bugs. - Update the README skills table (and floors),
SURVEY.md(the dated section), andPLAN.mdif a design decision changed. - Re-pin provenance:
- Skills you updated: set
nodejsCommitto the commit you verified against (git -C ../node rev-parse --short=11 HEAD), and add any new doc files tosources. - Untouched skills with no drift:
node tools/check-drift.mjs --node-dir ../node --bump. This re-pins only skills that reportcurrent. - Never bump a drifting skill without reviewing the diff.
- Skills you updated: set
- If the user asks for a commit, use one logical change per commit (for example "node-zip: cover ZipFile.rename"). Never push.