[OAUTH-WG] Re: draft-chen-oauth-agent-authz-use-cases-01

[Blake Morrison <[e-mail]>]

Brian, Meiling,

Thanks for the independent read. Meiling, checking the rendering before the
next version is the right place for it.

Brian's first suggestion is the one that generalises past this defect.
Recording the rendered symptom rather than the source fix is what makes an
issue uncloseable without a re-render, and it survives the particular fault
being fixed.

A source-to-render mismatch is invisible to review of the source, so nine
issues can close correctly against source and the document still ship the
fault. That is what happened between -02 and -03, and it is why the check
belongs on the rendered artefact rather than in anyone's review habits.

Brian, yes to the gate configuration. Send it on-list rather than off, since
the class it catches is not specific to anyone's draft.

Best,
Blake


On Thursday, 27 August 2026 at 7:57 PM, Meiling Chen <[e-mail]> wrote:

> Brian, Blake,
> 
> It's indeed a formatting issue. Thank you for the suggestion. We will check the rendering situation before the next version update, and the idea of a brief "verified in rendered output" note is quite good.
> 
> Best,
> Meiling
> 
> [e-mail]
> 
> > > From: Brian Vicente
> > > Date: 2026-08-27 06:48
> > > To: [e-mail]; Blake Morrison
> > > CC: [e-mail]; [e-mail]
> > > Subject: [OAUTH-WG] Re: draft-chen-oauth-agent-authz-use-cases-01
> > > Meiling, Blake,
> > > 
> > > Confirming Blake's finding against -03 from an independent read, since it is the kind of defect that survives a version bump quietly.
> > > 
> > > In Section 4.2.4, the UC8 "What's Missing" heading renders as two literal asterisks with no colon. The consequence is not cosmetic: the three gap bullets beneath it lose their label, so a reviewer landing in UC8 sees three unattributed bullets and no statement of what they are gaps against. It is the only one of the eleven use cases in the document where this happens, which is what makes it easy to miss in a diff review.
> > > 
> > > Two suggestions, both cheap:
> > > 
> > > 1. The tracker issue should record the rendered symptom, not just the source fix, so that closing it requires re-rendering rather than re-editing.
> > > 
> > > 2. Since the -03 announcement lists nine issues as resolved (#15-20, #26-28), it would help reviewers if the next revision included a short "verified in rendered output" note for heading and table changes. The class of defect here is a source-to-render mismatch, and issue closure against source alone will not catch it.
> > > 
> > > I run xml2rfc plus idnits in CI on my own drafts specifically to fail on unlabeled headings and stale front-matter dates. If it is useful to the authors I am glad to share the gate configuration off-list.