Technical writing
A shipped addition and its documentation are two separate facts, and only one
is checked by CI. check-doc-links.yml proves links resolve; check-prose- retention.yml stops prose disappearing unannounced. Neither asks whether a
new env var, flag or export has a matching line anywhere — both are built to
catch loss, not silence, and an addition is not a loss. The clud-bug seed
(CLUD_BUG_NOTARY_URL, --bundle) shipped working and undocumented; this
repo's own bd1b554/8f7fdbb F2 pass existed to close the same gap a second
time, independently. Two occurrences is a pattern, not a one-off.
When to use
- A diff adds a new env var, CLI flag, config key, exported function/type, or
endpoint that runs correctly and ships with no doc or changelog line naming
it.
- You are closing a "docs truth" pass and need to confirm every addition since
the last one is covered — not just that the existing docs still resolve.
- A PR's own description claims a capability the diff adds, but no README,
--help text, docstring or CHANGELOG entry says so anywhere in the tree.
When NOT to use
- The change reverses an earlier value.
retiring-a-superseded-decision
owns this, and says why it doesn't cover the addition case: "The decision
is new and replaces nothing — no old value to hunt." An addition has no old
value by definition — that gap is this skill's case, not that one's.
- The change breaks an existing surface.
api-contract-enforcement owns
removed fields, renamed parameters, changed status codes, tightened
validation — and disclaims itself only where "the change is purely
additive — adding a new optional field, new endpoint, new CLI flag — with no
removal or behavior change to existing surface," which is precisely this
skill's territory, not its own.
- The finding is about the diff's behavior, not its documentation. This is
a
kind: writing skill; per SPEC §2.2 it must not be the sole citation for
a claim about code behavior — pair it with the rule skill that owns that
surface (often api-contract-enforcement) when the code itself, not only
its coverage, is in question.
Search the new surface, not the old one
An addition has nothing to contradict, so there is no stale sentence to find —
the failure mode is a gap, not a lie, and the thing to search for is the new
name itself: the flag's own spelling, the env var's own spelling, the export's
own spelling, across every doc location (README, CHANGELOG, --help text,
docstrings). A hit is coverage; nothing is the finding. Control-test the search
first against an addition you already know is documented, per
proving-an-absence — a search that finds nothing may be the search, not the
repo.
Changelog cadence
The same PR that ships the capability states what changed, in the format its
readers use — not a promised follow-up. SemVer ties this to a version-visible
fact: "MINOR version when you add functionality in a backward compatible
manner" (semver.org §7–8). Keep a Changelog is one worked instantiation of the
cadence itself: an Unreleased section at the top, entries grouped by type
(Added/Changed/Deprecated/Removed/Fixed/Security), one section per
version. Two named systems make the rule machine-checkable instead of a habit
to remember: Changesets gates a merge on changeset status --since=main
failing when code changed with no changeset file; towncrier requires one
newsfragment file per PR, assembled into the changelog at release. Neither is
prescribed here — the generic rule is that the PR adding the surface also
states it; which mechanism enforces that is the repo's own choice.
Verification
- Grep the new surface's own name across doc locations; control-test against
a known-documented addition first, so a broken search doesn't read as a
clean repo.
- Confirm the changelog entry (or the repo's chosen mechanism) landed in the
same PR — not a promise to add it later.
- If the finding also touches the diff's behavior, pair it with the
code-aware skill that owns that surface; this skill's citation alone does
not cover a behavior claim.
Cross-references
Sources
- Keep a Changelog 1.1.0, keepachangelog.com — the
Unreleased section and
the Added/Changed/Deprecated/Removed/Fixed/Security categories.
- Semantic Versioning 2.0.0 §7–8, semver.org — MINOR for backward-compatible
additions.
- Changesets, github.com/changesets/changesets
docs/automating-changesets.md
— changeset status --since as a merge-time gate.
- towncrier, github.com/twisted/towncrier — one newsfragment file per PR.
- protocol SPEC §2.2, github.com/thrillmade/protocol
SPEC.md — kind
routes a skill to a pass; the pairing rule this skill's kind: writing
is bound by.
1---2version: "1.0.0"3digest: "13e8b85d472a" # is your copy current? github.com/thrillmade/agent-skills/blob/main/docs/skill-versions.json4origin: "https://github.com/thrillmade/agent-skills"5name: technical-writing6description: Flag a PR that ships a new env var, CLI flag, config key, exported function/type, or endpoint with no matching doc or changelog entry — working and undocumented, not broken. Apply to any addition, a new capability with no removal or behavior change to existing surface. Not for a reversed or superseded value (see retiring-a-superseded-decision) or a breaking API change (see api-contract-enforcement); pairs with the latter when a finding also touches behavior.7kind: writing8metadata:9 source: https://skillmd.com/skills/thrillmade/technical-writing10---1112# Technical writing1314A shipped addition and its documentation are two separate facts, and only one15is checked by CI. `check-doc-links.yml` proves links resolve; `check-prose-16retention.yml` stops prose disappearing unannounced. Neither asks whether a17*new* env var, flag or export has a matching line anywhere — both are built to18catch loss, not silence, and an addition is not a loss. The clud-bug seed19(`CLUD_BUG_NOTARY_URL`, `--bundle`) shipped working and undocumented; this20repo's own `bd1b554`/`8f7fdbb` F2 pass existed to close the same gap a second21time, independently. Two occurrences is a pattern, not a one-off.2223## When to use2425- A diff adds a new env var, CLI flag, config key, exported function/type, or26 endpoint that runs correctly and ships with no doc or changelog line naming27 it.28- You are closing a "docs truth" pass and need to confirm every addition since29 the last one is covered — not just that the existing docs still resolve.30- A PR's own description claims a capability the diff adds, but no README,31 `--help` text, docstring or CHANGELOG entry says so anywhere in the tree.3233## When NOT to use3435- **The change reverses an earlier value.** `retiring-a-superseded-decision`36 owns this, and says why it doesn't cover the addition case: *"The decision37 is new and replaces nothing — no old value to hunt."* An addition has no old38 value by definition — that gap is this skill's case, not that one's.39- **The change breaks an existing surface.** `api-contract-enforcement` owns40 removed fields, renamed parameters, changed status codes, tightened41 validation — and disclaims itself only where *"the change is purely42 additive — adding a new optional field, new endpoint, new CLI flag — with no43 removal or behavior change to existing surface,"* which is precisely this44 skill's territory, not its own.45- **The finding is about the diff's behavior, not its documentation.** This is46 a `kind: writing` skill; per SPEC §2.2 it must not be the sole citation for47 a claim about code behavior — pair it with the `rule` skill that owns that48 surface (often `api-contract-enforcement`) when the code itself, not only49 its coverage, is in question.5051## Search the new surface, not the old one5253An addition has nothing to contradict, so there is no stale sentence to find —54the failure mode is a gap, not a lie, and the thing to search for is the new55name itself: the flag's own spelling, the env var's own spelling, the export's56own spelling, across every doc location (README, CHANGELOG, `--help` text,57docstrings). A hit is coverage; nothing is the finding. Control-test the search58first against an addition you already know is documented, per59`proving-an-absence` — a search that finds nothing may be the search, not the60repo.6162## Changelog cadence6364The same PR that ships the capability states what changed, in the format its65readers use — not a promised follow-up. SemVer ties this to a version-visible66fact: "MINOR version when you add functionality in a backward compatible67manner" (semver.org §7–8). Keep a Changelog is one worked instantiation of the68cadence itself: an `Unreleased` section at the top, entries grouped by type69(`Added`/`Changed`/`Deprecated`/`Removed`/`Fixed`/`Security`), one section per70version. Two named systems make the rule machine-checkable instead of a habit71to remember: Changesets gates a merge on `changeset status --since=main`72failing when code changed with no changeset file; towncrier requires one73newsfragment file per PR, assembled into the changelog at release. Neither is74prescribed here — the generic rule is that the PR adding the surface also75states it; which mechanism enforces that is the repo's own choice.7677## Verification78791. Grep the new surface's own name across doc locations; control-test against80 a known-documented addition first, so a broken search doesn't read as a81 clean repo.822. Confirm the changelog entry (or the repo's chosen mechanism) landed in the83 same PR — not a promise to add it later.843. If the finding also touches the diff's behavior, pair it with the85 code-aware skill that owns that surface; this skill's citation alone does86 not cover a behavior claim.8788## Cross-references8990- [retiring-a-superseded-decision](../retiring-a-superseded-decision/SKILL.md)91 — the reversed-value case this skill excludes; search the old value, not92 the new one.93- [api-contract-enforcement](../api-contract-enforcement/SKILL.md) — the94 breaking-change case this skill excludes; pair with it when a finding also95 touches behavior, per SPEC §2.2.96- [proving-an-absence](../proving-an-absence/SKILL.md) — control-testing the97 "no doc found" grep before reporting it.9899## Sources100101- Keep a Changelog 1.1.0, keepachangelog.com — the `Unreleased` section and102 the `Added`/`Changed`/`Deprecated`/`Removed`/`Fixed`/`Security` categories.103- Semantic Versioning 2.0.0 §7–8, semver.org — MINOR for backward-compatible104 additions.105- Changesets, github.com/changesets/changesets `docs/automating-changesets.md`106 — `changeset status --since` as a merge-time gate.107- towncrier, github.com/twisted/towncrier — one newsfragment file per PR.108- protocol SPEC §2.2, github.com/thrillmade/protocol `SPEC.md` — `kind`109 routes a skill to a pass; the pairing rule this skill's `kind: writing`110 is bound by.