fix: record settled ADR decisions inline when grilling #120

jercik · 2026-10-06T07:50:27Z

jercik commented

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

Follows up #106 and its unresolved review finding: grill-with-docs said to offer an ADR once a decision passed the admission test, while project-docs says to write settled decisions down right then.

The line now says to record the ADR inline when the user settles a qualifying decision. The admission test is unchanged. I did not run an agent interview to measure how often the old wording left a decision unrecorded, so the failure is inferred from the two skills as written.

🤖 Generated with Claude Code

Follows up #106 and its unresolved review finding: `grill-with-docs` said to offer an ADR once a decision passed the admission test, while `project-docs` says to write settled decisions down right then. The line now says to record the ADR inline when the user settles a qualifying decision. The admission test is unchanged. I did not run an agent interview to measure how often the old wording left a decision unrecorded, so the failure is inferred from the two skills as written. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

jercik added 1 commit

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

fix(skills): record settled ADR decisions inline when grilling

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

Details

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

Details

Review / Review (pull_request_target) Successful in 1m49s

Details

12f741f6b0

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

jercik referenced this pull request

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

docs: reference canonical project docs guidance in grilling #106

forgejo-actions commented

2026-10-06 07:59:04 +00:00

Review 01M4832P4QHEAMDTNCDGYN3H73 — head 12f741f6b01ed2b466700bbec03ad29a4df71d75

Review — j4k-oss/agent-skills @ `60b5e29e7d`

Scope: diff against base tree 160c43773584
Status: dispatched — coverage complete (5/5 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-v4",
  "tally": "tally-v1",
  "triage_settle": "triage-settle-v2"
}

Findings (1)

low — Inline documentation rules repeat the required project-docs skill

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

**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.

**Record ADRs sparingly.** When the user settles a decision that passes the admission test in `project-docs`, record its ADR inline; otherwise skip the ADR.

lens: writing-quality · arm: default
verdicts: 1 valid / 0 invalid / 0 uncertain
- pass 01M4D6HHGC18MKXESHZJMEA4QW · valid: The exact-grounded excerpt repeats inline recording, CONTEXT.md's glossary-only boundary, and the ADR admission requirement. The installed project-docs skill confirms those rules, and the reviewer supplies a concrete account of the earlier instruction that explicitly calls that dependency and requires following its formats and maintenance rules. This is a targeted redundancy deletion: the reported call preserves each removed obligation, and neither the excerpt nor the body identifies an interview-specific constraint lost by removing the paragraphs. The writing skill's One Idea, One Place rule specifically favors calling declared dependencies over repeating their instructions. The low-severity quality finding is supported.
disposition: none

The final paragraphs make each interview load a second copy of documentation rules and create another place to maintain them when the canonical policy changes. They add no behavior beyond the dependency this skill already requires and explicitly loads.

Earlier, the file says to call project-docs and follow its canonical formats and maintenance rules before creating or updating project docs. That dependency's maintenance rule says, ‘When the user settles a term or a decision mid-session, write it down right then.’ Its CONTEXT.md format says, ‘A glossary and nothing else,’ and excludes implementation details and scratch content. Its ‘When a decision deserves an ADR’ section supplies the admission test to which the final paragraph already points.

Delete both anchored paragraphs. The existing instruction to follow project-docs preserves prompt recording of settled terms and qualifying decisions, the glossary boundary, and the ADR admission requirement. This follows the writing standard's ‘One Idea, One Place’ guidance to call declared dependencies instead of duplicating their instructions, and its no-op test.

I read the complete changed skill, its required project-docs and grilling skills, and the diff. This is a static comparison of the loaded instructions; I did not run an interview. A distinct interview-specific exception or evidence that these repeated reminders prevent a mistake despite loading and following project-docs would warrant retaining the necessary part; neither is stated here.

Other claims

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

Coverage

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

lens	part	arm	unit status	runs	loss
general-bug	whole	default	no-claims	1	no
writing-quality	whole	default	no-claims	1	no
test-trimming	whole	default	no-claims	1	no
restated-sets	whole	default	no-claims	1	no
project-docs	whole	default	no-claims	1	no

**Review** `01M4832P4QHEAMDTNCDGYN3H73` — head `12f741f6b01ed2b466700bbec03ad29a4df71d75` # Review — j4k-oss/agent-skills @ 60b5e29e7d3e Scope: diff against base tree `160c43773584` Status: dispatched — coverage complete (5/5 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-v4", "tally": "tally-v1", "triage_settle": "triage-settle-v2" } ``` ## Findings (1) ### low — Inline documentation rules repeat the required project-docs skill - claim: `01M4838YECPT4ST015KB8R8688` - anchor: `skills/grill-with-docs/SKILL.md` (snippet) ``` **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. **Record ADRs sparingly.** When the user settles a decision that passes the admission test in `project-docs`, record its ADR inline; otherwise skip the ADR. ``` - lens: writing-quality · arm: default - verdicts: 1 valid / 0 invalid / 0 uncertain - pass `01M4D6HHGC18MKXESHZJMEA4QW` · valid: The exact-grounded excerpt repeats inline recording, CONTEXT.md's glossary-only boundary, and the ADR admission requirement. The installed project-docs skill confirms those rules, and the reviewer supplies a concrete account of the earlier instruction that explicitly calls that dependency and requires following its formats and maintenance rules. This is a targeted redundancy deletion: the reported call preserves each removed obligation, and neither the excerpt nor the body identifies an interview-specific constraint lost by removing the paragraphs. The writing skill's One Idea, One Place rule specifically favors calling declared dependencies over repeating their instructions. The low-severity quality finding is supported. - disposition: none > The final paragraphs make each interview load a second copy of documentation rules and create another place to maintain them when the canonical policy changes. They add no behavior beyond the dependency this skill already requires and explicitly loads. > > Earlier, the file says to call `project-docs` and follow its canonical formats and maintenance rules before creating or updating project docs. That dependency's maintenance rule says, ‘When the user settles a term or a decision mid-session, write it down right then.’ Its CONTEXT.md format says, ‘A glossary and nothing else,’ and excludes implementation details and scratch content. Its ‘When a decision deserves an ADR’ section supplies the admission test to which the final paragraph already points. > > Delete both anchored paragraphs. The existing instruction to follow `project-docs` preserves prompt recording of settled terms and qualifying decisions, the glossary boundary, and the ADR admission requirement. This follows the writing standard's ‘One Idea, One Place’ guidance to call declared dependencies instead of duplicating their instructions, and its no-op test. > > I read the complete changed skill, its required `project-docs` and `grilling` skills, and the diff. This is a static comparison of the loaded instructions; I did not run an interview. A distinct interview-specific exception or evidence that these repeated reminders prevent a mistake despite loading and following `project-docs` would warrant retaining the necessary part; neither is stated here. ## Other claims - grounding-pending (0) - ungrounded (0) - rejected (0) - duplicate-of (0) - unadjudicated (0) ## Coverage Coverage pass: 01M4B3M9K0N9GQY4KQ0PRGKW2D Accounting: complete Slot health: healthy | lens | part | arm | unit status | runs | loss | | --- | --- | --- | --- | --- | --- | | general-bug | whole | default | no-claims | 1 | no | | writing-quality | whole | default | no-claims | 1 | no | | test-trimming | whole | default | no-claims | 1 | no | | restated-sets | whole | default | no-claims | 1 | no | | project-docs | whole | default | no-claims | 1 | no |

🚀 1

jercik referenced this pull request

2026-10-07 11:57:37 +00:00

fix: reference project-docs inline-update rule when grilling #123

jercik commented

2026-10-07 11:57:44 +00:00

Unadjudicated claim 01M4838YECPT4ST015KB8R8688 (low, "Inline documentation rules repeat the required project-docs skill"): confirmed. skills/project-docs/SKILL.md ("Update inline, don't batch") already says to write settled terms and decisions down right then, so the two inline bullets in grill-with-docs restate it. It is not a defect this PR introduces and does not make merging harmful, so it is tracked in #123, stacked on this PR.

The 12f741f review run failed with triage-failed (agent execution failed) and wrote no findings; a fresh review is being requested for this head.

Unadjudicated claim `01M4838YECPT4ST015KB8R8688` (low, "Inline documentation rules repeat the required project-docs skill"): confirmed. `skills/project-docs/SKILL.md` ("Update inline, don't batch") already says to write settled terms and decisions down right then, so the two inline bullets in `grill-with-docs` restate it. It is not a defect this PR introduces and does not make merging harmful, so it is tracked in https://code.j4k.dev/j4k-oss/agent-skills/pulls/123, stacked on this PR. The 12f741f review run failed with `triage-failed` (agent execution failed) and wrote no findings; a fresh review is being requested for this head.

🚀 1

forgejo-actions reviewed

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

skills/grill-with-docs/SKILL.md

Lines 24-26

					
				@ -32,4 +32,4 @@ Follow its loading procedure and use its canonical formats and maintenance rules

				**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 admission test in `project-docs`; otherwise skip it.

				**Record ADRs sparingly.** When the user settles a decision that passes the admission test in `project-docs`, record its ADR inline; otherwise skip the ADR.

low — Inline documentation rules repeat the required project-docs skill

The final paragraphs make each interview load a second copy of documentation rules and create another place to maintain them when the canonical policy changes. They add no behavior beyond the dependency this skill already requires and explicitly loads.

Earlier, the file says to call project-docs and follow its canonical formats and maintenance rules before creating or updating project docs. That dependency's maintenance rule says, ‘When the user settles a term or a decision mid-session, write it down right then.’ Its CONTEXT.md format says, ‘A glossary and nothing else,’ and excludes implementation details and scratch content. Its ‘When a decision deserves an ADR’ section supplies the admission test to which the final paragraph already points.

Delete both anchored paragraphs. The existing instruction to follow project-docs preserves prompt recording of settled terms and qualifying decisions, the glossary boundary, and the ADR admission requirement. This follows the writing standard's ‘One Idea, One Place’ guidance to call declared dependencies instead of duplicating their instructions, and its no-op test.

I read the complete changed skill, its required project-docs and grilling skills, and the diff. This is a static comparison of the loaded instructions; I did not run an interview. A distinct interview-specific exception or evidence that these repeated reminders prevent a mistake despite loading and following project-docs would warrant retaining the necessary part; neither is stated here.

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

**low** — Inline documentation rules repeat the required project-docs skill > The final paragraphs make each interview load a second copy of documentation rules and create another place to maintain them when the canonical policy changes. They add no behavior beyond the dependency this skill already requires and explicitly loads. > > Earlier, the file says to call `project-docs` and follow its canonical formats and maintenance rules before creating or updating project docs. That dependency's maintenance rule says, ‘When the user settles a term or a decision mid-session, write it down right then.’ Its CONTEXT.md format says, ‘A glossary and nothing else,’ and excludes implementation details and scratch content. Its ‘When a decision deserves an ADR’ section supplies the admission test to which the final paragraph already points. > > Delete both anchored paragraphs. The existing instruction to follow `project-docs` preserves prompt recording of settled terms and qualifying decisions, the glossary boundary, and the ADR admission requirement. This follows the writing standard's ‘One Idea, One Place’ guidance to call declared dependencies instead of duplicating their instructions, and its no-op test. > > I read the complete changed skill, its required `project-docs` and `grilling` skills, and the diff. This is a static comparison of the loaded instructions; I did not run an interview. A distinct interview-specific exception or evidence that these repeated reminders prevent a mistake despite loading and following `project-docs` would warrant retaining the necessary part; neither is stated here. lens `writing-quality` · arm `default` · tally 1 valid / 0 invalid / 0 uncertain claim `01M4838YECPT4ST015KB8R8688` of review `01M4832P4QHEAMDTNCDGYN3H73`

🚀 1

jercik marked this conversation as resolved

jercik commented

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

Replying to review comment #141031

Tracked in #123, which deletes the duplicated inline-update bullets in grill-with-docs in favour of the project-docs rule. The repetition is real but this PR did not introduce it, so it does not block merging head 12f741f; #123 owns the change.

> Replying to review comment #141031 Tracked in https://code.j4k.dev/j4k-oss/agent-skills/pulls/123, which deletes the duplicated inline-update bullets in `grill-with-docs` in favour of the `project-docs` rule. The repetition is real but this PR did not introduce it, so it does not block merging head 12f741f; #123 owns the change.

jercik merged commit 6632385c08 into main

2026-10-08 10:27:39 +00:00

jercik deleted branch fix/grill-record-adr

2026-10-08 10:27:39 +00:00

jercik referenced this pull request from a commit

2026-10-08 10:27:40 +00:00

fix: record settled ADR decisions inline when grilling (#120)

Sign in to join this conversation.

No reviewers

No labels

No milestone