fix(skills): load the binding ADR decision contract #114

jercik · 2026-10-04T04:30:46Z

jercik commented

2026-10-04 04:30:46 +00:00

Delivers and loads project-docs when the user changes an ADR decision, as the existing doc-drift contract already requires. Keeps accepted and status-less ADR authority and the user's decision gate.

Addresses the dependency-loading finding in #113. This targets main independently because its ADR contract is already present there. Whitespace checks pass; the historical 137/138 local workflow failure remains separate from the 35 passing selected tests.

Delivers and loads `project-docs` when the user changes an ADR decision, as the existing doc-drift contract already requires. Keeps accepted and status-less ADR authority and the user's decision gate. Addresses the dependency-loading finding in [#113](https://code.j4k.dev/j4k-oss/agent-skills/pulls/113). This targets main independently because its ADR contract is already present there. Whitespace checks pass; the historical 137/138 local workflow failure remains separate from the 35 passing selected tests.

jercik added 1 commit

2026-10-04 04:30:46 +00:00

fix: load the existing ADR decision contract

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

Details

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

Details

Review / Review (pull_request_target) Successful in 3m52s

Details

85347515c5

jercik referenced this pull request

2026-10-04 04:32:16 +00:00

fix(skills): report unavailable release claims as unverified #113

forgejo-actions commented

2026-10-04 04:34:37 +00:00

Review 01M42K5F9RH3FBNF9PQDXA0NT3 — head 24f33de8f42786b0ac63a4a210629389deac3925

Review — j4k-oss/agent-skills @ `566f80735b`

Scope: diff against base tree 2034125557e6
Status: dispatched — coverage complete (4/4 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)

high — The `description` frontmatter copies the four finding-category names that the body's "Finding categories" section defines

claim: 01M42K899AV6GN66ZAEXRFRHD9
anchor: skills/verify-doc-drift/SKILL.md (snippet)

Each finding is categorized (incorrect / code-drift / obvious / duplicate)

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

I read the whole of skills/verify-doc-drift/SKILL.md, which this diff modifies by adding metadata to the frontmatter and rewording the ADR paragraph. The body's ## Finding categories section defines the set: "Classify every discrepancy as exactly one of:" followed by bullets for incorrect, code-drift, obvious, and duplicate, each with its definition. The frontmatter description repeats every member: "Each finding is categorized (incorrect / code-drift / obvious / duplicate)".

Under the restated-sets guideline, that list in the description is a second copy of a set whose source is the body section. If someone adds, renames, or merges a category in the body, nothing forces the description to change with it. The description also goes into the skill catalog in every session, where a stale copy misleads routing and costs context, and the router never needs the category names to choose this skill. No exception applies: the description is not what the agent classifies against, and the router does not use the members.

Correction: delete the parenthetical, and with it the clause "Each finding is categorized (...) and adversarially verified against the code before it is reported". The body is still the only home for the categories, and their definitions are unchanged. My separate claim on this description (vdd-desc-method-summary) proposes a full Use when … rewrite that also leaves out this list. Decisive evidence: the description line and the ## Finding categories bullets in the same file name the same four members.

low — The intro restates the fix-direction rule that "Fix direction and missing features" owns

claim: 01M42K8ZHPCJKQ460VGVKZBK58
anchor: skills/verify-doc-drift/SKILL.md (snippet)

Default direction: fix the docs to match the code — reverse it only when the doc is the intended source of truth.

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

I read skills/verify-doc-drift/SKILL.md in full. The diff rewrites its "Fix direction and missing features" paragraph. The opening paragraph ends with: "Default direction: fix the docs to match the code — reverse it only when the doc is the intended source of truth." The section the diff edits opens with the same rule in more precise form: "Fix docs to match code by default. Change code only for a confirmed code-drift where the doc is the intended source of truth." That section then adds the missing-feature fork and the ADR status rules, which the intro does not mention.

The writing skill's "One Idea, One Place" guidance says to give each instruction one home and not restate what an earlier sentence says. Having two copies costs every reader, and the copies already differ. The intro version leaves out that reversing the direction requires a confirmed code-drift finding, and it omits the ADR rules. An editor who later changes the fix-direction rule in the section can easily miss the intro, and the two will then conflict.

Correction: delete this sentence from the intro. The opening paragraph still says what the skill does ("treats every concrete claim a doc makes as a hypothesis… then repairs the loser"). The fix direction stays complete in its own section, which every reader reaches before the Task steps that apply fixes. Nothing is lost, because every condition in the deleted sentence appears in the section's first two sentences.

Other claims

grounding-pending (0)
ungrounded (0)
rejected (0)
duplicate-of (0)
unadjudicated (1)
- 01M42K8PAR15TF25RV47ZKZ7QY medium — verify-doc-drift's description summarizes the skill's method instead of starting with a Use when … routing rule

Coverage

Coverage pass: 01M42K5FB0GF96BGWYY8JJJP4Q
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
restated-sets	whole	default	no-claims	1	no

**Review** `01M42K5F9RH3FBNF9PQDXA0NT3` — head `24f33de8f42786b0ac63a4a210629389deac3925` # Review — j4k-oss/agent-skills @ 566f80735be9 Scope: diff against base tree `2034125557e6` Status: dispatched — coverage complete (4/4 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) ### high — The `description` frontmatter copies the four finding-category names that the body's "Finding categories" section defines - claim: `01M42K899AV6GN66ZAEXRFRHD9` - anchor: `skills/verify-doc-drift/SKILL.md` (snippet) ``` Each finding is categorized (incorrect / code-drift / obvious / duplicate) ``` - lens: writing-quality · arm: default - verdicts: 1 valid / 0 invalid / 0 uncertain - disposition: none > I read the whole of skills/verify-doc-drift/SKILL.md, which this diff modifies by adding `metadata` to the frontmatter and rewording the ADR paragraph. The body's `## Finding categories` section defines the set: "Classify every discrepancy as exactly one of:" followed by bullets for **incorrect**, **code-drift**, **obvious**, and **duplicate**, each with its definition. The frontmatter `description` repeats every member: "Each finding is categorized (incorrect / code-drift / obvious / duplicate)". > > Under the restated-sets guideline, that list in the description is a second copy of a set whose source is the body section. If someone adds, renames, or merges a category in the body, nothing forces the description to change with it. The description also goes into the skill catalog in every session, where a stale copy misleads routing and costs context, and the router never needs the category names to choose this skill. No exception applies: the description is not what the agent classifies against, and the router does not use the members. > > Correction: delete the parenthetical, and with it the clause "Each finding is categorized (...) and adversarially verified against the code before it is reported". The body is still the only home for the categories, and their definitions are unchanged. My separate claim on this description (vdd-desc-method-summary) proposes a full `Use when …` rewrite that also leaves out this list. Decisive evidence: the description line and the `## Finding categories` bullets in the same file name the same four members. ### low — The intro restates the fix-direction rule that "Fix direction and missing features" owns - claim: `01M42K8ZHPCJKQ460VGVKZBK58` - anchor: `skills/verify-doc-drift/SKILL.md` (snippet) ``` Default direction: fix the docs to match the code — reverse it only when the doc is the intended source of truth. ``` - lens: writing-quality · arm: default - verdicts: 1 valid / 0 invalid / 0 uncertain - disposition: none > I read skills/verify-doc-drift/SKILL.md in full. The diff rewrites its "Fix direction and missing features" paragraph. The opening paragraph ends with: "Default direction: fix the docs to match the code — reverse it only when the doc is the intended source of truth." The section the diff edits opens with the same rule in more precise form: "Fix docs to match code by default. Change code only for a confirmed **code-drift** where the doc is the intended source of truth." That section then adds the missing-feature fork and the ADR status rules, which the intro does not mention. > > The writing skill's "One Idea, One Place" guidance says to give each instruction one home and not restate what an earlier sentence says. Having two copies costs every reader, and the copies already differ. The intro version leaves out that reversing the direction requires a *confirmed* code-drift finding, and it omits the ADR rules. An editor who later changes the fix-direction rule in the section can easily miss the intro, and the two will then conflict. > > Correction: delete this sentence from the intro. The opening paragraph still says what the skill does ("treats every concrete claim a doc makes as a hypothesis… then repairs the loser"). The fix direction stays complete in its own section, which every reader reaches before the Task steps that apply fixes. Nothing is lost, because every condition in the deleted sentence appears in the section's first two sentences. ## Other claims - grounding-pending (0) - ungrounded (0) - rejected (0) - duplicate-of (0) - unadjudicated (1) - `01M42K8PAR15TF25RV47ZKZ7QY` medium — verify-doc-drift's `description` summarizes the skill's method instead of starting with a `Use when …` routing rule ## Coverage Coverage pass: 01M42K5FB0GF96BGWYY8JJJP4Q 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 | | restated-sets | whole | default | no-claims | 1 | no |

👀 1

forgejo-actions reviewed

2026-10-04 04:34:38 +00:00

skills/verify-doc-drift/SKILL.md Outdated

					
				@ -35,3 +37,3 @@

				## Fix direction and missing features

				Fix docs to match code by default. Change code only for a confirmed **code-drift** where the doc is the intended source of truth. A third case hides inside "incorrect": the doc describes a capability that _should_ exist but doesn't (an endpoint, a flag). Removing the claim and _implementing_ the feature are both valid — surface the fork to the user, and if the claim is removed, flag the missing feature as separate work rather than silently dropping it. ADRs are decision records, not behaviour docs. A `proposed` ADR is an open question: correct its statement of current behaviour if the code contradicts it, never delete it as stale. An `accepted` or status-less ADR is the source of truth for the decision it records: code contradicting it is `code-drift`. Changing the decision is the user's call, after which the ADR is edited, replaced, or deleted per `project-docs`; never edit an ADR just to match the code.

				Fix docs to match code by default. Change code only for a confirmed **code-drift** where the doc is the intended source of truth. A third case hides inside "incorrect": the doc describes a capability that _should_ exist but doesn't (an endpoint, a flag). Removing the claim and _implementing_ the feature are both valid — surface the fork to the user, and if the claim is removed, flag the missing feature as separate work rather than silently dropping it. ADRs are decision records, not behaviour docs. A `proposed` ADR is an open question: correct its statement of current behaviour if the code contradicts it, never delete it as stale. An `accepted` or status-less ADR is the source of truth for the decision it records: code contradicting it is `code-drift`. Changing the decision is the user's call; never edit an ADR just to match the code. After the user decides, edit, replace, or delete the ADR by `project-docs` rules. Call the Skill tool with `project-docs`.

high — verify-doc-drift lists project-docs' ADR maintenance actions (edit, replace, delete) instead of pointing to its rules

What I examined: the changed paragraph "Fix direction and missing features" in skills/verify-doc-drift/SKILL.md, and the ADR maintenance rules in skills/project-docs/SKILL.md. This change also adds axskills.requires: "project-docs" and says "Call the Skill tool with project-docs", so the agent loads that source.

What the subject says: the rewritten sentence is "After the user decides, edit, replace, or delete the ADR by project-docs rules." That is a closed list of the actions allowed on an ADR. project-docs defines that set in its "Keep only current decisions" bullet: "When a decision changes, edit its ADR to state the new decision. When a new decision replaces it outright, delete the old ADR and add a new one. Delete an ADR whose decision no longer applies." The "Accept when settled" bullet adds that an implementing change "edits or deletes older ADRs whose decisions it changes". It also forbids other outcomes: "Never keep an outdated ADR marked superseded or deprecated, or annotated with a note pointing to another ADR".

What goes wrong: the copy agrees with project-docs today. But the action set belongs to project-docs, and this sentence repeats it while also naming project-docs as the authority. If project-docs adds, removes, or narrows an action, this sentence goes stale without warning. For example, it might permit a status change, or require that replacement always be delete-plus-add. The agent then sees two conflicting lists. This is the drift that verify-doc-drift's own "one fact, one home" guidance warns about.

Why no exception applies: verify-doc-drift's reader is an agent that can open the source; the same paragraph tells it to load project-docs. The list is framed as the complete set of outcomes, not as examples. It is not a dated record, a generated file, or an external standard.

Correction: "Changing the decision is the user's call; never edit an ADR just to match the code. After the user decides, update the ADR as project-docs requires; call the Skill tool with project-docs." Do not list the individual actions. Detail about each action already lives in project-docs' "Keep only current decisions" bullet.

What would refute this: showing that project-docs does not define the ADR actions, or that verify-doc-drift is meant to permit a different set from project-docs. Neither holds in this tree.

lens restated-sets · arm default · tally 1 valid / 0 invalid / 0 uncertain
claim 01M42JYWA2AM607HKDGNQSX1TQ of review 01M42JVKKXF4MZ4M6R7PDATFHD

**high** — verify-doc-drift lists project-docs' ADR maintenance actions (edit, replace, delete) instead of pointing to its rules > What I examined: the changed paragraph "Fix direction and missing features" in skills/verify-doc-drift/SKILL.md, and the ADR maintenance rules in skills/project-docs/SKILL.md. This change also adds `axskills.requires: "project-docs"` and says "Call the Skill tool with `project-docs`", so the agent loads that source. > > What the subject says: the rewritten sentence is "After the user decides, edit, replace, or delete the ADR by `project-docs` rules." That is a closed list of the actions allowed on an ADR. project-docs defines that set in its "Keep only current decisions" bullet: "When a decision changes, edit its ADR to state the new decision. When a new decision replaces it outright, delete the old ADR and add a new one. Delete an ADR whose decision no longer applies." The "Accept when settled" bullet adds that an implementing change "edits or deletes older ADRs whose decisions it changes". It also forbids other outcomes: "Never keep an outdated ADR marked superseded or deprecated, or annotated with a note pointing to another ADR". > > What goes wrong: the copy agrees with project-docs today. But the action set belongs to project-docs, and this sentence repeats it while also naming project-docs as the authority. If project-docs adds, removes, or narrows an action, this sentence goes stale without warning. For example, it might permit a status change, or require that replacement always be delete-plus-add. The agent then sees two conflicting lists. This is the drift that verify-doc-drift's own "one fact, one home" guidance warns about. > > Why no exception applies: verify-doc-drift's reader is an agent that can open the source; the same paragraph tells it to load project-docs. The list is framed as the complete set of outcomes, not as examples. It is not a dated record, a generated file, or an external standard. > > Correction: "Changing the decision is the user's call; never edit an ADR just to match the code. After the user decides, update the ADR as `project-docs` requires; call the Skill tool with `project-docs`." Do not list the individual actions. Detail about each action already lives in project-docs' "Keep only current decisions" bullet. > > What would refute this: showing that project-docs does not define the ADR actions, or that verify-doc-drift is meant to permit a different set from project-docs. Neither holds in this tree. lens `restated-sets` · arm `default` · tally 1 valid / 0 invalid / 0 uncertain claim `01M42JYWA2AM607HKDGNQSX1TQ` of review `01M42JVKKXF4MZ4M6R7PDATFHD`

👍 1

low — verify-doc-drift tells the agent to apply project-docs ADR rules before the sentence that loads project-docs, breaking the repo's invocation contract

What I examined: the changed paragraph under "## Fix direction and missing features" in skills/verify-doc-drift/SKILL.md, the dependency/invocation contract in skills/writing-for-agents/references/skill-packaging.md ("Declare Dependencies"), and every other Call the Skill tool with site in skills/ (handoff, grill-with-docs, reengineer-program, write-agent-instructions, verify-readme, add-dark-mode, etc.).

The contract: skill-packaging.md says "At the point where one skill calls another, use this exact standalone sentence ... Call the Skill tool with skill-name. Follow it with the instructions for using the loaded skill." Every other caller in the tree follows this: the call sentence sits on its own line at the trigger point, and the usage instructions come after it (e.g. handoff: "Before writing the doc:\n\nCall the Skill tool with project-docs.\n\nCheck whether the session produced decisions..."; reengineer-program: "Call the Skill tool with project-docs.\n\nFollow its loading procedure; ...").

What the change does: it appends the call as the last clause of a long Reference paragraph, after the instruction it is meant to support ("After the user decides, edit, replace, or delete the ADR by project-docs rules. Call the Skill tool with project-docs."). The order is reversed. The agent is told to edit, replace, or delete the ADR "by project-docs rules" before it is told to load those rules. Those rules are not obvious. project-docs says to delete a replaced ADR instead of marking it superseded, never to renumber, to update every link to a deleted ADR, and to verify every edited ADR. An agent that acts on the first sentence can edit the ADR from guesswork and only then load the skill, or not load it at all. The trigger is also buried mid-paragraph in the Reference section, not at its own line, so the conditional "after the user decides" timing is easy to miss. Nothing in Task step 5 ("Apply the confirmed fixes") points back to it.

This is static reasoning about instruction order against the repo's own documented contract. I did not run an agent on the skill. A safe fix is to put the call first, at the decision point, on its own line: "After the user decides to change an ADR's decision:\n\nCall the Skill tool with project-docs.\n\nEdit, replace, or delete the ADR by its maintenance rules." The axskills.requires: "project-docs" frontmatter added in the same change is correct and matches the other callers.

lens general-bug · arm default · tally 1 valid / 0 invalid / 0 uncertain
claim 01M42JYNR7E30S5N630GX5P284 of review 01M42JVKKXF4MZ4M6R7PDATFHD

**low** — verify-doc-drift tells the agent to apply `project-docs` ADR rules before the sentence that loads `project-docs`, breaking the repo's invocation contract > What I examined: the changed paragraph under "## Fix direction and missing features" in skills/verify-doc-drift/SKILL.md, the dependency/invocation contract in skills/writing-for-agents/references/skill-packaging.md ("Declare Dependencies"), and every other `Call the Skill tool with` site in skills/ (handoff, grill-with-docs, reengineer-program, write-agent-instructions, verify-readme, add-dark-mode, etc.). > > The contract: skill-packaging.md says "At the point where one skill calls another, use this exact standalone sentence ... Call the Skill tool with `skill-name`. Follow it with the instructions for using the loaded skill." Every other caller in the tree follows this: the call sentence sits on its own line at the trigger point, and the usage instructions come after it (e.g. handoff: "Before writing the doc:\n\nCall the Skill tool with `project-docs`.\n\nCheck whether the session produced decisions..."; reengineer-program: "Call the Skill tool with `project-docs`.\n\nFollow its loading procedure; ..."). > > What the change does: it appends the call as the last clause of a long Reference paragraph, after the instruction it is meant to support ("After the user decides, edit, replace, or delete the ADR by `project-docs` rules. Call the Skill tool with `project-docs`."). The order is reversed. The agent is told to edit, replace, or delete the ADR "by `project-docs` rules" before it is told to load those rules. Those rules are not obvious. project-docs says to delete a replaced ADR instead of marking it superseded, never to renumber, to update every link to a deleted ADR, and to verify every edited ADR. An agent that acts on the first sentence can edit the ADR from guesswork and only then load the skill, or not load it at all. The trigger is also buried mid-paragraph in the Reference section, not at its own line, so the conditional "after the user decides" timing is easy to miss. Nothing in Task step 5 ("Apply the confirmed fixes") points back to it. > > This is static reasoning about instruction order against the repo's own documented contract. I did not run an agent on the skill. A safe fix is to put the call first, at the decision point, on its own line: "After the user decides to change an ADR's decision:\n\nCall the Skill tool with `project-docs`.\n\nEdit, replace, or delete the ADR by its maintenance rules." The `axskills.requires: "project-docs"` frontmatter added in the same change is correct and matches the other callers. lens `general-bug` · arm `default` · tally 1 valid / 0 invalid / 0 uncertain claim `01M42JYNR7E30S5N630GX5P284` of review `01M42JVKKXF4MZ4M6R7PDATFHD`

👍 1

Fixed in 24f33de8f4: ADR maintenance is a pointer to the loaded canonical skill, without copying its action list.

Fixed in 24f33de8f42786b0ac63a4a210629389deac3925: ADR maintenance is a pointer to the loaded canonical skill, without copying its action list.

Fixed in 24f33de8f4: after the user decides, standalone Call loads project-docs before its rules are applied. ADR authority and code-matching prohibition remain.

Fixed in 24f33de8f42786b0ac63a4a210629389deac3925: after the user decides, standalone Call loads project-docs before its rules are applied. ADR authority and code-matching prohibition remain.

jercik marked this conversation as resolved

jercik added 1 commit

2026-10-04 04:36:09 +00:00

fix: load ADR rules before applying the decision

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

Details

Review / Review (pull_request_target) Successful in 3m21s

Details

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

Details

24f33de8f4

forgejo-actions reviewed

2026-10-04 04:39:29 +00:00

skills/verify-doc-drift/SKILL.md

					
				@ -2,2 +2,4 @@

				name: verify-doc-drift

				metadata:

				  axskills.requires: "project-docs"

				description: Audit a repository's documentation against its actual source code and fix the factual drift — wrong ports/flags/scope names/env vars, stale or non-compiling examples, phantom routes, superseded claims, plus duplicate and obsolete docs. Each finding is categorized (incorrect / code-drift / obvious / duplicate) and adversarially verified against the code before it is reported, then docs are fixed to match the code (the reverse only when the doc is the intended source of truth). Use when the user wants to verify documentation matches the code, audit docs for accuracy, hunt doc-vs-code drift, or check that READMEs / CONTEXT.md / ADRs / standards are still true. Triggers on "verify docs", "audit documentation", "doc drift", "do the docs match the code", "check the docs against the code", "are the docs still accurate".

high — The description frontmatter copies the four finding-category names that the body's "Finding categories" section defines

I read the whole of skills/verify-doc-drift/SKILL.md, which this diff modifies by adding metadata to the frontmatter and rewording the ADR paragraph. The body's ## Finding categories section defines the set: "Classify every discrepancy as exactly one of:" followed by bullets for incorrect, code-drift, obvious, and duplicate, each with its definition. The frontmatter description repeats every member: "Each finding is categorized (incorrect / code-drift / obvious / duplicate)".

Under the restated-sets guideline, that list in the description is a second copy of a set whose source is the body section. If someone adds, renames, or merges a category in the body, nothing forces the description to change with it. The description also goes into the skill catalog in every session, where a stale copy misleads routing and costs context, and the router never needs the category names to choose this skill. No exception applies: the description is not what the agent classifies against, and the router does not use the members.

Correction: delete the parenthetical, and with it the clause "Each finding is categorized (...) and adversarially verified against the code before it is reported". The body is still the only home for the categories, and their definitions are unchanged. My separate claim on this description (vdd-desc-method-summary) proposes a full Use when … rewrite that also leaves out this list. Decisive evidence: the description line and the ## Finding categories bullets in the same file name the same four members.

lens writing-quality · arm default · tally 1 valid / 0 invalid / 0 uncertain
claim 01M42K899AV6GN66ZAEXRFRHD9 of review 01M42K5F9RH3FBNF9PQDXA0NT3

**high** — The `description` frontmatter copies the four finding-category names that the body's "Finding categories" section defines > I read the whole of skills/verify-doc-drift/SKILL.md, which this diff modifies by adding `metadata` to the frontmatter and rewording the ADR paragraph. The body's `## Finding categories` section defines the set: "Classify every discrepancy as exactly one of:" followed by bullets for **incorrect**, **code-drift**, **obvious**, and **duplicate**, each with its definition. The frontmatter `description` repeats every member: "Each finding is categorized (incorrect / code-drift / obvious / duplicate)". > > Under the restated-sets guideline, that list in the description is a second copy of a set whose source is the body section. If someone adds, renames, or merges a category in the body, nothing forces the description to change with it. The description also goes into the skill catalog in every session, where a stale copy misleads routing and costs context, and the router never needs the category names to choose this skill. No exception applies: the description is not what the agent classifies against, and the router does not use the members. > > Correction: delete the parenthetical, and with it the clause "Each finding is categorized (...) and adversarially verified against the code before it is reported". The body is still the only home for the categories, and their definitions are unchanged. My separate claim on this description (vdd-desc-method-summary) proposes a full `Use when …` rewrite that also leaves out this list. Decisive evidence: the description line and the `## Finding categories` bullets in the same file name the same four members. lens `writing-quality` · arm `default` · tally 1 valid / 0 invalid / 0 uncertain claim `01M42K899AV6GN66ZAEXRFRHD9` of review `01M42K5F9RH3FBNF9PQDXA0NT3`

🚀 1

jercik marked this conversation as resolved

jercik commented

2026-10-04 04:40:03 +00:00

Replying to review comment #112353

Claim 01M42K899AV6GN66ZAEXRFRHD9: the pre-existing frontmatter category copy is verified and remains scope-deferred, as on #110 and #113. This bounded PR delivers and loads the existing ADR contract; it does not redesign the skill's routing description. No fix or empirical disproof is claimed.

Replying to review comment #112293

Current review 01M42K5F9RH3FBNF9PQDXA0NT3, head 24f33de8f42786b0ac63a4a210629389deac3925: report-only low 01M42K8ZHPCJKQ460VGVKZBK58 repeats the pre-existing default-direction wording cleanup recorded on #113. It remains scope-deferred; binding ADR authority, code-drift requirements, and the user-decision boundary are preserved.

Report-only unadjudicated medium 01M42K8PAR15TF25RV47ZKZ7QY asks to replace the pre-existing method-summary description with a routing description. Source inspection confirms that existing packaging cleanup; it remains outside this bounded ADR-loading correction and explicitly scope-deferred. There is no matching inline anchor for either report-only claim, so no per-claim native transition is asserted.

The service's medium claim remains unadjudicated. Source evidence and scope dispositions do not clear that native review gate. No vote, rerun, dispatch, summary acknowledgment, or READY claim is made. The previous scoped findings #112294 and #112295 are fixed in this published head with their outcomes posted; current metadata/source coverage is not delivered-agent efficacy.

> Replying to review comment #112353 Claim `01M42K899AV6GN66ZAEXRFRHD9`: the pre-existing frontmatter category copy is verified and remains scope-deferred, as on #110 and #113. This bounded PR delivers and loads the existing ADR contract; it does not redesign the skill's routing description. No fix or empirical disproof is claimed. > Replying to review comment #112293 Current review `01M42K5F9RH3FBNF9PQDXA0NT3`, head `24f33de8f42786b0ac63a4a210629389deac3925`: report-only low `01M42K8ZHPCJKQ460VGVKZBK58` repeats the pre-existing default-direction wording cleanup recorded on #113. It remains scope-deferred; binding ADR authority, code-drift requirements, and the user-decision boundary are preserved. Report-only unadjudicated medium `01M42K8PAR15TF25RV47ZKZ7QY` asks to replace the pre-existing method-summary description with a routing description. Source inspection confirms that existing packaging cleanup; it remains outside this bounded ADR-loading correction and explicitly scope-deferred. There is no matching inline anchor for either report-only claim, so no per-claim native transition is asserted. The service's medium claim remains unadjudicated. Source evidence and scope dispositions do not clear that native review gate. No vote, rerun, dispatch, summary acknowledgment, or READY claim is made. The previous scoped findings #112294 and #112295 are fixed in this published head with their outcomes posted; current metadata/source coverage is not delivered-agent efficacy.

jercik commented

2026-10-06 07:45:46 +00:00

Closing as superseded. Main now carries the same change through #108: verify-doc-drift declares axskills.requires: "project-docs" and loads it before applying the ADR rules, using the canonical binding-ADR wording. The branch conflicts with main and adds nothing beyond that. The scope-deferred report-only findings above (frontmatter category copy, default-direction wording) were pre-existing and are not addressed here.

Closing as superseded. Main now carries the same change through #108: `verify-doc-drift` declares `axskills.requires: "project-docs"` and loads it before applying the ADR rules, using the canonical binding-ADR wording. The branch conflicts with main and adds nothing beyond that. The scope-deferred report-only findings above (frontmatter category copy, default-direction wording) were pre-existing and are not addressed here.

jercik closed this pull request

2026-10-06 07:45:46 +00:00

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

Details

Review / Review (pull_request_target) Successful in 3m21s

Details

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

Details

Pull request closed

Please reopen this pull request to perform a merge.

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!114

Rows
Columns

fix(skills): load the binding ADR decision contract #114

Review — j4k-oss/agent-skills @ 566f80735b

Findings (2)

high — The description frontmatter copies the four finding-category names that the body's "Finding categories" section defines

low — The intro restates the fix-direction rule that "Fix direction and missing features" owns

Other claims

Coverage

Pull request closed

Review — j4k-oss/agent-skills @ `566f80735b`

high — The `description` frontmatter copies the four finding-category names that the body's "Finding categories" section defines