diff --git a/docs/references/kernel-style-as-example.md b/docs/references/kernel-style-as-example.md index 3079115..2023e31 100644 --- a/docs/references/kernel-style-as-example.md +++ b/docs/references/kernel-style-as-example.md @@ -9,7 +9,7 @@ - Phase model: Phase0 planning.md (non-trivial trigger), Phase1 coding.md always hot, Phase2 review.md + exemplars-routing mandatory before commit, Phase3 commit.md + changelog-style mandatory. - ID taxonomy: `R0-*` factual integrity, `CL-*` changelog, `CS-*` code structure, `CC-*` comments, plus `` matching hot ↔ cold rationale via `check-orphan-ids.py`. - Lint chain: `lint-changelog.py` (CL-12 50/70), `lint-code.py`, `checkpatch.pl --strict -g HEAD`, `verify-cover-letter.py`. -- Generic distilled rules we re-used: WHY not WHAT 50-word cap, one source at definition, helper extraction by theme, should_/is_ bool naming, minimal obvious fix, one idea per paragraph. +- Generic distilled rules we re-used: WHY not WHAT 50-word cap, one source at definition, helper extraction by theme, should_/is_ bool naming, minimal obvious fix, one idea per paragraph, forward references naming the artifact (GC-14b), working-context shorthand ban (upstream-hygiene class 6). ## License diff --git a/skills/changelog-quality/SKILL.md b/skills/changelog-quality/SKILL.md index e8124d6..d81ef58 100644 --- a/skills/changelog-quality/SKILL.md +++ b/skills/changelog-quality/SKILL.md @@ -51,6 +51,10 @@ Good: "Fix by having the offline path wait for pending work for the memcg before Split helper, sync bool, trylock vs mutex belong in code comments/doc, not changelog. +### Forward references name the artifact, for purpose not status + + A patch that exists for a later patch names what the later patch introduces — the function, helper, or contract — never the later patch's plan label or status. Bad: "switched to it in the next patch", "until step B lands", "a later change needs the same three lines" (names neither the change nor the lines, so in the committed log it points at nothing). Good: "cleans up the name space for adding a scoped-query variant". Justify a prep patch on its own terms: open with the problem that exists now, not with what a follow-up will do — at this patch that behavior does not exist yet, so stating it as motivation misleads a reviewer reading in order. + ### GC-15 — Say what change does NOT do / its limits if non-trivial Scope guard: "Does not change behavior for GET", "No fast-path impact". diff --git a/skills/upstream-hygiene/SKILL.md b/skills/upstream-hygiene/SKILL.md index dfa0bfe..92db562 100644 --- a/skills/upstream-hygiene/SKILL.md +++ b/skills/upstream-hygiene/SKILL.md @@ -54,6 +54,7 @@ Do not enumerate private names — ban classes, with `example.invalid` placehold 3. **Internal tooling/process:** private scripts, cron jobs, internal ticket IDs, private CI job names, local-only wrappers — unless project documents them. 4. **Cross-project references:** "like our fix in " unless direct documented dependency (import, API, shared lib). Upstream fix should stand alone. 5. **Personal dev notes:** `TODO()`, "we do X in our infra", "for our perf lab", internal benchmark machine names. +6. **Working-context shorthand and process narration:** step labels from a private plan (`phase-2 item`, `step B of the rollout`), bare first-name references (`the case flagged`), and process verbs carrying no technical content (`review found three problems`, `as decided in sync`). Rewrite by naming the artifact — the function, contract, or finding — not the session it came from. **Why class-based:** Listing private names to ban them leaks them. Teach agent the class, use `example.invalid` in examples, never paste real private suffixes into skill or commit.