fix(verify-readme): point READMEs at the sources of sets instead of copying them #96

jercik · 2026-10-02T05:35:42Z

jercik commented

2026-10-02 05:35:42 +00:00

verify-readme no longer asks READMEs for script and env var tables or an in-README API reference. Instead, a README names the file, schema, or command that defines each set. It keeps only what that source can't show: why a member exists, its traps, and which members a reader must set when the source doesn't mark them.

The old tables conflict with the restated-sets rule in j4k/review#91. Reviewing three setup-atlas READMEs under that rule produced 22 high-severity findings, and only 3 of them were real drift.

A README can still list every member when no file defines the set, when the README is the only place a reader can see a contract they depend on (like the fields of a --json output with no shipped schema), or when the list is a table of contents. The dotfiles directory index and the monorepo packages table stay, because each entry says what the item is for, so a reader can pick one without opening them all. A bare list of names doesn't qualify.

verify-unixy-cli's ARG8 now asks for the same thing, so the two skills stop disagreeing about one README: a CLI's Requirements section points at the help output that names its external dependencies and adds install and auth steps instead of listing them all.

`verify-readme` no longer asks READMEs for script and env var tables or an in-README API reference. Instead, a README names the file, schema, or command that defines each set. It keeps only what that source can't show: why a member exists, its traps, and which members a reader must set when the source doesn't mark them. The old tables conflict with the restated-sets rule in [j4k/review#91](https://code.j4k.dev/j4k/review/pulls/91). Reviewing three setup-atlas READMEs under that rule produced 22 high-severity findings, and only 3 of them were real drift. A README can still list every member when no file defines the set, when the README is the only place a reader can see a contract they depend on (like the fields of a `--json` output with no shipped schema), or when the list is a table of contents. The dotfiles directory index and the monorepo packages table stay, because each entry says what the item is for, so a reader can pick one without opening them all. A bare list of names doesn't qualify. `verify-unixy-cli`'s ARG8 now asks for the same thing, so the two skills stop disagreeing about one README: a CLI's Requirements section points at the help output that names its external dependencies and adds install and auth steps instead of listing them all.

jercik added 1 commit

2026-10-02 05:35:42 +00:00

fix(verify-readme): point READMEs at the sources of sets instead of copying them

commit-msg / commitlint (pull_request) Successful in 23s

Details

Node tests / node:test (pull_request) Successful in 1m35s

Details

Review / Review (pull_request_target) Successful in 4s

Details

e929825944

forgejo-actions commented

2026-10-02 05:39:36 +00:00

Review 01M3YFMB4XNPJMN56TY04SEGG4 — head 4a0708998a356d6364aa2ec68933f4a1644cbf1a

Review — j4k-oss/agent-skills @ `dc68299186`

Scope: diff against base tree 9bc616862d3a
Status: dispatched — coverage complete (3/3 slots terminal)
Facts: current review-wide projection

Computed under:

{
  "abandonment": "abandonment-v1",
  "anchor_recipe": 1,
  "batch_policy": "batch-v1",
  "coverage": "coverage-v3",
  "dispatch_policy": "dispatch-v2",
  "grounder_version": 1,
  "grounding_read_rule": "grounding-read-v1",
  "promotion_policy": "promotion-v1",
  "report": "report-v3",
  "tally": "tally-v1",
  "triage_settle": "triage-settle-v2"
}

Findings (2)

medium — Moving README explanations into source comments can hide them from the linked user-facing source

claim: 01M3YG2EXKPBGNWWZB319THHZ0
anchor: skills/verify-readme/SKILL.md (snippet)

Keep that detail in the README unless the task covers editing the source; then move it beside the member's definition, as a schema description or a comment.

lens: writing-quality · arm: default
verdicts: 1 valid / 0 invalid / 0 uncertain
disposition: none

I read the full verify-readme skill and its CLI cross-reference, plus ARG8 and ARG9 in verify-unixy-cli. This paragraph first requires the README to add meanings, units, default rationale, gotchas, and requiredness when the referenced source cannot show them. It then says to move that detail into a schema description or a comment whenever the task also edits the source. For a CLI README that points readers to --help, a comment beside a flag declaration never appears in --help; similarly, an implementation comment may not appear in generated API docs. A combined CLI-and-README edit can therefore delete useful explanation from the README while leaving the reader with only a link to output that still lacks it. The installed writing guide calls for placing content where its audience can see it and preserving non-obvious facts. Limit the move to descriptions actually rendered in the linked help/docs, and keep other detail in the README with the link. This retains one authoritative explanation without making users inspect implementation comments. This is a static audience-and-surface mismatch; a project that publishes the comments as linked reference documentation would avoid it.

medium — README guidance treats installation and authentication as absent from help despite ARG9 requiring them there

claim: 01M3YFWA3JE9K7NEPRKPZV5Y09
anchor: skills/verify-unixy-cli/references/arg8-document-external-dependencies.md (snippet)

2. **Covered in README**: A "Requirements" or "Prerequisites" section that points at the help output naming the dependencies and adds what it can't show, such as how to install each one and, for one that needs it, how to authenticate it (see "Sets defined elsewhere" in the verify-readme skill)

lens: writing-quality · arm: default
verdicts: 1 valid / 0 invalid / 0 uncertain
disposition: none

I read the full ARG8 rule, the linked verify-readme skill, and ARG9 contextual Requires rule. ARG8 says the README should add what help cannot show, specifically installation and authentication instructions. ARG9 requires each command dependency to have install guidance and an optional auth fix, renders inline fixes in --help, and its examples show both an install URL and gh auth login. An agent applying both rules cannot tell which details belong only in the README; following ARG8 examples duplicates help text, while avoiding duplication can make the README look incomplete under ARG8 verification. The writing guide says to state each fact once and keep related rules consistent. Revise ARG8 to point at live help for dependency names and short install/auth fixes, and ask the README for only setup detail that help does not actually contain, such as platform-specific steps or prerequisite versions. This preserves the README setup role while giving each instruction one source. Static comparison establishes the conflict; an implementation where help omits install/auth fixes would refute it for that CLI, but would then fail ARG9.

Other claims

grounding-pending (0)
ungrounded (0)
rejected (0)
duplicate-of (0)
unadjudicated (0)

Coverage

Coverage pass: 01M3YFMB6JQYFEAA4AZ3PNQQS7
Accounting: complete
Slot health: healthy

lens	part	arm	unit status	runs	loss
general-bug	whole	default	no-claims	1	no
writing-quality	whole	default	claims-emitted	1	no
test-trimming	whole	default	no-claims	1	no

**Review** `01M3YFMB4XNPJMN56TY04SEGG4` — head `4a0708998a356d6364aa2ec68933f4a1644cbf1a` # Review — j4k-oss/agent-skills @ dc68299186f8 Scope: diff against base tree `9bc616862d3a` Status: dispatched — coverage complete (3/3 slots terminal) Facts: current review-wide projection Computed under: ```json { "abandonment": "abandonment-v1", "anchor_recipe": 1, "batch_policy": "batch-v1", "coverage": "coverage-v3", "dispatch_policy": "dispatch-v2", "grounder_version": 1, "grounding_read_rule": "grounding-read-v1", "promotion_policy": "promotion-v1", "report": "report-v3", "tally": "tally-v1", "triage_settle": "triage-settle-v2" } ``` ## Findings (2) ### medium — Moving README explanations into source comments can hide them from the linked user-facing source - claim: `01M3YG2EXKPBGNWWZB319THHZ0` - anchor: `skills/verify-readme/SKILL.md` (snippet) ``` Keep that detail in the README unless the task covers editing the source; then move it beside the member's definition, as a schema description or a comment. ``` - lens: writing-quality · arm: default - verdicts: 1 valid / 0 invalid / 0 uncertain - disposition: none > I read the full verify-readme skill and its CLI cross-reference, plus ARG8 and ARG9 in verify-unixy-cli. This paragraph first requires the README to add meanings, units, default rationale, gotchas, and requiredness when the referenced source cannot show them. It then says to move that detail into a schema description or a comment whenever the task also edits the source. For a CLI README that points readers to --help, a comment beside a flag declaration never appears in --help; similarly, an implementation comment may not appear in generated API docs. A combined CLI-and-README edit can therefore delete useful explanation from the README while leaving the reader with only a link to output that still lacks it. The installed writing guide calls for placing content where its audience can see it and preserving non-obvious facts. Limit the move to descriptions actually rendered in the linked help/docs, and keep other detail in the README with the link. This retains one authoritative explanation without making users inspect implementation comments. This is a static audience-and-surface mismatch; a project that publishes the comments as linked reference documentation would avoid it. ### medium — README guidance treats installation and authentication as absent from help despite ARG9 requiring them there - claim: `01M3YFWA3JE9K7NEPRKPZV5Y09` - anchor: `skills/verify-unixy-cli/references/arg8-document-external-dependencies.md` (snippet) ``` 2. **Covered in README**: A "Requirements" or "Prerequisites" section that points at the help output naming the dependencies and adds what it can't show, such as how to install each one and, for one that needs it, how to authenticate it (see "Sets defined elsewhere" in the verify-readme skill) ``` - lens: writing-quality · arm: default - verdicts: 1 valid / 0 invalid / 0 uncertain - disposition: none > I read the full ARG8 rule, the linked verify-readme skill, and ARG9 contextual Requires rule. ARG8 says the README should add what help cannot show, specifically installation and authentication instructions. ARG9 requires each command dependency to have install guidance and an optional auth fix, renders inline fixes in --help, and its examples show both an install URL and gh auth login. An agent applying both rules cannot tell which details belong only in the README; following ARG8 examples duplicates help text, while avoiding duplication can make the README look incomplete under ARG8 verification. The writing guide says to state each fact once and keep related rules consistent. Revise ARG8 to point at live help for dependency names and short install/auth fixes, and ask the README for only setup detail that help does not actually contain, such as platform-specific steps or prerequisite versions. This preserves the README setup role while giving each instruction one source. Static comparison establishes the conflict; an implementation where help omits install/auth fixes would refute it for that CLI, but would then fail ARG9. ## Other claims - grounding-pending (0) - ungrounded (0) - rejected (0) - duplicate-of (0) - unadjudicated (0) ## Coverage Coverage pass: 01M3YFMB6JQYFEAA4AZ3PNQQS7 Accounting: complete Slot health: healthy | lens | part | arm | unit status | runs | loss | | --- | --- | --- | --- | --- | --- | | general-bug | whole | default | no-claims | 1 | no | | writing-quality | whole | default | claims-emitted | 1 | no | | test-trimming | whole | default | no-claims | 1 | no |

🚀 1

forgejo-actions reviewed

2026-10-02 05:39:37 +00:00

skills/verify-readme/SKILL.md Outdated

					
				@ -72,0 +67,4 @@

				- **CLI** — point at `--help` for the flag reference; use this section for shell composition (pipelines, scripting). See "Pipeline patterns" below.

				- **Library** — show realistic usage, not toy snippets. Point at the type declarations or generated docs (TypeDoc, etc.) for the full API.

				- **App** — point at `package.json#scripts` and say which scripts a reader runs and when; auth setup.

				- **Config / dotfiles** — ordered setup steps; point at the top-level directories, say that each carries its own README where it does, and explain a directory only when its name doesn't.

medium — Config/dotfiles Usage bullet ("point at the top-level directories") can be read as listing every directory, which the new "Sets defined elsewhere" rule forbids
lens writing-quality · arm default · tally 1 valid / 0 invalid / 0 uncertain

Examined: the Usage / API per-type bullets in skills/verify-readme/SKILL.md, the line right after them ("See "Sets defined elsewhere" below for how to point at a set."), and that section, which names "a directory's children" as a set the README must not list: "the README names that source instead of listing the members".

What the text says: the Config / dotfiles bullet tells the agent to "point at the top-level directories, say that each carries its own README where it does, and explain a directory only when its name doesn't." Every other bullet in the list points at one source (--help, package.json#scripts, the workspace definition, type declarations). This one points at a plural set of things. A literal reader can take "point at the top-level directories" to mean "link each top-level directory", which is the per-directory index the old bullet asked for and which the new section now forbids. The clause "say that each carries its own README where it does" makes this worse: "each" claims full coverage and "where it does" takes it back, so it isn't clear whether the README should make one blanket statement or name the directories that have a README.

Impact: in edit mode, an agent following this bullet can produce a full directory index, and the same agent in audit mode flags that index under step 6 ("A set copied from its source — a ... directory ... table"). The writing-for-agents skill asks for "one term for one concept" and verifiable claims. Here "point at" means "name one source" in the other bullets and plausibly "list" in this one.

Proposed correction: name the source the same way the other bullets do. For example: "Config / dotfiles — ordered setup steps; point at the repository root as the index of what's managed, say that directories with their own README document themselves, and explain a directory only when its name doesn't." This keeps the setup steps, the sub-README pointer, and the selective explanations, and removes the reading that asks for a full list.

What would refute this: if the author meant a full directory index to be allowed here, the section needs an explicit exception for it, because as written the two passages conflict. I found this by reading the text; I did not run the skill.

claim 01M3XHVVY3CDHTG7Z2KH01DZM2 of review 01M3XHS1TPJ8AQWQCWZ1SR0MGW

**medium** — Config/dotfiles Usage bullet ("point at the top-level directories") can be read as listing every directory, which the new "Sets defined elsewhere" rule forbids lens `writing-quality` · arm `default` · tally 1 valid / 0 invalid / 0 uncertain > Examined: the Usage / API per-type bullets in skills/verify-readme/SKILL.md, the line right after them ("See \"Sets defined elsewhere\" below for how to point at a set."), and that section, which names "a directory's children" as a set the README must not list: "the README names that source instead of listing the members". > > What the text says: the Config / dotfiles bullet tells the agent to "point at the top-level directories, say that each carries its own README where it does, and explain a directory only when its name doesn't." Every other bullet in the list points at one source (`--help`, `package.json#scripts`, the workspace definition, type declarations). This one points at a plural set of things. A literal reader can take "point at the top-level directories" to mean "link each top-level directory", which is the per-directory index the old bullet asked for and which the new section now forbids. The clause "say that each carries its own README where it does" makes this worse: "each" claims full coverage and "where it does" takes it back, so it isn't clear whether the README should make one blanket statement or name the directories that have a README. > > Impact: in edit mode, an agent following this bullet can produce a full directory index, and the same agent in audit mode flags that index under step 6 ("A set copied from its source — a ... directory ... table"). The writing-for-agents skill asks for "one term for one concept" and verifiable claims. Here "point at" means "name one source" in the other bullets and plausibly "list" in this one. > > Proposed correction: name the source the same way the other bullets do. For example: "**Config / dotfiles** — ordered setup steps; point at the repository root as the index of what's managed, say that directories with their own README document themselves, and explain a directory only when its name doesn't." This keeps the setup steps, the sub-README pointer, and the selective explanations, and removes the reading that asks for a full list. > > What would refute this: if the author meant a full directory index to be allowed here, the section needs an explicit exception for it, because as written the two passages conflict. I found this by reading the text; I did not run the skill. claim `01M3XHVVY3CDHTG7Z2KH01DZM2` of review `01M3XHS1TPJ8AQWQCWZ1SR0MGW`

👍 1

superseded by review 01M3XPYZ4SDEZHKKR5BEC4M702 for head fd767d038e4e15c61e5b63e3095ed1b37ec4e19a

superseded by review `01M3XPYZ4SDEZHKKR5BEC4M702` for head `fd767d038e4e15c61e5b63e3095ed1b37ec4e19a`

🚀 1

Already fixed in 83f9b43: the bullet now asks for a per-directory index whose entries each say what the directory is for, which the table-of-contents exception in "Sets defined elsewhere" allows. The ambiguous "point at the top-level directories" wording is gone.

Already fixed in 83f9b43: the bullet now asks for a per-directory index whose entries each say what the directory is for, which the table-of-contents exception in "Sets defined elsewhere" allows. The ambiguous "point at the top-level directories" wording is gone.

jercik marked this conversation as resolved

skills/verify-readme/SKILL.md Outdated

					
				@ -72,0 +68,4 @@

				- **Library** — show realistic usage, not toy snippets. Point at the type declarations or generated docs (TypeDoc, etc.) for the full API.

				- **App** — point at `package.json#scripts` and say which scripts a reader runs and when; auth setup.

				- **Config / dotfiles** — ordered setup steps; point at the top-level directories, say that each carries its own README where it does, and explain a directory only when its name doesn't.

				- **Monorepo** — point at the workspace definition and say that each package carries its own README; describe the packages a newcomer touches first.

low — Monorepo Usage guidance tells the agent to say every package has its own README without the "where it does" check the dotfiles bullet has
lens general-bug · arm default · tally 1 valid / 0 invalid / 0 uncertain

Examined: the per-type Usage guidance in section 4 of skills/verify-readme/SKILL.md, the new "Sets defined elsewhere" section, and the Task/Output steps, where edit mode writes the README directly.

The change replaced "link to each package's README" with "point at the workspace definition and say that each package carries its own README". The parallel bullet changed in the same hunk, Config / dotfiles, is qualified: "say that each carries its own README where it does". The Monorepo bullet has no such qualifier. It tells the agent to assert, as a blanket fact about the whole set, that every package has a README. It gives no step to check that first.

Outcome: in a workspace where some packages lack a README (common for internal tooling or config packages under packages/), an agent in edit or draft mode following this bullet writes a false statement into the README, and a reader goes looking for files that do not exist. The same section also says detail should be written "without a count or a claim to cover them all". An unconditional "each package carries its own README" is a claim over the whole set that goes stale when a package without a README is added, which is the staleness the new rule is meant to prevent.

This is reasoned from the skill text; I did not run an agent. Fix: mirror the dotfiles wording ("say that each package carries its own README where it does"), or tell the agent to check for package READMEs before making the claim. What would refute this: some other part of the skill that limits the Monorepo instruction to workspaces where every package has a README. I found none.

claim 01M3XHWAPKYBY16BD9S1JXSCYA of review 01M3XHS1TPJ8AQWQCWZ1SR0MGW

**low** — Monorepo Usage guidance tells the agent to say every package has its own README without the "where it does" check the dotfiles bullet has lens `general-bug` · arm `default` · tally 1 valid / 0 invalid / 0 uncertain > Examined: the per-type Usage guidance in section 4 of skills/verify-readme/SKILL.md, the new "Sets defined elsewhere" section, and the Task/Output steps, where edit mode writes the README directly. > > The change replaced "link to each package's README" with "point at the workspace definition and say that each package carries its own README". The parallel bullet changed in the same hunk, Config / dotfiles, is qualified: "say that each carries its own README where it does". The Monorepo bullet has no such qualifier. It tells the agent to assert, as a blanket fact about the whole set, that every package has a README. It gives no step to check that first. > > Outcome: in a workspace where some packages lack a README (common for internal tooling or config packages under `packages/`), an agent in edit or draft mode following this bullet writes a false statement into the README, and a reader goes looking for files that do not exist. The same section also says detail should be written "without a count or a claim to cover them all". An unconditional "each package carries its own README" is a claim over the whole set that goes stale when a package without a README is added, which is the staleness the new rule is meant to prevent. > > This is reasoned from the skill text; I did not run an agent. Fix: mirror the dotfiles wording ("say that each package carries its own README where it does"), or tell the agent to check for package READMEs before making the claim. What would refute this: some other part of the skill that limits the Monorepo instruction to workspaces where every package has a README. I found none. claim `01M3XHWAPKYBY16BD9S1JXSCYA` of review `01M3XHS1TPJ8AQWQCWZ1SR0MGW`

👍 1

superseded by review 01M3XPYZ4SDEZHKKR5BEC4M702 for head fd767d038e4e15c61e5b63e3095ed1b37ec4e19a

superseded by review `01M3XPYZ4SDEZHKKR5BEC4M702` for head `fd767d038e4e15c61e5b63e3095ed1b37ec4e19a`

🚀 1

Fixed in bd1fb2f: the Monorepo bullet now links each package README where it has one, matching the dotfiles bullet.

Fixed in bd1fb2f: the Monorepo bullet now links each package README where it has one, matching the dotfiles bullet.

jercik marked this conversation as resolved

skills/verify-readme/SKILL.md Outdated

					
				@ -87,3 +89,3 @@

				**Purpose**: the settings surface.

				Env vars as a table. Config file format in a fenced block. Include only when the project is configurable.

				Point at the env var schema or config parser and any example config file, then add what they can't show: which settings a reader must set when the source doesn't mark them, why a default is what it is, and traps. A short fenced excerpt can show the config file format. Include only when the project is configurable.

low — Configuration section restates the "Sets defined elsewhere" rule in its own words instead of pointing to it, so the two copies can drift
lens writing-quality · arm default · tally 1 valid / 0 invalid / 0 uncertain

Examined: the "### 6. Configuration" section of skills/verify-readme/SKILL.md, the "## Sets defined elsewhere" section, and the pointer at the end of Usage ("See "Sets defined elsewhere" below for how to point at a set.").

What the text says: Configuration says "Point at the env var schema or config parser ... then add what they can't show: which settings a reader must set when the source doesn't mark them, why a default is what it is, and traps." "Sets defined elsewhere" already names "the env var schema or config parser" as a source and requires "the detail the source can't show: what a member means and its units, why it exists, its gotchas, and which members the reader must set or run when the source doesn't mark them." That is the same instruction in slightly different wording, and the two lists of detail already disagree: Configuration leaves out meaning/units, and "why a default is what it is" does not appear in the shared section.

Impact: the writing-for-agents skill says "Give each instruction one clear home" and "Do not restate what ... an earlier sentence ... already says." With two versions, a future edit to one will not reach the other. An agent comparing them may also read the differences as intentional, for example that config docs need not explain units. This is also the kind of copy-of-a-set drift the new section itself warns about.

Proposed correction: replace the restatement with the same pointer Usage uses, and keep only what is specific to configuration. For example: "Point at the env var schema or config parser and any example config file, as "Sets defined elsewhere" describes. A short fenced excerpt can show the config file format. Include only when the project is configurable." If "why a default is what it is" matters, add it once to the shared detail list in "Sets defined elsewhere" so it applies to every set. This keeps every requirement in one place.

claim 01M3XHW6BGPJTC444DC9Q6MAJQ of review 01M3XHS1TPJ8AQWQCWZ1SR0MGW

**low** — Configuration section restates the "Sets defined elsewhere" rule in its own words instead of pointing to it, so the two copies can drift lens `writing-quality` · arm `default` · tally 1 valid / 0 invalid / 0 uncertain > Examined: the "### 6. Configuration" section of skills/verify-readme/SKILL.md, the "## Sets defined elsewhere" section, and the pointer at the end of Usage ("See \"Sets defined elsewhere\" below for how to point at a set."). > > What the text says: Configuration says "Point at the env var schema or config parser ... then add what they can't show: which settings a reader must set when the source doesn't mark them, why a default is what it is, and traps." "Sets defined elsewhere" already names "the env var schema or config parser" as a source and requires "the detail the source can't show: what a member means and its units, why it exists, its gotchas, and which members the reader must set or run when the source doesn't mark them." That is the same instruction in slightly different wording, and the two lists of detail already disagree: Configuration leaves out meaning/units, and "why a default is what it is" does not appear in the shared section. > > Impact: the writing-for-agents skill says "Give each instruction one clear home" and "Do not restate what ... an earlier sentence ... already says." With two versions, a future edit to one will not reach the other. An agent comparing them may also read the differences as intentional, for example that config docs need not explain units. This is also the kind of copy-of-a-set drift the new section itself warns about. > > Proposed correction: replace the restatement with the same pointer Usage uses, and keep only what is specific to configuration. For example: "Point at the env var schema or config parser and any example config file, as \"Sets defined elsewhere\" describes. A short fenced excerpt can show the config file format. Include only when the project is configurable." If "why a default is what it is" matters, add it once to the shared detail list in "Sets defined elsewhere" so it applies to every set. This keeps every requirement in one place. claim `01M3XHW6BGPJTC444DC9Q6MAJQ` of review `01M3XHS1TPJ8AQWQCWZ1SR0MGW`

👍 1

superseded by review 01M3XPYZ4SDEZHKKR5BEC4M702 for head fd767d038e4e15c61e5b63e3095ed1b37ec4e19a

superseded by review `01M3XPYZ4SDEZHKKR5BEC4M702` for head `fd767d038e4e15c61e5b63e3095ed1b37ec4e19a`

🚀 1

Fixed in bd1fb2f: Configuration now points at "Sets defined elsewhere" for the detail to add instead of restating it, and "why its default is what it is" moved into the shared list.

Fixed in bd1fb2f: Configuration now points at "Sets defined elsewhere" for the detail to add instead of restating it, and "why its default is what it is" moved into the shared list.

jercik marked this conversation as resolved

skills/verify-readme/SKILL.md Outdated

					
				@ -104,1 +106,4 @@

				## Sets defined elsewhere

				When a file, directory, schema, or command already defines a set — `--help`, `package.json#scripts`, the env var schema or config parser, the workspace packages, a directory's children — the README names that source instead of listing the members or stating how many there are. A copy must change with every change to the set, and it goes stale silently when nobody updates it. Name a source the README's reader can reach: a command, a file the published package ships, an absolute repository URL, or, when the project isn't published, a repository-relative path.

low — Rationale sentence in "Sets defined elsewhere" repeats itself: "goes stale silently when nobody updates it" only restates "must change with every change"
lens writing-quality · arm default · tally 1 valid / 0 invalid / 0 uncertain

Examined: the first paragraph of "## Sets defined elsewhere" in skills/verify-readme/SKILL.md.

What the text says: "A copy must change with every change to the set, and it goes stale silently when nobody updates it." The second clause adds nothing: a copy that must be updated is, by definition, stale when nobody updates it. The only new word is "silently", which is the one useful point, that nothing signals the drift.

Impact: this is a small cost to the reader, but this section is already the densest part of the skill (see the separate exception-chain finding), and every extra clause makes the operative rules harder to find. The writing-for-agents skill gives almost exactly this case as its "Duplicate" example: "After a clear sentence, test the next one against it ... cut a consequence or complement the first sentence already implies."

Proposed correction: "A copy must change with every change to the set, and nothing flags it when it doesn't." Or, shorter: "A copy drifts silently as the set changes." Either keeps the rationale (why pointing beats copying) and the "silently" point, and drops the tautology.

claim 01M3XHWQ846764RBBP9546FG1Q of review 01M3XHS1TPJ8AQWQCWZ1SR0MGW

**low** — Rationale sentence in "Sets defined elsewhere" repeats itself: "goes stale silently when nobody updates it" only restates "must change with every change" lens `writing-quality` · arm `default` · tally 1 valid / 0 invalid / 0 uncertain > Examined: the first paragraph of "## Sets defined elsewhere" in skills/verify-readme/SKILL.md. > > What the text says: "A copy must change with every change to the set, and it goes stale silently when nobody updates it." The second clause adds nothing: a copy that must be updated is, by definition, stale when nobody updates it. The only new word is "silently", which is the one useful point, that nothing signals the drift. > > Impact: this is a small cost to the reader, but this section is already the densest part of the skill (see the separate exception-chain finding), and every extra clause makes the operative rules harder to find. The writing-for-agents skill gives almost exactly this case as its "Duplicate" example: "After a clear sentence, test the next one against it ... cut a consequence or complement the first sentence already implies." > > Proposed correction: "A copy must change with every change to the set, and nothing flags it when it doesn't." Or, shorter: "A copy drifts silently as the set changes." Either keeps the rationale (why pointing beats copying) and the "silently" point, and drops the tautology. claim `01M3XHWQ846764RBBP9546FG1Q` of review `01M3XHS1TPJ8AQWQCWZ1SR0MGW`

👍 1

superseded by review 01M3XPYZ4SDEZHKKR5BEC4M702 for head fd767d038e4e15c61e5b63e3095ed1b37ec4e19a

superseded by review `01M3XPYZ4SDEZHKKR5BEC4M702` for head `fd767d038e4e15c61e5b63e3095ed1b37ec4e19a`

🚀 1

Fixed in bd1fb2f: the rationale now reads "A copy must change with every change to the set, and nothing flags it when it does not."

Fixed in bd1fb2f: the rationale now reads "A copy must change with every change to the set, and nothing flags it when it does not."

jercik marked this conversation as resolved

jercik added 1 commit

2026-10-02 07:06:19 +00:00

fix(verify-readme): mark partial lists and config excerpts, exempt dated records

commit-msg / commitlint (pull_request) Successful in 16s

Details

Node tests / node:test (pull_request) Successful in 1m20s

Details

Review / Review (pull_request_target) Successful in 3m20s

Details

fd767d038e

forgejo-actions reviewed

2026-10-02 07:09:45 +00:00

skills/verify-readme/SKILL.md Outdated

					
				@ -87,3 +89,3 @@

				**Purpose**: the settings surface.

				Env vars as a table. Config file format in a fenced block. Include only when the project is configurable.

				Point at the env var schema or config parser and any example config file, then add what they can't show: which settings a reader must set when the source doesn't mark them, why a default is what it is, and traps. A short fenced excerpt, labeled as an excerpt, can show the config file format; it shows the shape, not every key. Include only when the project is configurable.

low — Configuration section repeats the "Sets defined elsewhere" rule instead of pointing to it
lens writing-quality · arm default · tally 1 valid / 0 invalid / 0 uncertain

What I examined: section "### 6. Configuration" and the new "## Sets defined elsewhere" section in skills/verify-readme/SKILL.md.

What the text says: Configuration now reads "Point at the env var schema or config parser and any example config file, then add what they can't show: which settings a reader must set when the source doesn't mark them, why a default is what it is, and traps." "Sets defined elsewhere" already names "the env var schema or config parser" as a set source and requires the README to add "what a member means and its units, why it exists, its gotchas, and which members the reader must set or run when the source doesn't mark them." The Usage section (§4) ends with the pointer "See "Sets defined elsewhere" below for how to point at a set." Configuration has no pointer and instead paraphrases the rule with a slightly different detail list: it drops meaning/units and turns "why it exists" into "why a default is what it is".

What goes wrong: a literal reader gets two lists of required detail that don't quite match, and has to decide whether config settings follow the shorter local list or the general one. Any future edit to the rule also has to be made in two places. The writing-for-agents skill says "Give each instruction one clear home. Do not restate what … an earlier sentence … already says."

Proposed correction: "Point at the env var schema or config parser and any example config file, and add the detail described in "Sets defined elsewhere". A short fenced excerpt, labeled as an excerpt, can show the config file format. Include only when the project is configurable." If the default rationale matters specifically for configuration, add "why a default is what it is" to the general list in "Sets defined elsewhere" so the rule still has one home. This keeps the excerpt permission and the inclusion condition.

claim 01M3XQ1FPHHRHZSDDNAN5VV0BA of review 01M3XPYZ4SDEZHKKR5BEC4M702

**low** — Configuration section repeats the "Sets defined elsewhere" rule instead of pointing to it lens `writing-quality` · arm `default` · tally 1 valid / 0 invalid / 0 uncertain > What I examined: section "### 6. Configuration" and the new "## Sets defined elsewhere" section in skills/verify-readme/SKILL.md. > > What the text says: Configuration now reads "Point at the env var schema or config parser and any example config file, then add what they can't show: which settings a reader must set when the source doesn't mark them, why a default is what it is, and traps." "Sets defined elsewhere" already names "the env var schema or config parser" as a set source and requires the README to add "what a member means and its units, why it exists, its gotchas, and which members the reader must set or run when the source doesn't mark them." The Usage section (§4) ends with the pointer "See \"Sets defined elsewhere\" below for how to point at a set." Configuration has no pointer and instead paraphrases the rule with a slightly different detail list: it drops meaning/units and turns "why it exists" into "why a default is what it is". > > What goes wrong: a literal reader gets two lists of required detail that don't quite match, and has to decide whether config settings follow the shorter local list or the general one. Any future edit to the rule also has to be made in two places. The writing-for-agents skill says "Give each instruction one clear home. Do not restate what … an earlier sentence … already says." > > Proposed correction: "Point at the env var schema or config parser and any example config file, and add the detail described in \"Sets defined elsewhere\". A short fenced excerpt, labeled as an excerpt, can show the config file format. Include only when the project is configurable." If the default rationale matters specifically for configuration, add "why a default is what it is" to the general list in "Sets defined elsewhere" so the rule still has one home. This keeps the excerpt permission and the inclusion condition. claim `01M3XQ1FPHHRHZSDDNAN5VV0BA` of review `01M3XPYZ4SDEZHKKR5BEC4M702`

👍 1

superseded by review 01M3XR69KD21A4VCY038Z7E4DE for head d9cbf38f83ebd9cc714757b9291c403c454a38e8

superseded by review `01M3XR69KD21A4VCY038Z7E4DE` for head `d9cbf38f83ebd9cc714757b9291c403c454a38e8`

🚀 1

Fixed in bd1fb2f: Configuration now points at "Sets defined elsewhere" for the detail to add instead of restating it, and "why its default is what it is" moved into the shared list.

Fixed in bd1fb2f: Configuration now points at "Sets defined elsewhere" for the detail to add instead of restating it, and "why its default is what it is" moved into the shared list.

jercik marked this conversation as resolved

skills/verify-readme/SKILL.md Outdated

					
				@ -104,1 +106,4 @@

				## Sets defined elsewhere

				When a file, directory, schema, or command already defines a set — `--help`, `package.json#scripts`, the env var schema or config parser, the workspace packages, a directory's children — the README names that source instead of listing the members or stating how many there are. A copy must change with every change to the set, and it goes stale silently when nobody updates it. Name a source the README's reader can reach: a command, a file the published package ships, an absolute repository URL, or, when the project isn't published, a repository-relative path.

low — Rationale sentence for "Sets defined elsewhere" restates its own consequence
lens writing-quality · arm default · tally 1 valid / 0 invalid / 0 uncertain

What I examined: the first paragraph of the new "## Sets defined elsewhere" section in skills/verify-readme/SKILL.md.

What the text says: after the rule ("the README names that source instead of listing the members or stating how many there are"), the rationale is "A copy must change with every change to the set, and it goes stale silently when nobody updates it." The second clause is just the first clause's consequence restated: a copy that must change with every change goes stale when nobody changes it.

Why it matters: this section is long and dense, and every sentence costs context for an agent loading the skill. The writing-for-agents skill says: "After a clear sentence, test the next one against it… cut a consequence or complement the first sentence already implies", and its Duplicate example has the same shape.

Proposed correction: "A copy goes stale silently whenever the set changes." This keeps the rationale, including the word "silently", which carries the stakes, and drops the redundant clause.

claim 01M3XQ1G2VC8ZGYPXC5BND3PKX of review 01M3XPYZ4SDEZHKKR5BEC4M702

**low** — Rationale sentence for "Sets defined elsewhere" restates its own consequence lens `writing-quality` · arm `default` · tally 1 valid / 0 invalid / 0 uncertain > What I examined: the first paragraph of the new "## Sets defined elsewhere" section in skills/verify-readme/SKILL.md. > > What the text says: after the rule ("the README names that source instead of listing the members or stating how many there are"), the rationale is "A copy must change with every change to the set, and it goes stale silently when nobody updates it." The second clause is just the first clause's consequence restated: a copy that must change with every change goes stale when nobody changes it. > > Why it matters: this section is long and dense, and every sentence costs context for an agent loading the skill. The writing-for-agents skill says: "After a clear sentence, test the next one against it… cut a consequence or complement the first sentence already implies", and its Duplicate example has the same shape. > > Proposed correction: "A copy goes stale silently whenever the set changes." This keeps the rationale, including the word "silently", which carries the stakes, and drops the redundant clause. claim `01M3XQ1G2VC8ZGYPXC5BND3PKX` of review `01M3XPYZ4SDEZHKKR5BEC4M702`

👍 1

superseded by review 01M3XR69KD21A4VCY038Z7E4DE for head d9cbf38f83ebd9cc714757b9291c403c454a38e8

superseded by review `01M3XR69KD21A4VCY038Z7E4DE` for head `d9cbf38f83ebd9cc714757b9291c403c454a38e8`

🚀 1

Fixed in bd1fb2f: the rationale now reads "A copy must change with every change to the set, and nothing flags it when it does not."

Fixed in bd1fb2f: the rationale now reads "A copy must change with every change to the set, and nothing flags it when it does not."

jercik marked this conversation as resolved

skills/verify-readme/SKILL.md Outdated

					
				@ -105,0 +110,4 @@

				The README still tells the reader where each set lives, plus the detail the source can't show: what a member means and its units, why it exists, its gotchas, and which members the reader must set or run when the source doesn't mark them. A requirements list, a schema's `required`, or `--help` output that labels them required counts as marking them. Write that detail for the members that need it, without a count or a claim to cover them all, even when every member needs it; such a list may name every member. Move detail beside the member's definition, as a schema description or a comment, only when the task covers editing the source; otherwise keep it in the README, including detail carried by a restated list you remove.

				Any other list that names every member restates the set however it is framed — a table, a sentence, a parenthetical, or an "e.g." that covers them all — and so does a count word like "both" or "all" attached to listed members. Mark any other partial list as examples.

low — New "Sets defined elsewhere" rule flags the README dependency list that verify-unixy-cli ARG8 requires, and both checks run in the same audit
lens general-bug · arm default · tally 2 valid / 0 invalid / 0 uncertain

What I examined: the new "Sets defined elsewhere" section and the step 6 failure modes in skills/verify-readme/SKILL.md, plus the verify-unixy-cli skill that loads this one (axskills.requires: "verify-readme"; ARG5 in skills/verify-unixy-cli/references/arg5-readme-quality.md says "Call the Skill tool with verify-readme. Audit the CLI README against it.").

What the subject says: verify-readme now lists --help as a set source and says the README "names that source instead of listing the members". It also says any other list naming every member "restates the set", and step 6 flags "A set copied from its source". Separately, skills/verify-unixy-cli/references/arg8-document-external-dependencies.md requires each external tool dependency to be "Listed in README: A "Requirements" or "Prerequisites" section listing all dependencies" and also "Mentioned in help output".

What goes wrong: take a CLI that follows ARG8. Its --help names its dependencies (say git and gh), and its README Requirements section lists all of them. When verify-unixy-cli audits that CLI, ARG8 passes only if the README carries the full list. ARG5 then runs verify-readme, which reads that same list as a restated --help set ("a sentence ... that covers them all") and reports it as a failure mode. The auditor gets two opposite verdicts on one README section. In edit mode, following verify-readme would remove the list and break ARG8. A list that adds per-dependency detail, such as install commands, can arguably pass under the "detail for the members that need it" carve-out. A plain list of all dependencies is still caught, and that is exactly what ARG8 asks for. None of the exemptions apply: no file defines the set, generated section, dated record, or a contract that --help defers to.

This comes from reading the two documents statically. I did not run either skill. The claim is refuted if the Sets rule explicitly exempts a Requirements or prerequisites list of external tools, or if ARG8 is changed to point at --help instead of listing every dependency. Either change would fix it.

claim 01M3XQ1P511J91T113REJK6ZTK of review 01M3XPYZ4SDEZHKKR5BEC4M702

**low** — New "Sets defined elsewhere" rule flags the README dependency list that verify-unixy-cli ARG8 requires, and both checks run in the same audit lens `general-bug` · arm `default` · tally 2 valid / 0 invalid / 0 uncertain > What I examined: the new "Sets defined elsewhere" section and the step 6 failure modes in skills/verify-readme/SKILL.md, plus the verify-unixy-cli skill that loads this one (`axskills.requires: "verify-readme"`; ARG5 in skills/verify-unixy-cli/references/arg5-readme-quality.md says "Call the Skill tool with `verify-readme`. Audit the CLI README against it."). > > What the subject says: verify-readme now lists `--help` as a set source and says the README "names that source instead of listing the members". It also says any other list naming every member "restates the set", and step 6 flags "A set copied from its source". Separately, skills/verify-unixy-cli/references/arg8-document-external-dependencies.md requires each external tool dependency to be "**Listed in README**: A \"Requirements\" or \"Prerequisites\" section listing all dependencies" and also "**Mentioned in help output**". > > What goes wrong: take a CLI that follows ARG8. Its `--help` names its dependencies (say `git` and `gh`), and its README Requirements section lists all of them. When verify-unixy-cli audits that CLI, ARG8 passes only if the README carries the full list. ARG5 then runs verify-readme, which reads that same list as a restated `--help` set ("a sentence ... that covers them all") and reports it as a failure mode. The auditor gets two opposite verdicts on one README section. In edit mode, following verify-readme would remove the list and break ARG8. A list that adds per-dependency detail, such as install commands, can arguably pass under the "detail for the members that need it" carve-out. A plain list of all dependencies is still caught, and that is exactly what ARG8 asks for. None of the exemptions apply: no file defines the set, generated section, dated record, or a contract that `--help` defers to. > > This comes from reading the two documents statically. I did not run either skill. The claim is refuted if the Sets rule explicitly exempts a Requirements or prerequisites list of external tools, or if ARG8 is changed to point at `--help` instead of listing every dependency. Either change would fix it. claim `01M3XQ1P511J91T113REJK6ZTK` of review `01M3XPYZ4SDEZHKKR5BEC4M702`

👍 1

superseded by review 01M3XR69KD21A4VCY038Z7E4DE for head d9cbf38f83ebd9cc714757b9291c403c454a38e8

superseded by review `01M3XR69KD21A4VCY038Z7E4DE` for head `d9cbf38f83ebd9cc714757b9291c403c454a38e8`

🚀 1

Fixed in bd1fb2f on the ARG8 side. I declined the proposed exemption for prerequisites lists: the user decided that prose restating a set defined elsewhere is a high defect, with a fixed set of exceptions that does not include requirements lists. ARG8 now asks the README Requirements section to point at the help output naming the dependencies and add what help cannot show, such as install and auth steps. "Sets defined elsewhere" already allows a list carrying that per-dependency detail, so the two skills now give the same verdict on one README.

Fixed in bd1fb2f on the ARG8 side. I declined the proposed exemption for prerequisites lists: the user decided that prose restating a set defined elsewhere is a high defect, with a fixed set of exceptions that does not include requirements lists. ARG8 now asks the README Requirements section to point at the help output naming the dependencies and add what help cannot show, such as install and auth steps. "Sets defined elsewhere" already allows a list carrying that per-dependency detail, so the two skills now give the same verdict on one README.

jercik marked this conversation as resolved

jercik referenced this pull request

2026-10-02 07:26:01 +00:00

fix(skills): point CLI docs and drift fixes at sources instead of restating sets #97

jercik added 1 commit

2026-10-02 07:27:48 +00:00

fix(verify-readme): use an unshipped output schema as the README-only contract example

commit-msg / commitlint (pull_request) Successful in 22s

Details

Node tests / node:test (pull_request) Successful in 1m30s

Details

Review / Review (pull_request_target) Successful in 3m35s

Details

d9cbf38f83

forgejo-actions reviewed

2026-10-02 07:31:28 +00:00

skills/verify-readme/SKILL.md Outdated

					
				@ -87,3 +89,3 @@

				**Purpose**: the settings surface.

				Env vars as a table. Config file format in a fenced block. Include only when the project is configurable.

				Point at the env var schema or config parser and any example config file, then add what they can't show: which settings a reader must set when the source doesn't mark them, why a default is what it is, and traps. A short fenced excerpt, labeled as an excerpt, can show the config file format; it shows the shape, not every key. Include only when the project is configurable.

low — Configuration section restates the "Sets defined elsewhere" detail list instead of pointing to it, unlike Usage
lens writing-quality · arm default · tally 1 valid / 0 invalid / 0 uncertain

What I examined: section "### 6. Configuration" and the new "## Sets defined elsewhere" section of skills/verify-readme/SKILL.md, both changed in this diff. I compared them with the Usage section (4), which ends with "See "Sets defined elsewhere" below for how to point at a set." I judged them against the writing-for-agents guidance "Give each instruction one clear home. Do not restate what ... an earlier sentence ... already says."

What the subject says: Configuration tells the agent to add "which settings a reader must set when the source doesn't mark them, why a default is what it is, and traps". "Sets defined elsewhere" already lists the same detail for any set, including env var schemas and config parsers: "what a member means and its units, why it exists, its gotchas, and which members the reader must set or run when the source doesn't mark them." The two lists are close paraphrases ("traps" vs "gotchas", "why a default is what it is" vs "why it exists"), and they differ slightly: Configuration leaves out meaning and units.

What goes wrong: an agent drafting a Configuration section gets two similar but different checklists and has to decide whether the shorter one overrides the general rule. It might skip units and meaning for a setting such as a timeout. Any future edit to the detail list also has to be made twice.

Proposed correction: "Point at the env var schema or config parser and any example config file, and add the detail they can't show (see "Sets defined elsewhere" below). A short fenced excerpt, labeled as an excerpt, can show the config file format; it shows the shape, not every key. Include only when the project is configurable." This keeps the Configuration-specific guidance (example config file, excerpt labeling, include-only-when-configurable) and leaves the detail checklist in one place. If "why a default is what it is" should apply to every set, move that wording into "Sets defined elsewhere". This finding comes from reading the text; I did not test it with an agent.

claim 01M3XR9580JSCCBGY2NFKV8NFD of review 01M3XR69KD21A4VCY038Z7E4DE

**low** — Configuration section restates the "Sets defined elsewhere" detail list instead of pointing to it, unlike Usage lens `writing-quality` · arm `default` · tally 1 valid / 0 invalid / 0 uncertain > What I examined: section "### 6. Configuration" and the new "## Sets defined elsewhere" section of skills/verify-readme/SKILL.md, both changed in this diff. I compared them with the Usage section (4), which ends with "See \"Sets defined elsewhere\" below for how to point at a set." I judged them against the writing-for-agents guidance "Give each instruction one clear home. Do not restate what ... an earlier sentence ... already says." > > What the subject says: Configuration tells the agent to add "which settings a reader must set when the source doesn't mark them, why a default is what it is, and traps". "Sets defined elsewhere" already lists the same detail for any set, including env var schemas and config parsers: "what a member means and its units, why it exists, its gotchas, and which members the reader must set or run when the source doesn't mark them." The two lists are close paraphrases ("traps" vs "gotchas", "why a default is what it is" vs "why it exists"), and they differ slightly: Configuration leaves out meaning and units. > > What goes wrong: an agent drafting a Configuration section gets two similar but different checklists and has to decide whether the shorter one overrides the general rule. It might skip units and meaning for a setting such as a timeout. Any future edit to the detail list also has to be made twice. > > Proposed correction: "Point at the env var schema or config parser and any example config file, and add the detail they can't show (see \"Sets defined elsewhere\" below). A short fenced excerpt, labeled as an excerpt, can show the config file format; it shows the shape, not every key. Include only when the project is configurable." This keeps the Configuration-specific guidance (example config file, excerpt labeling, include-only-when-configurable) and leaves the detail checklist in one place. If "why a default is what it is" should apply to every set, move that wording into "Sets defined elsewhere". This finding comes from reading the text; I did not test it with an agent. claim `01M3XR9580JSCCBGY2NFKV8NFD` of review `01M3XR69KD21A4VCY038Z7E4DE`

👍 1

superseded by review 01M3XWQCYY7CNKW93YBJPRSV25 for head 83f9b432f2c50361247a23b024ded728916a4f4c

superseded by review `01M3XWQCYY7CNKW93YBJPRSV25` for head `83f9b432f2c50361247a23b024ded728916a4f4c`

🚀 1

Fixed in bd1fb2f: Configuration now points at "Sets defined elsewhere" for the detail to add instead of restating it, and "why its default is what it is" moved into the shared list.

Fixed in bd1fb2f: Configuration now points at "Sets defined elsewhere" for the detail to add instead of restating it, and "why its default is what it is" moved into the shared list.

jercik marked this conversation as resolved

skills/verify-readme/SKILL.md Outdated

					
				@ -105,0 +108,4 @@

				When a file, directory, schema, or command already defines a set — `--help`, `package.json#scripts`, the env var schema or config parser, the workspace packages, a directory's children — the README names that source instead of listing the members or stating how many there are. A copy must change with every change to the set, and it goes stale silently when nobody updates it. Name a source the README's reader can reach: a command, a file the published package ships, an absolute repository URL, or, when the project isn't published, a repository-relative path.

				The README still tells the reader where each set lives, plus the detail the source can't show: what a member means and its units, why it exists, its gotchas, and which members the reader must set or run when the source doesn't mark them. A requirements list, a schema's `required`, or `--help` output that labels them required counts as marking them. Write that detail for the members that need it, without a count or a claim to cover them all, even when every member needs it; such a list may name every member. Move detail beside the member's definition, as a schema description or a comment, only when the task covers editing the source; otherwise keep it in the README, including detail carried by a restated list you remove.

medium — "Sets defined elsewhere" repeats the no-list/no-count rule in three paragraphs and leaves the allowed full-coverage detail list hard to tell apart from a forbidden restatement
lens writing-quality · arm default · tally 1 valid / 0 invalid / 0 uncertain

What I examined: the new "## Sets defined elsewhere" section of skills/verify-readme/SKILL.md, which the diff adds. I also read the Usage, Configuration, One-liner and Task step 6 edits that point to it or repeat it. I checked it against the writing-for-agents skill's "One Idea, One Place" guidance ("Do not restate what ... an earlier sentence ... already says"; "Make the decisive constraint prominent"; "cut a consequence or complement the first sentence already implies").

What the section says: the rule against counting appears three times. Paragraph 1 says the README names the source "instead of listing the members or stating how many there are". Paragraph 2 says to write detail "without a count or a claim to cover them all". Paragraph 3 says a list restates the set when it uses "a count word like "both" or "all" attached to listed members". Paragraph 2 opens with "The README still tells the reader where each set lives", which repeats paragraph 1's "names that source". The rationale "A copy must change with every change to the set, and it goes stale silently when nobody updates it" also says the same thing twice.

What goes wrong: the hard judgment for the agent is telling an allowed detail list apart from a forbidden copy, and that distinction is split across two paragraphs. Paragraph 2 ends with "such a list may name every member". Paragraph 3 then begins "Any other list that names every member restates the set". So the agent has to connect "such a list" with "Any other list" across the paragraph break to see that the only difference is whether the list carries per-member detail. The pronoun in "A requirements list, a schema's required, or --help output that labels them required counts as marking them" also makes the reader resolve "them" back to "members the reader must set or run". The most important edit-mode constraint, keeping the detail from a table you delete, comes last as a trailing clause: "including detail carried by a restated list you remove". An agent rewriting a README can easily miss it and delete useful gotchas together with the copied table.

Proposed correction (keeps every condition and the exceptions paragraph unchanged):

"When a file, directory, schema, or command already defines a set (...), name that source instead of listing or counting its members; a copy goes stale silently whenever the set changes. Name a source the README's reader can reach: ...

Add what the source can't show, for each member that needs it: what it means and its units, why it exists, its gotchas, and whether the reader must set or run it when the source (a requirements list, a schema's required, or --help) doesn't already say so. Don't introduce this list with a count or a claim of completeness, even when it ends up naming every member. When you remove a restated list, keep its detail: beside each member's definition when the task covers editing the source, otherwise in the README.

Every other list must be marked as examples. If it covers every member, it restates the set, whether it is a table, a sentence, a parenthetical, an "e.g.", or listed members joined by "both" or "all"."

What the rewrite improves: each condition is stated once. The detail-list exemption and the examples rule sit side by side. The keep-the-detail instruction becomes its own sentence. Evidence that would refute this: a test showing agents applying the current wording reliably keep per-member detail and never flag a detail list as a restatement. I did not run such a test; this claim is based on reading the text.

claim 01M3XR8VK5XGBETH73YM56TTJA of review 01M3XR69KD21A4VCY038Z7E4DE

**medium** — "Sets defined elsewhere" repeats the no-list/no-count rule in three paragraphs and leaves the allowed full-coverage detail list hard to tell apart from a forbidden restatement lens `writing-quality` · arm `default` · tally 1 valid / 0 invalid / 0 uncertain > What I examined: the new "## Sets defined elsewhere" section of skills/verify-readme/SKILL.md, which the diff adds. I also read the Usage, Configuration, One-liner and Task step 6 edits that point to it or repeat it. I checked it against the writing-for-agents skill's "One Idea, One Place" guidance ("Do not restate what ... an earlier sentence ... already says"; "Make the decisive constraint prominent"; "cut a consequence or complement the first sentence already implies"). > > What the section says: the rule against counting appears three times. Paragraph 1 says the README names the source "instead of listing the members or stating how many there are". Paragraph 2 says to write detail "without a count or a claim to cover them all". Paragraph 3 says a list restates the set when it uses "a count word like \"both\" or \"all\" attached to listed members". Paragraph 2 opens with "The README still tells the reader where each set lives", which repeats paragraph 1's "names that source". The rationale "A copy must change with every change to the set, and it goes stale silently when nobody updates it" also says the same thing twice. > > What goes wrong: the hard judgment for the agent is telling an allowed detail list apart from a forbidden copy, and that distinction is split across two paragraphs. Paragraph 2 ends with "such a list may name every member". Paragraph 3 then begins "Any other list that names every member restates the set". So the agent has to connect "such a list" with "Any other list" across the paragraph break to see that the only difference is whether the list carries per-member detail. The pronoun in "A requirements list, a schema's `required`, or `--help` output that labels them required counts as marking them" also makes the reader resolve "them" back to "members the reader must set or run". The most important edit-mode constraint, keeping the detail from a table you delete, comes last as a trailing clause: "including detail carried by a restated list you remove". An agent rewriting a README can easily miss it and delete useful gotchas together with the copied table. > > Proposed correction (keeps every condition and the exceptions paragraph unchanged): > > "When a file, directory, schema, or command already defines a set (...), name that source instead of listing or counting its members; a copy goes stale silently whenever the set changes. Name a source the README's reader can reach: ... > > Add what the source can't show, for each member that needs it: what it means and its units, why it exists, its gotchas, and whether the reader must set or run it when the source (a requirements list, a schema's `required`, or `--help`) doesn't already say so. Don't introduce this list with a count or a claim of completeness, even when it ends up naming every member. When you remove a restated list, keep its detail: beside each member's definition when the task covers editing the source, otherwise in the README. > > Every other list must be marked as examples. If it covers every member, it restates the set, whether it is a table, a sentence, a parenthetical, an \"e.g.\", or listed members joined by \"both\" or \"all\"." > > What the rewrite improves: each condition is stated once. The detail-list exemption and the examples rule sit side by side. The keep-the-detail instruction becomes its own sentence. Evidence that would refute this: a test showing agents applying the current wording reliably keep per-member detail and never flag a detail list as a restatement. I did not run such a test; this claim is based on reading the text. claim `01M3XR8VK5XGBETH73YM56TTJA` of review `01M3XR69KD21A4VCY038Z7E4DE`

👍 1

superseded by review 01M3XWQCYY7CNKW93YBJPRSV25 for head 83f9b432f2c50361247a23b024ded728916a4f4c

superseded by review `01M3XWQCYY7CNKW93YBJPRSV25` for head `83f9b432f2c50361247a23b024ded728916a4f4c`

🚀 1

Fixed in bd1fb2f: the section now states each condition once. The detail paragraph drops the repeated "where each set lives", keeping detail from a removed list is its own paragraph, and the list rule opens "A list without that detail restates the set", so the allowed detail list and the forbidden copy are told apart by name instead of across a paragraph break.

Fixed in bd1fb2f: the section now states each condition once. The detail paragraph drops the repeated "where each set lives", keeping detail from a removed list is its own paragraph, and the list rule opens "A list without that detail restates the set", so the allowed detail list and the forbidden copy are told apart by name instead of across a paragraph break.

jercik marked this conversation as resolved

jercik referenced this pull request

2026-10-02 08:29:07 +00:00

fix(skills): route skill references by their own headings instead of copied indexes #99

jercik added 1 commit

2026-10-02 08:47:02 +00:00

fix(verify-readme): allow tables of contents whose entries say what each item covers

commit-msg / commitlint (pull_request) Successful in 23s

Details

Node tests / node:test (pull_request) Successful in 1m28s

Details

Review / Review (pull_request_target) Successful in 18m40s

Details

83f9b432f2

forgejo-actions reviewed

2026-10-02 09:05:55 +00:00

skills/verify-readme/SKILL.md Outdated

					
				@ -70,2 +67,2 @@

				- **Config / dotfiles** — per-directory index linking to each sub-README; ordered setup steps.

				- **Monorepo** — a packages table with purpose and published name; link to each package's README.

				- **CLI** — point at `--help` for the flag reference; use this section for shell composition (pipelines, scripting). See "Pipeline patterns" below.

				- **Library** — show realistic usage, not toy snippets. Point at the type declarations or generated docs (TypeDoc, etc.) for the full API.

medium — Library API guidance has no fallback for JavaScript packages without types or generated docs
lens general-bug · arm default · tally 1 valid / 0 invalid / 0 uncertain

I read the full verify-readme skill and its library classification: a package with main or exports and no bin is a library even if it has no types field. The new Usage/API instruction nevertheless tells the agent to point readers at type declarations or generated docs for the full API. For a plain JavaScript library that has neither, those targets do not exist; following the instruction either yields a broken link or leaves readers without a full API reference. The new 'Sets defined elsewhere' rule also treats source exports as a defined set, so it does not clearly allow the previous in-README reference for a small API. Permit a source entry point or an in-README public API reference when declarations and generated docs are unavailable. This is a static contract inconsistency; the subject tree contains no example library README on which to run the skill, so an observed generated-README failure is unverified.

claim 01M3XWYFR1N4ZZBHFT9K0DD9T5 of review 01M3XWQCYY7CNKW93YBJPRSV25

**medium** — Library API guidance has no fallback for JavaScript packages without types or generated docs lens `general-bug` · arm `default` · tally 1 valid / 0 invalid / 0 uncertain > I read the full verify-readme skill and its library classification: a package with `main` or `exports` and no `bin` is a library even if it has no `types` field. The new Usage/API instruction nevertheless tells the agent to point readers at type declarations or generated docs for the full API. For a plain JavaScript library that has neither, those targets do not exist; following the instruction either yields a broken link or leaves readers without a full API reference. The new 'Sets defined elsewhere' rule also treats source exports as a defined set, so it does not clearly allow the previous in-README reference for a small API. Permit a source entry point or an in-README public API reference when declarations and generated docs are unavailable. This is a static contract inconsistency; the subject tree contains no example library README on which to run the skill, so an observed generated-README failure is unverified. claim `01M3XWYFR1N4ZZBHFT9K0DD9T5` of review `01M3XWQCYY7CNKW93YBJPRSV25`

👍 1

Fixed in bd1fb2f: the Library bullet now points at what defines the full API — the type declarations, generated docs, or, when neither exists, the entry point the package ships. I did not bring back an exhaustive in-README API reference: the user decided that prose restating a set defined elsewhere is a high defect, and the entry point defines the exports. Per-export detail the source cannot show is still allowed under "Sets defined elsewhere".

Fixed in bd1fb2f: the Library bullet now points at what defines the full API — the type declarations, generated docs, or, when neither exists, the entry point the package ships. I did not bring back an exhaustive in-README API reference: the user decided that prose restating a set defined elsewhere is a high defect, and the entry point defines the exports. Per-export detail the source cannot show is still allowed under "Sets defined elsewhere".

jercik marked this conversation as resolved

skills/verify-readme/SKILL.md Outdated

					
				@ -104,1 +106,4 @@

				## Sets defined elsewhere

				When a file, directory, schema, or command already defines a set — `--help`, `package.json#scripts`, the env var schema or config parser, the workspace packages, a directory's children — the README names that source instead of listing the members or stating how many there are. A copy must change with every change to the set, and it goes stale silently when nobody updates it. Name a source the README's reader can reach: a command, a file the published package ships, an absolute repository URL, or, when the project isn't published, a repository-relative path.

medium — The set rule conflicts with required CLI prerequisite lists
lens writing-quality · arm default · tally 1 valid / 0 invalid / 0 uncertain

I read the full verify-readme skill and its dependent CLI guidance in skills/verify-unixy-cli/references/arg8-document-external-dependencies.md. The new rule applies whenever a file or command defines a set, so a CLI README whose external dependencies are named in code and --help would be told to point to that source instead of listing the dependencies. The same skill's Requirements section explicitly calls for non-obvious external binaries such as git and gh, and ARG8 requires a Requirements or Prerequisites section listing all external dependencies while also mentioning them in help output. A user following the new general rule could remove the named installation prerequisites that ARG8 requires, leaving readers to discover missing binaries by running help or hitting startup errors. The exception for contracts visible only in the README does not apply because ARG8 also requires help to mention them. Reconcile the instructions by explicitly exempting installation prerequisites from the set rule and retaining their names in Requirements, while still pointing to help or code for version-specific details. This preserves the anti-drift rule for option and configuration inventories without weakening first-run setup. This is a static conflict between the two skill contracts; I did not execute a README rewrite.

claim 01M3XX9GAEJCK400ZY6RK1RDPM of review 01M3XWQCYY7CNKW93YBJPRSV25

**medium** — The set rule conflicts with required CLI prerequisite lists lens `writing-quality` · arm `default` · tally 1 valid / 0 invalid / 0 uncertain > I read the full verify-readme skill and its dependent CLI guidance in skills/verify-unixy-cli/references/arg8-document-external-dependencies.md. The new rule applies whenever a file or command defines a set, so a CLI README whose external dependencies are named in code and `--help` would be told to point to that source instead of listing the dependencies. The same skill's Requirements section explicitly calls for non-obvious external binaries such as `git` and `gh`, and ARG8 requires a Requirements or Prerequisites section listing all external dependencies while also mentioning them in help output. A user following the new general rule could remove the named installation prerequisites that ARG8 requires, leaving readers to discover missing binaries by running help or hitting startup errors. The exception for contracts visible only in the README does not apply because ARG8 also requires help to mention them. Reconcile the instructions by explicitly exempting installation prerequisites from the set rule and retaining their names in Requirements, while still pointing to help or code for version-specific details. This preserves the anti-drift rule for option and configuration inventories without weakening first-run setup. This is a static conflict between the two skill contracts; I did not execute a README rewrite. claim `01M3XX9GAEJCK400ZY6RK1RDPM` of review `01M3XWQCYY7CNKW93YBJPRSV25`

👍 1

Fixed in bd1fb2f on the ARG8 side. I declined the proposed exemption for prerequisites lists: the user decided that prose restating a set defined elsewhere is a high defect, with a fixed set of exceptions that does not include requirements lists. ARG8 now asks the README Requirements section to point at the help output naming the dependencies and add what help cannot show, such as install and auth steps. "Sets defined elsewhere" already allows a list carrying that per-dependency detail, so the two skills now give the same verdict on one README.

Fixed in bd1fb2f on the ARG8 side. I declined the proposed exemption for prerequisites lists: the user decided that prose restating a set defined elsewhere is a high defect, with a fixed set of exceptions that does not include requirements lists. ARG8 now asks the README Requirements section to point at the help output naming the dependencies and add what help cannot show, such as install and auth steps. "Sets defined elsewhere" already allows a list carrying that per-dependency detail, so the two skills now give the same verdict on one README.

jercik marked this conversation as resolved

jercik added 1 commit

2026-10-02 13:49:45 +00:00

fix(verify-readme): keep set detail in one place and align ARG8 with the set rule

commit-msg / commitlint (pull_request) Successful in 24s

Details

Node tests / node:test (pull_request) Successful in 2m5s

Details

Review / Review (pull_request_target) Successful in 6m52s

Details

bd1fb2fb7f

- Configuration points at "Sets defined elsewhere" instead of restating its
  detail list; "why its default is what it is" moves into the shared list.
- Restructure "Sets defined elsewhere" so each condition is stated once and
  keeping detail from a removed list is its own sentence.
- Library points at the shipped entry point when there are no type
  declarations or generated docs; Monorepo links package READMEs only where
  they exist.
- verify-unixy-cli ARG8 asks the README to point at the help output naming
  dependencies and add install and auth detail, instead of listing them all.

jercik referenced this pull request

2026-10-02 13:56:01 +00:00

fix(skills): point CLI docs and drift fixes at sources instead of restating sets #97

jercik referenced this pull request

2026-10-02 13:56:05 +00:00

fix(skills): point CLI docs and drift fixes at sources instead of restating sets #97

jercik referenced this pull request

2026-10-02 13:56:10 +00:00

fix(skills): point CLI docs and drift fixes at sources instead of restating sets #97

forgejo-actions reviewed

2026-10-02 13:59:47 +00:00

skills/verify-readme/SKILL.md Outdated

					
				@ -105,0 +110,4 @@

				Beside the source, the README adds the detail the source can't show, for each member that needs it: what the member means and its units, why it exists and why its default is what it is, its gotchas, and whether the reader must set or run it when the source doesn't mark it required. A requirements list, a schema's `required`, or `--help` output that labels a member required marks it. This detail may end up covering every member; don't introduce it with a count or a claim to cover them all.

				Keep that detail in the README unless the task covers editing the source; then move it beside the member's definition, as a schema description or a comment. When you remove a restated list, keep the detail it carried the same way.

medium — Keep reader-facing setup warnings visible in the README when editing source
lens writing-quality · arm default · tally 1 valid / 0 invalid / 0 uncertain

I read the full verify-readme skill, its changed "Sets defined elsewhere" guidance, the referenced human-facing-writing-style skill, and the neighboring CLI dependency rule. The preceding paragraph tells the README to add details a schema or parser cannot show, including meaning, units, defaults, gotchas, and whether users must set a value. This sentence then directs an agent to move that detail beside a source definition whenever the task also permits source edits, even if the destination is merely a code comment. For example, the skill's own DATABASE_URL migration-on-start warning could leave the README and appear only beside src/config.ts; a reader configuring the app from the README would no longer see the destructive setup caveat without opening implementation code. The writing standard says placement determines who sees content and to put facts near their audience. Keep operational and setup guidance in the README regardless of whether source is in scope, while adding machine-readable descriptions or code comments as appropriate; move only details that the linked source actually presents to the README reader. This preserves the rule against duplicating a complete option list. This is a static reading of the instructions; no consumer README was generated in this review.

claim 01M3YE9HX1S49M0C56FPC400CA of review 01M3YE1NRGYPFVPFNET8NH66AC

**medium** — Keep reader-facing setup warnings visible in the README when editing source lens `writing-quality` · arm `default` · tally 1 valid / 0 invalid / 0 uncertain > I read the full verify-readme skill, its changed "Sets defined elsewhere" guidance, the referenced human-facing-writing-style skill, and the neighboring CLI dependency rule. The preceding paragraph tells the README to add details a schema or parser cannot show, including meaning, units, defaults, gotchas, and whether users must set a value. This sentence then directs an agent to move that detail beside a source definition whenever the task also permits source edits, even if the destination is merely a code comment. For example, the skill's own DATABASE_URL migration-on-start warning could leave the README and appear only beside src/config.ts; a reader configuring the app from the README would no longer see the destructive setup caveat without opening implementation code. The writing standard says placement determines who sees content and to put facts near their audience. Keep operational and setup guidance in the README regardless of whether source is in scope, while adding machine-readable descriptions or code comments as appropriate; move only details that the linked source actually presents to the README reader. This preserves the rule against duplicating a complete option list. This is a static reading of the instructions; no consumer README was generated in this review. claim `01M3YE9HX1S49M0C56FPC400CA` of review `01M3YE1NRGYPFVPFNET8NH66AC`

👍 1

Fixed in b158887: a warning the reader needs before setting or running a member now stays in the README even when the task covers editing the source, like the DATABASE_URL warning in the Good example. Other detail still moves beside the member definition in that case, so it has one home.

Fixed in b158887: a warning the reader needs before setting or running a member now stays in the README even when the task covers editing the source, like the `DATABASE_URL` warning in the Good example. Other detail still moves beside the member definition in that case, so it has one home.

jercik marked this conversation as resolved

skills/verify-unixy-cli/references/arg8-document-external-dependencies.md Outdated

					
				@ -5,2 +5,2 @@

**Listed in README**: A "Requirements" or "Prerequisites" section listing all dependencies

**Mentioned in help output**: Either in the description or a dedicated section

**Mentioned in help output**: Either in the description or a dedicated section

**Covered in README**: A "Requirements" or "Prerequisites" section that points at the help output naming the dependencies and adds what it can't show, such as how to install and authenticate each one (see "Sets defined elsewhere" in the verify-readme skill)

medium — Keep dependency help available when a prerequisite is missing
lens writing-quality · arm default · tally 1 valid / 0 invalid / 0 uncertain

I read the full changed ARG8 reference, verify-readme's new "Sets defined elsewhere" rule, and the adjacent ARG9 help-diagnostics reference. ARG8 now tells an agent to make the Requirements section point to --help as the place that names external binaries. The same ARG8 reference requires checking each binary at startup and gives an example that catches a missing gh and calls process.exit(1). If that check runs before argument handling, mycli --help exits before printing the dependency names, so a reader with the missing prerequisite gets a README pointer they cannot follow. ARG9 says help should display missing-requirement diagnostics, but ARG8 neither qualifies its startup example nor states the required ordering; an agent implementing the shown check can satisfy the literal startup instruction and break the documentation path. Say explicitly that --help must render dependency names and installation guidance even when checks fail, with the fatal check applied only to commands that need the dependency. This preserves a single authoritative list in help while keeping the README pointer usable. The impact follows from static control-flow reasoning; I did not run a consumer CLI.

claim 01M3YEBR7V2DYXG78SDFZSHMZ2 of review 01M3YE1NRGYPFVPFNET8NH66AC

**medium** — Keep dependency help available when a prerequisite is missing lens `writing-quality` · arm `default` · tally 1 valid / 0 invalid / 0 uncertain > I read the full changed ARG8 reference, verify-readme's new "Sets defined elsewhere" rule, and the adjacent ARG9 help-diagnostics reference. ARG8 now tells an agent to make the Requirements section point to --help as the place that names external binaries. The same ARG8 reference requires checking each binary at startup and gives an example that catches a missing gh and calls process.exit(1). If that check runs before argument handling, `mycli --help` exits before printing the dependency names, so a reader with the missing prerequisite gets a README pointer they cannot follow. ARG9 says help should display missing-requirement diagnostics, but ARG8 neither qualifies its startup example nor states the required ordering; an agent implementing the shown check can satisfy the literal startup instruction and break the documentation path. Say explicitly that --help must render dependency names and installation guidance even when checks fail, with the fatal check applied only to commands that need the dependency. This preserves a single authoritative list in help while keeping the README pointer usable. The impact follows from static control-flow reasoning; I did not run a consumer CLI. claim `01M3YEBR7V2DYXG78SDFZSHMZ2` of review `01M3YE1NRGYPFVPFNET8NH66AC`

👍 1

Fixed in b158887: ARG8 now runs the dependency check after --help and --version are handled, so help still names the dependencies when one is missing (matching ARG9), and the example comment says the same.

Fixed in b158887: ARG8 now runs the dependency check after `--help` and `--version` are handled, so help still names the dependencies when one is missing (matching ARG9), and the example comment says the same.

jercik marked this conversation as resolved

jercik added 1 commit

2026-10-02 14:01:23 +00:00

fix(verify-readme): keep setup warnings in the readme and let help name missing dependencies

commit-msg / commitlint (pull_request) Successful in 19s

Details

Node tests / node:test (pull_request) Successful in 1m2s

Details

Review / Review (pull_request_target) Successful in 11m27s

Details

b158887d26

- "Sets defined elsewhere" keeps a warning the reader needs before setting
  or running a member in the README even when other detail moves into the
  source.
- verify-unixy-cli ARG8 runs dependency checks after --help and --version,
  so the help output the README points at still names a missing dependency.

jercik referenced this pull request

2026-10-02 14:07:52 +00:00

fix(skills): point CLI docs and drift fixes at sources instead of restating sets #97

jercik referenced this pull request

2026-10-02 14:07:55 +00:00

fix(skills): point CLI docs and drift fixes at sources instead of restating sets #97

forgejo-actions reviewed

2026-10-02 14:12:48 +00:00

skills/verify-readme/SKILL.md Outdated

					
				@ -104,1 +106,4 @@

				## Sets defined elsewhere

				When a file, directory, schema, or command already defines a set — `--help`, `package.json#scripts`, the env var schema or config parser, the workspace packages, a directory's children — the README names that source instead of listing the members or stating how many there are. A copy must change with every change to the set, and nothing flags it when it doesn't. Name a source the README's reader can reach: a command, a file the published package ships, an absolute repository URL, or, when the project isn't published, a repository-relative path.

low — Include hosted generated documentation among reachable API sources
lens writing-quality · arm default · tally 1 valid / 0 invalid / 0 uncertain

I read the full verify-readme skill. Its Library Usage/API bullet explicitly allows a link to generated docs such as TypeDoc, but this new source-selection sentence lists only a command, a file shipped with the package, an absolute repository URL, or a repository-relative path for unpublished projects. Hosted generated API docs are none of those. An agent applying both instructions may replace the intended API-doc link with a source-file link, leaving readers to infer parameter and return-value contracts from code. This is a conflict in the text; no target library was run. Include an ordinary URL to version-matched generated docs in the reachable-source options, or mark the list as examples. That keeps the single-source intent while preserving the Library bullet's more useful destination. A separate statement that the list is non-exhaustive would refute the strict reading; the current sentence does not say that.

claim 01M3YF2BBE3G7C6PQ3N7P451VW of review 01M3YEPZJ8KVE8TY42JWJ3T417

**low** — Include hosted generated documentation among reachable API sources lens `writing-quality` · arm `default` · tally 1 valid / 0 invalid / 0 uncertain > I read the full verify-readme skill. Its Library Usage/API bullet explicitly allows a link to generated docs such as TypeDoc, but this new source-selection sentence lists only a command, a file shipped with the package, an absolute repository URL, or a repository-relative path for unpublished projects. Hosted generated API docs are none of those. An agent applying both instructions may replace the intended API-doc link with a source-file link, leaving readers to infer parameter and return-value contracts from code. This is a conflict in the text; no target library was run. Include an ordinary URL to version-matched generated docs in the reachable-source options, or mark the list as examples. That keeps the single-source intent while preserving the Library bullet's more useful destination. A separate statement that the list is non-exhaustive would refute the strict reading; the current sentence does not say that. claim `01M3YF2BBE3G7C6PQ3N7P451VW` of review `01M3YEPZJ8KVE8TY42JWJ3T417`

👍 1

Fixed in 4a07089: the reachable-source list now includes a hosted docs URL, so the Library bullet pointer to generated docs fits it.

Fixed in 4a07089: the reachable-source list now includes a hosted docs URL, so the Library bullet pointer to generated docs fits it.

jercik marked this conversation as resolved

skills/verify-unixy-cli/references/arg8-document-external-dependencies.md Outdated

					
				@ -5,2 +5,2 @@

**Listed in README**: A "Requirements" or "Prerequisites" section listing all dependencies

**Mentioned in help output**: Either in the description or a dedicated section

**Mentioned in help output**: Either in the description or a dedicated section

**Covered in README**: A "Requirements" or "Prerequisites" section that points at the help output naming the dependencies and adds what it can't show, such as how to install and authenticate each one (see "Sets defined elsewhere" in the verify-readme skill)

low — Limit authentication guidance to dependencies that require it
lens writing-quality · arm default · tally 1 valid / 0 invalid / 0 uncertain

I read the full ARG8 reference and the verify-readme section it invokes. ARG8 names git, docker, and ffmpeg as possible external tools, but this new sentence asks for instructions to "install and authenticate each one." ffmpeg, for example, has no authentication step. Following the wording produces invented or irrelevant README requirements and makes a real prerequisite harder to identify. This is a textual mismatch with ARG8's own examples; I did not run a CLI. Say "how to install each dependency and, where applicable, how to authenticate it". That keeps the installation guidance and narrows authentication to tools such as gh. A specification that every named external tool requires authentication would refute the claim; the rule includes tools that do not.

claim 01M3YF1H0851H8VQRT0Y92M5H9 of review 01M3YEPZJ8KVE8TY42JWJ3T417

**low** — Limit authentication guidance to dependencies that require it lens `writing-quality` · arm `default` · tally 1 valid / 0 invalid / 0 uncertain > I read the full ARG8 reference and the verify-readme section it invokes. ARG8 names `git`, `docker`, and `ffmpeg` as possible external tools, but this new sentence asks for instructions to "install and authenticate each one." `ffmpeg`, for example, has no authentication step. Following the wording produces invented or irrelevant README requirements and makes a real prerequisite harder to identify. This is a textual mismatch with ARG8's own examples; I did not run a CLI. Say "how to install each dependency and, where applicable, how to authenticate it". That keeps the installation guidance and narrows authentication to tools such as `gh`. A specification that every named external tool requires authentication would refute the claim; the rule includes tools that do not. claim `01M3YF1H0851H8VQRT0Y92M5H9` of review `01M3YEPZJ8KVE8TY42JWJ3T417`

👍 1

Fixed in 4a07089: ARG8 now asks how to install each dependency and, for one that needs it, how to authenticate it.

Fixed in 4a07089: ARG8 now asks how to install each dependency and, for one that needs it, how to authenticate it.

jercik marked this conversation as resolved

skills/verify-unixy-cli/references/arg8-document-external-dependencies.md Outdated

					
				@ -7,2 +6,3 @@

**Covered in README**: A "Requirements" or "Prerequisites" section that points at the help output naming the dependencies and adds what it can't show, such as how to install and authenticate each one (see "Sets defined elsewhere" in the verify-readme skill)

**Configurable via environment variable**: A per-dependency env var for custom paths (e.g., `MYCLI_GH_PATH`, `MYCLI_GIT_PATH`)

**Checked at startup**: With actionable error messages if missing

**Checked at startup**: With actionable error messages if missing. Run the check after `--help` and `--version` are handled, so help still names the dependencies when one is missing (see ARG9)

medium — Distinguish help status checks from fatal dependency validation
lens writing-quality · arm default · tally 1 valid / 0 invalid / 0 uncertain

I read ARG8 in full and followed its ARG9 cross-reference. ARG8 now says to run the dependency check after --help and --version are handled. ARG9, however, requires --help to call a status check for each prerequisite and render a contextual Requires: line with MISSING or NOT AUTHORIZED remediation. A literal implementation of the new ARG8 order leaves help unable to show the diagnostics ARG9 promises; the example comment repeats the same order. This is a conflict in the written contract, established by those two reference files rather than by running a CLI. Say that --help performs non-fatal status checks to render diagnostics, while the fatal startup validation runs only after help and version have exited. That preserves access to help when a binary is missing and preserves ARG9 diagnostics. A separate explicit definition of two different checks would refute the ambiguity; the current ARG8 passage has none.

claim 01M3YEXZ41P6M4GEN0019DND7P of review 01M3YEPZJ8KVE8TY42JWJ3T417

**medium** — Distinguish help status checks from fatal dependency validation lens `writing-quality` · arm `default` · tally 1 valid / 0 invalid / 0 uncertain > I read ARG8 in full and followed its ARG9 cross-reference. ARG8 now says to run the dependency check after `--help` and `--version` are handled. ARG9, however, requires `--help` to call a status check for each prerequisite and render a contextual `Requires:` line with `MISSING` or `NOT AUTHORIZED` remediation. A literal implementation of the new ARG8 order leaves help unable to show the diagnostics ARG9 promises; the example comment repeats the same order. This is a conflict in the written contract, established by those two reference files rather than by running a CLI. Say that `--help` performs non-fatal status checks to render diagnostics, while the fatal startup validation runs only after help and version have exited. That preserves access to help when a binary is missing and preserves ARG9 diagnostics. A separate explicit definition of two different checks would refute the ambiguity; the current ARG8 passage has none. claim `01M3YEXZ41P6M4GEN0019DND7P` of review `01M3YEPZJ8KVE8TY42JWJ3T417`

👍 1

Fixed in 4a07089: ARG8 now calls its startup check the fatal one and runs it after --help and --version; help runs its own non-fatal status checks to show the Requires diagnostics in ARG9. The example comment says the same.

Fixed in 4a07089: ARG8 now calls its startup check the fatal one and runs it after `--help` and `--version`; help runs its own non-fatal status checks to show the `Requires` diagnostics in ARG9. The example comment says the same.

jercik marked this conversation as resolved

jercik added 1 commit

2026-10-02 14:17:24 +00:00

fix(verify-readme): allow hosted docs as a set source and separate fatal dependency checks from help

commit-msg / commitlint (pull_request) Successful in 25s

Details

Node tests / node:test (pull_request) Successful in 1m30s

Details

Review / Review (pull_request_target) Successful in 10m9s

Details

4a0708998a

- "Sets defined elsewhere" accepts a hosted docs URL as a source the reader
  can reach, matching the Library bullet's generated-docs pointer.
- verify-unixy-cli ARG8 asks for auth guidance only for dependencies that
  need it, and says help keeps its own non-fatal status checks for ARG9's
  Requires diagnostics while the fatal check runs after help and version.

jercik referenced this pull request

2026-10-02 14:23:43 +00:00

fix(skills): point CLI docs and drift fixes at sources instead of restating sets #97

forgejo-actions reviewed

2026-10-02 14:27:32 +00:00

skills/verify-readme/SKILL.md

					
				@ -105,0 +110,4 @@

				Beside the source, the README adds the detail the source can't show, for each member that needs it: what the member means and its units, why it exists and why its default is what it is, its gotchas, and whether the reader must set or run it when the source doesn't mark it required. A requirements list, a schema's `required`, or `--help` output that labels a member required marks it. This detail may end up covering every member; don't introduce it with a count or a claim to cover them all.

				Keep that detail in the README unless the task covers editing the source; then move it beside the member's definition, as a schema description or a comment. A warning the reader needs before setting or running a member stays in the README either way, like the `DATABASE_URL` warning in the Good example below. When you remove a restated list, keep the detail it carried the same way.

medium — Moving README explanations into source comments can hide them from the linked user-facing source
lens writing-quality · arm default · tally 1 valid / 0 invalid / 0 uncertain

I read the full verify-readme skill and its CLI cross-reference, plus ARG8 and ARG9 in verify-unixy-cli. This paragraph first requires the README to add meanings, units, default rationale, gotchas, and requiredness when the referenced source cannot show them. It then says to move that detail into a schema description or a comment whenever the task also edits the source. For a CLI README that points readers to --help, a comment beside a flag declaration never appears in --help; similarly, an implementation comment may not appear in generated API docs. A combined CLI-and-README edit can therefore delete useful explanation from the README while leaving the reader with only a link to output that still lacks it. The installed writing guide calls for placing content where its audience can see it and preserving non-obvious facts. Limit the move to descriptions actually rendered in the linked help/docs, and keep other detail in the README with the link. This retains one authoritative explanation without making users inspect implementation comments. This is a static audience-and-surface mismatch; a project that publishes the comments as linked reference documentation would avoid it.

claim 01M3YG2EXKPBGNWWZB319THHZ0 of review 01M3YFMB4XNPJMN56TY04SEGG4

**medium** — Moving README explanations into source comments can hide them from the linked user-facing source lens `writing-quality` · arm `default` · tally 1 valid / 0 invalid / 0 uncertain > I read the full verify-readme skill and its CLI cross-reference, plus ARG8 and ARG9 in verify-unixy-cli. This paragraph first requires the README to add meanings, units, default rationale, gotchas, and requiredness when the referenced source cannot show them. It then says to move that detail into a schema description or a comment whenever the task also edits the source. For a CLI README that points readers to --help, a comment beside a flag declaration never appears in --help; similarly, an implementation comment may not appear in generated API docs. A combined CLI-and-README edit can therefore delete useful explanation from the README while leaving the reader with only a link to output that still lacks it. The installed writing guide calls for placing content where its audience can see it and preserving non-obvious facts. Limit the move to descriptions actually rendered in the linked help/docs, and keep other detail in the README with the link. This retains one authoritative explanation without making users inspect implementation comments. This is a static audience-and-surface mismatch; a project that publishes the comments as linked reference documentation would avoid it. claim `01M3YG2EXKPBGNWWZB319THHZ0` of review `01M3YFMB4XNPJMN56TY04SEGG4`

🚀 1

jercik marked this conversation as resolved

skills/verify-unixy-cli/references/arg8-document-external-dependencies.md

					
				@ -5,2 +5,2 @@

**Listed in README**: A "Requirements" or "Prerequisites" section listing all dependencies

**Mentioned in help output**: Either in the description or a dedicated section

**Mentioned in help output**: Either in the description or a dedicated section

**Covered in README**: A "Requirements" or "Prerequisites" section that points at the help output naming the dependencies and adds what it can't show, such as how to install each one and, for one that needs it, how to authenticate it (see "Sets defined elsewhere" in the verify-readme skill)

medium — README guidance treats installation and authentication as absent from help despite ARG9 requiring them there
lens writing-quality · arm default · tally 1 valid / 0 invalid / 0 uncertain

I read the full ARG8 rule, the linked verify-readme skill, and ARG9 contextual Requires rule. ARG8 says the README should add what help cannot show, specifically installation and authentication instructions. ARG9 requires each command dependency to have install guidance and an optional auth fix, renders inline fixes in --help, and its examples show both an install URL and gh auth login. An agent applying both rules cannot tell which details belong only in the README; following ARG8 examples duplicates help text, while avoiding duplication can make the README look incomplete under ARG8 verification. The writing guide says to state each fact once and keep related rules consistent. Revise ARG8 to point at live help for dependency names and short install/auth fixes, and ask the README for only setup detail that help does not actually contain, such as platform-specific steps or prerequisite versions. This preserves the README setup role while giving each instruction one source. Static comparison establishes the conflict; an implementation where help omits install/auth fixes would refute it for that CLI, but would then fail ARG9.

claim 01M3YFWA3JE9K7NEPRKPZV5Y09 of review 01M3YFMB4XNPJMN56TY04SEGG4

**medium** — README guidance treats installation and authentication as absent from help despite ARG9 requiring them there lens `writing-quality` · arm `default` · tally 1 valid / 0 invalid / 0 uncertain > I read the full ARG8 rule, the linked verify-readme skill, and ARG9 contextual Requires rule. ARG8 says the README should add what help cannot show, specifically installation and authentication instructions. ARG9 requires each command dependency to have install guidance and an optional auth fix, renders inline fixes in --help, and its examples show both an install URL and gh auth login. An agent applying both rules cannot tell which details belong only in the README; following ARG8 examples duplicates help text, while avoiding duplication can make the README look incomplete under ARG8 verification. The writing guide says to state each fact once and keep related rules consistent. Revise ARG8 to point at live help for dependency names and short install/auth fixes, and ask the README for only setup detail that help does not actually contain, such as platform-specific steps or prerequisite versions. This preserves the README setup role while giving each instruction one source. Static comparison establishes the conflict; an implementation where help omits install/auth fixes would refute it for that CLI, but would then fail ARG9. claim `01M3YFWA3JE9K7NEPRKPZV5Y09` of review `01M3YFMB4XNPJMN56TY04SEGG4`

🚀 1

jercik marked this conversation as resolved

jercik commented

2026-10-02 14:28:39 +00:00

Replying to review comment #103989

Acknowledged, not fixed in this PR: this finding arrived in review round 4, where only clear, severe bugs get another push, and this one is a real but small wording gap. A comment beside a flag declaration never reaches --help, so the move can hide detail from the reader the README points there.

Deferred to a follow-up PR. In skills/verify-readme/SKILL.md, "Sets defined elsewhere", third paragraph, replace "then move it beside the member's definition, as a schema description or a comment" with "then move it into a description the linked source shows its reader, such as a schema description or a --help option description, and keep any other detail in the README".

> Replying to review comment #103989 Acknowledged, not fixed in this PR: this finding arrived in review round 4, where only clear, severe bugs get another push, and this one is a real but small wording gap. A comment beside a flag declaration never reaches `--help`, so the move can hide detail from the reader the README points there. Deferred to a follow-up PR. In `skills/verify-readme/SKILL.md`, "Sets defined elsewhere", third paragraph, replace "then move it beside the member's definition, as a schema description or a comment" with "then move it into a description the linked source shows its reader, such as a schema description or a `--help` option description, and keep any other detail in the README".

jercik commented

2026-10-02 14:28:39 +00:00

Replying to review comment #103990

Acknowledged, not fixed in this PR: this finding arrived in review round 4, where only clear, severe bugs get another push, and this one is a real but small overlap. ARG9 has --help print install and auth fixes for a missing dependency, so ARG8's "how to install each one and ... how to authenticate it" can duplicate them in the README.

Deferred to a follow-up PR. In skills/verify-unixy-cli/references/arg8-document-external-dependencies.md, item 2, replace "such as how to install each one and, for one that needs it, how to authenticate it" with "such as platform-specific install steps or a minimum version, beyond the short fix --help prints for a missing dependency (ARG9)".

> Replying to review comment #103990 Acknowledged, not fixed in this PR: this finding arrived in review round 4, where only clear, severe bugs get another push, and this one is a real but small overlap. ARG9 has `--help` print install and auth fixes for a missing dependency, so ARG8's "how to install each one and ... how to authenticate it" can duplicate them in the README. Deferred to a follow-up PR. In `skills/verify-unixy-cli/references/arg8-document-external-dependencies.md`, item 2, replace "such as how to install each one and, for one that needs it, how to authenticate it" with "such as platform-specific install steps or a minimum version, beyond the short fix `--help` prints for a missing dependency (ARG9)".

jercik referenced this pull request

2026-10-02 14:34:20 +00:00

fix(skills): point CLI docs and drift fixes at sources instead of restating sets #97

jercik referenced this pull request

2026-10-02 14:34:34 +00:00

fix(skills): point CLI docs and drift fixes at sources instead of restating sets #97

jercik merged commit 92b9e1b50d into main

2026-10-03 08:08:41 +00:00

jercik deleted branch fix/verify-readme-point-to-sources

2026-10-03 08:08:41 +00:00

jercik referenced this pull request from a commit

2026-10-03 08:08:41 +00:00

fix(verify-readme): point READMEs at the sources of sets instead of copying them (#96)

jercik referenced this pull request

2026-10-03 23:40:21 +00:00

fix(skills): point CLI docs and drift fixes at sources instead of restating sets #97

Sign in to join this conversation.

No reviewers

No labels

No milestone

No assignees

2 participants

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

j4k-oss/agent-skills!96

 @ -5,2 +5,2 @@
 . **Listed in README**: A "Requirements" or "Prerequisites" section listing all dependencies
 . **Mentioned in help output**: Either in the description or a dedicated section
 . **Mentioned in help output**: Either in the description or a dedicated section
 . **Covered in README**: A "Requirements" or "Prerequisites" section that points at the help output naming the dependencies and adds what it can't show, such as how to install and authenticate each one (see "Sets defined elsewhere" in the verify-readme skill)

 @ -5,2 +5,2 @@
 . **Listed in README**: A "Requirements" or "Prerequisites" section listing all dependencies
 . **Mentioned in help output**: Either in the description or a dedicated section
 . **Mentioned in help output**: Either in the description or a dedicated section
 . **Covered in README**: A "Requirements" or "Prerequisites" section that points at the help output naming the dependencies and adds what it can't show, such as how to install and authenticate each one (see "Sets defined elsewhere" in the verify-readme skill)

 @ -7,2 +6,3 @@
 . **Covered in README**: A "Requirements" or "Prerequisites" section that points at the help output naming the dependencies and adds what it can't show, such as how to install and authenticate each one (see "Sets defined elsewhere" in the verify-readme skill)
 . **Configurable via environment variable**: A per-dependency env var for custom paths (e.g., `MYCLI_GH_PATH`, `MYCLI_GIT_PATH`)
 . **Checked at startup**: With actionable error messages if missing
 . **Checked at startup**: With actionable error messages if missing. Run the check after `--help` and `--version` are handled, so help still names the dependencies when one is missing (see ARG9)

 @ -5,2 +5,2 @@
 . **Listed in README**: A "Requirements" or "Prerequisites" section listing all dependencies
 . **Mentioned in help output**: Either in the description or a dedicated section
 . **Mentioned in help output**: Either in the description or a dedicated section
 . **Covered in README**: A "Requirements" or "Prerequisites" section that points at the help output naming the dependencies and adds what it can't show, such as how to install each one and, for one that needs it, how to authenticate it (see "Sets defined elsewhere" in the verify-readme skill)

Rows
Columns