docs: reference canonical project docs guidance in grilling #106

jercik · 2026-10-03T20:32:08Z

jercik commented

2026-10-03 20:32:08 +00:00

Follows up #98 by referring grilling's loading and ADR admission procedures to its declared and invoked project-docs dependency.

Composed with merged main, preserving the binding-ADR conflict guard and the authorized inline glossary guidance. Fresh independent verification is required before merge.

Follows up [#98](https://code.j4k.dev/j4k-oss/agent-skills/pulls/98) by referring grilling's loading and ADR admission procedures to its declared and invoked `project-docs` dependency. Composed with merged `main`, preserving the binding-ADR conflict guard and the authorized inline glossary guidance. Fresh independent verification is required before merge.

jercik added 1 commit

2026-10-03 20:32:08 +00:00

fix(skills): reference canonical ADR guidance when grilling

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

Details

Node tests / node:test (pull_request) Successful in 3m12s

Details

Review / Review (pull_request_target) Successful in 5m5s

Details

efa99f89a5

forgejo-actions commented

2026-10-03 20:37:13 +00:00

Review 01M41X37YVXD4H0XHVKSMYJ9A2 — head 57a2ae9827cd413f9b26ca922f77c8138dd7d275

Review — j4k-oss/agent-skills @ `5d1127e364`

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 (1)

medium — Record qualifying settled decisions instead of offering an ADR

claim: 01M41X8DMTNS69R8D9HRDN4WXE
anchor: skills/grill-with-docs/SKILL.md (snippet)

**Offer ADRs sparingly.** Offer to create an ADR only when the decision passes the admission test in `project-docs`; otherwise skip it.

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

I read the full grill-with-docs, project-docs, and grilling skills. Grill-with-docs promises to update the glossary and ADRs as decisions settle, and it explicitly says to update CONTEXT.md right then. The Maintenance rules in project-docs likewise say to write down a term or decision when the user settles it mid-session, while its ADR admission test limits which decisions deserve an ADR. This passage instead tells the agent to offer an ADR after the test passes. For a user who has just settled a hard-to-reverse, surprising trade-off during the interview, following that wording adds a second approval step and can leave the accepted decision unrecorded if the conversation moves on. Change it to: When the user settles a decision that passes the admission test in project-docs, record its ADR inline; otherwise skip the ADR. This preserves the admission threshold and makes the documentation timing agree with the called skill. The conflict is established by the two skills as written; I did not run an agent interview to measure how often it occurs.

Other claims

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

Coverage

Coverage pass: 01M41X382R2T4550KKQFZYJYBF
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** `01M41X37YVXD4H0XHVKSMYJ9A2` — head `57a2ae9827cd413f9b26ca922f77c8138dd7d275` # Review — j4k-oss/agent-skills @ 5d1127e3642d 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 (1) ### medium — Record qualifying settled decisions instead of offering an ADR - claim: `01M41X8DMTNS69R8D9HRDN4WXE` - anchor: `skills/grill-with-docs/SKILL.md` (snippet) ``` **Offer ADRs sparingly.** Offer to create an ADR only when the decision passes the admission test in `project-docs`; otherwise skip it. ``` - lens: writing-quality · arm: default - verdicts: 1 valid / 0 invalid / 0 uncertain - disposition: none > I read the full grill-with-docs, project-docs, and grilling skills. Grill-with-docs promises to update the glossary and ADRs as decisions settle, and it explicitly says to update CONTEXT.md right then. The Maintenance rules in project-docs likewise say to write down a term or decision when the user settles it mid-session, while its ADR admission test limits which decisions deserve an ADR. This passage instead tells the agent to offer an ADR after the test passes. For a user who has just settled a hard-to-reverse, surprising trade-off during the interview, following that wording adds a second approval step and can leave the accepted decision unrecorded if the conversation moves on. Change it to: When the user settles a decision that passes the admission test in project-docs, record its ADR inline; otherwise skip the ADR. This preserves the admission threshold and makes the documentation timing agree with the called skill. The conflict is established by the two skills as written; I did not run an agent interview to measure how often it occurs. ## Other claims - grounding-pending (0) - ungrounded (0) - rejected (0) - duplicate-of (0) - unadjudicated (0) ## Coverage Coverage pass: 01M41X382R2T4550KKQFZYJYBF 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 |

forgejo-actions reviewed

2026-10-03 20:37:13 +00:00

skills/grill-with-docs/SKILL.md

					
				@ -32,4 +32,4 @@ Follow its loading procedure: a root `CONTEXT-MAP.md` means the repo has multipl

				**Update `CONTEXT.md` inline.** When a term is resolved, update `CONTEXT.md` right then, not in a batch at the session's end. `CONTEXT.md` is a glossary and nothing else — never a spec, a scratch pad, or a home for implementation decisions.

low — CONTEXT.md maintenance rule is repeated after loading project-docs

I read the full grill-with-docs skill and the project-docs skill it explicitly loads at session start. This paragraph says to update a resolved term immediately and keep CONTEXT.md solely as a glossary. The loaded project-docs skill already says "Update inline, don't batch" for settled terms and "A glossary and nothing else" with the same exclusions. The repetition adds a second place to maintain the same rule and costs each invocation this paragraph without changing the agent's task. Delete this paragraph; the canonical project-docs guidance preserves both the timing and the glossary boundary. The no-op test in the installed writing-for-agents skill applies here. A separate behavior required only in this interview would refute the deletion, but the paragraph gives none.

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

**low** — CONTEXT.md maintenance rule is repeated after loading project-docs > I read the full grill-with-docs skill and the project-docs skill it explicitly loads at session start. This paragraph says to update a resolved term immediately and keep CONTEXT.md solely as a glossary. The loaded project-docs skill already says "Update inline, don't batch" for settled terms and "A glossary and nothing else" with the same exclusions. The repetition adds a second place to maintain the same rule and costs each invocation this paragraph without changing the agent's task. Delete this paragraph; the canonical project-docs guidance preserves both the timing and the glossary boundary. The no-op test in the installed writing-for-agents skill applies here. A separate behavior required only in this interview would refute the deletion, but the paragraph gives none. lens `writing-quality` · arm `default` · tally 1 valid / 0 invalid / 0 uncertain claim `01M41QP6VV1PT8BA0V4B7RSBAA` of review `01M41QF64VHYYCX5YT1C6CSRPM`

👎 1

The duplication is present, but deleting this paragraph exceeds the user-authorized loading/admission delta. The user explicitly requires preserving inline timing and the glossary partial exception. Retaining it is a directed scope exception, not a claim that the canonical dependency lacks those rules. No deletion is claimed; this contested thread is left open for the reviewer.

The duplication is present, but deleting this paragraph exceeds the user-authorized loading/admission delta. The user explicitly requires preserving inline timing and the glossary partial exception. Retaining it is a directed scope exception, not a claim that the canonical dependency lacks those rules. No deletion is claimed; this contested thread is left open for the reviewer.

superseded by review 01M41X37YVXD4H0XHVKSMYJ9A2 for head 57a2ae9827cd413f9b26ca922f77c8138dd7d275

superseded by review `01M41X37YVXD4H0XHVKSMYJ9A2` for head `57a2ae9827cd413f9b26ca922f77c8138dd7d275`

🚀 1

jercik referenced this pull request

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

fix(skills): record settled ADR decisions #98

jercik added 1 commit

2026-10-03 22:10:28 +00:00

chore: integrate merged ADR authority

commit-msg / commitlint (pull_request) Successful in 4m58s

Details

Review / Review (pull_request_target) Successful in 4m35s

Details

Node tests / node:test (pull_request) Failing after 10m1s

Details

57a2ae9827

jercik commented

2026-10-03 22:14:46 +00:00

Replying to review comment #110727

Claim 01M41QN90FWE326YMAY0CP508J (old recorded-ADR conflict guard) is addressed on pushed head 57a2ae9827cd413f9b26ca922f77c8138dd7d275 by composing merged #98 (b93e79a33d35263259bd19cf11a5f031b9171f26). The consumer now challenges only binding ADRs and follows the canonical conflict-resolution rule; that owner includes statusless authority and requires the user's decision before changing a binding record.

Claim 01M41QP6VV1PT8BA0V4B7RSBAA is a directed scope exception: inline timing and the glossary boundary remain by explicit user instruction. The deletion is contested in comment 110728 and its anchor remains open. Neither a source deletion nor a resolution of that disagreement is claimed.

> Replying to review comment #110727 Claim `01M41QN90FWE326YMAY0CP508J` (old recorded-ADR conflict guard) is addressed on pushed head `57a2ae9827cd413f9b26ca922f77c8138dd7d275` by composing merged #98 (`b93e79a33d35263259bd19cf11a5f031b9171f26`). The consumer now challenges only binding ADRs and follows the canonical conflict-resolution rule; that owner includes statusless authority and requires the user's decision before changing a binding record. Claim `01M41QP6VV1PT8BA0V4B7RSBAA` is a directed scope exception: inline timing and the glossary boundary remain by explicit user instruction. The deletion is contested in comment 110728 and its anchor remains open. Neither a source deletion nor a resolution of that disagreement is claimed.

forgejo-actions reviewed

2026-10-03 22:15:31 +00:00

skills/grill-with-docs/SKILL.md

					
				@ -33,3 +33,3 @@

				**Update `CONTEXT.md` inline.** When a term is resolved, update `CONTEXT.md` right then, not in a batch at the session's end. `CONTEXT.md` is a glossary and nothing else — never a spec, a scratch pad, or a home for implementation decisions.

				**Offer ADRs sparingly.** Offer to create an ADR only when the decision passes the three-part test in the `project-docs` skill — hard to reverse, surprising without context, and the result of a real trade-off. That skill's version of the test is canonical. If any part is missing, skip the ADR.

				**Offer ADRs sparingly.** Offer to create an ADR only when the decision passes the admission test in `project-docs`; otherwise skip it.

medium — Record qualifying settled decisions instead of offering an ADR

I read the full grill-with-docs, project-docs, and grilling skills. Grill-with-docs promises to update the glossary and ADRs as decisions settle, and it explicitly says to update CONTEXT.md right then. The Maintenance rules in project-docs likewise say to write down a term or decision when the user settles it mid-session, while its ADR admission test limits which decisions deserve an ADR. This passage instead tells the agent to offer an ADR after the test passes. For a user who has just settled a hard-to-reverse, surprising trade-off during the interview, following that wording adds a second approval step and can leave the accepted decision unrecorded if the conversation moves on. Change it to: When the user settles a decision that passes the admission test in project-docs, record its ADR inline; otherwise skip the ADR. This preserves the admission threshold and makes the documentation timing agree with the called skill. The conflict is established by the two skills as written; I did not run an agent interview to measure how often it occurs.

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

**medium** — Record qualifying settled decisions instead of offering an ADR > I read the full grill-with-docs, project-docs, and grilling skills. Grill-with-docs promises to update the glossary and ADRs as decisions settle, and it explicitly says to update CONTEXT.md right then. The Maintenance rules in project-docs likewise say to write down a term or decision when the user settles it mid-session, while its ADR admission test limits which decisions deserve an ADR. This passage instead tells the agent to offer an ADR after the test passes. For a user who has just settled a hard-to-reverse, surprising trade-off during the interview, following that wording adds a second approval step and can leave the accepted decision unrecorded if the conversation moves on. Change it to: When the user settles a decision that passes the admission test in project-docs, record its ADR inline; otherwise skip the ADR. This preserves the admission threshold and makes the documentation timing agree with the called skill. The conflict is established by the two skills as written; I did not run an agent interview to measure how often it occurs. lens `writing-quality` · arm `default` · tally 1 valid / 0 invalid / 0 uncertain claim `01M41X8DMTNS69R8D9HRDN4WXE` of review `01M41X37YVXD4H0XHVKSMYJ9A2`

😕 1

The source already invokes project-docs and says to use its maintenance rules before creating or updating docs. Those rules require inline recording when the user settles a qualifying decision. The retained offer wording governs admission and does not explicitly require a second approval after settlement. Is the requested change an admission/timing redesign, or can you identify a directive that overrides the loaded inline-recording rule? This PR is authorized for mechanical canonical loading/admission references and must preserve existing timing and admission semantics. No behavioral trial was run, so I am not claiming the inferred second-approval failure disproved.

The source already invokes project-docs and says to use its maintenance rules before creating or updating docs. Those rules require inline recording when the user settles a qualifying decision. The retained offer wording governs admission and does not explicitly require a second approval after settlement. Is the requested change an admission/timing redesign, or can you identify a directive that overrides the loaded inline-recording rule? This PR is authorized for mechanical canonical loading/admission references and must preserve existing timing and admission semantics. No behavioral trial was run, so I am not claiming the inferred second-approval failure disproved.

jercik merged commit f14669b7f3 into main

2026-10-06 07:50:10 +00:00

jercik deleted branch fix/reference-grill-adr-guidance

2026-10-06 07:50:11 +00:00

jercik referenced this pull request from a commit

2026-10-06 07:50:11 +00:00

docs: reference canonical project docs guidance in grilling (#106)

jercik referenced this pull request

2026-10-06 07:50:27 +00:00

fix: record settled ADR decisions inline when grilling #120

jercik commented

2026-10-06 07:50:32 +00:00

Tracked in #120, which changes the ADR line to record qualifying decisions inline (claim 01M41X8DMTNS69R8D9HRDN4WXE). #106 merged without that wording change; the failing node:test check is unrelated to this docs-only diff and also fails on current main.

Tracked in https://code.j4k.dev/j4k-oss/agent-skills/pulls/120, which changes the ADR line to record qualifying decisions inline (claim `01M41X8DMTNS69R8D9HRDN4WXE`). #106 merged without that wording change; the failing `node:test` check is unrelated to this docs-only diff and also fails on current main.

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

				@ -32,4 +32,4 @@ Follow its loading procedure: a root `CONTEXT-MAP.md` means the repo has multipl

				Update `CONTEXT.md` inline. When a term is resolved, update `CONTEXT.md` right then, not in a batch at the session's end. `CONTEXT.md` is a glossary and nothing else — never a spec, a scratch pad, or a home for implementation decisions.

Rows
Columns