Skip to content

docs(claude): requirement headings per ADR-038, current ADR numbers, a progress-carrier pattern - #855

Merged
WilcoLouwerse merged 3 commits into
mainfrom
docs/claude-guides-adr-038-progress-carrier
Oct 19, 2026
Merged

WilcoLouwerse merged 3 commits into
mainfrom
docs/claude-guides-adr-038-progress-carrier

Conversation

@WilcoLouwerse

@WilcoLouwerse WilcoLouwerse commented Oct 16, 2026 •

Copy link
Copy Markdown
Contributor

What

Three fixes in docs/claude/, the guides hydra's /review-pr skill stages for spec, docs and skill PRs.

  • writing-specs.md — every requirement heading now has ADR-038's Form A, ### Requirement: <Title> (REQ-XX-NNN), with a short section on the rule. The guide still taught ### REQ-{NNN}: <Name>, ADR-038's legacy Form B, which the coverage scanner flags and asks to migrate before /opsx-annotate runs. The id rules follow ADR-038 too: optional, [A-Z]{2,5}-[0-9]+[a-z]*, numbering marked as the guide's own convention. All six examples and the cross-referencing table follow; the @spec row is unchanged.
  • writing-docs.md — the Sources-of-Truth table pointed NL Design System at "company ADR-003" (Backend; NL Design System is ADR-010) and the i18n sentence cited ADR-005 (Security; i18n is ADR-007).
  • skill-patterns.md — a new common pattern, Progress carrier: a progress line typed between tool calls is absent whenever the model thinks before the call (measured on three review-pr sessions: 0 of 56 shown with a thinking block, 43 of 122 without), so progress is emitted as a tool call's output and carried in the Bash description. Reference implementation named (hydra development, not yet main).
  • gate-68 tasks.md — the same wrong i18n number (ADR-005 → ADR-007) in an openspec change file.

Why now

The review skill compares every spec PR against writing-specs.md; with the legacy form in the guide, a reviewer could ask an author to move away from the canonical heading. The counterpart in hydra (the content-type guide and the spec schema's own description) is in the review-pr readiness PR on hydra of the same day.

Checks

  • Links verified: the ADR-038 file is openspec/architecture/adr-038-canonical-req-id-format.md on hydra main.
  • No other docs/claude/*.md file carries the ### REQ- form (grep -rn "### REQ-" docs/claude/ → only writing-specs.md, now updated).

🤖 Generated with Claude Code

…a progress-carrier pattern

writing-specs.md still taught `### REQ-{NNN}: <Name>`, the legacy form ADR-038 replaced
on 2026-05-24: the coverage scanner cannot read it and synthesises ids for it. Every
example and the cross-referencing table now use `### Requirement: <Title> (REQ-XX-NNN)`,
with a short section on the rule. hydra's review-pr skill stages this guide for every
spec PR, so the stale form was what reviewers were checking against.

writing-docs.md pointed NL Design System at "company ADR-003" (that is Backend; NL
Design System is ADR-010) and i18n at ADR-005 (Security; i18n is ADR-007).

skill-patterns.md gets the progress-carrier pattern measured in hydra's review-pr
skill: a progress line typed between tool calls is absent whenever the model thinks
before the call, so progress is emitted as a tool call's output and carried in the Bash
description.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Comment thread docs/claude/writing-specs.md Resolved
Comment thread docs/claude/writing-specs.md Resolved
Comment thread docs/claude/skill-patterns.md Resolved

@WilcoLouwerse WilcoLouwerse left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Verdict: REQUEST_CHANGES (posted as COMMENT — self-review)

Standard review of 4070bace. The ADR-number fixes in writing-docs.md are right (ADR-010 NL Design, ADR-007 i18n) and the new heading form matches ADR-038 Form A. One blocker: the reason the guide gives for leaving the legacy heading is wrong against ADR-038 itself, and the PR body repeats it. Fixes follow on this branch.

🔴 Blockers

🟡 Concerns

🟢 Outside the diff

  • openspec/changes/gate-68-duplicate-index-pages/tasks.md:207 still cites "company-wide ADR-005" for i18n (ADR-007). Not in this PR's diff; a follow-up, not a blocker.

ADRs verified: ADR-038, ADR-010, ADR-007.
Gates: local run scoped to the diff — 3 failures, all repo-level and outside this docs diff (coding-standard-adoption, composer-cooldown-config, adr-number-collision on a planted test fixture); 3 of 5 applicable gates reported.
Mode: Standard · CI: green

…nst ADR-038

writing-specs.md said the coverage scanner cannot read `### REQ-001:`
headings and synthesises ids for them; ADR-038 says the scanner reads the
id of that legacy form and warns, and /opsx-annotate refuses the app until
it is migrated. The id rules now follow ADR-038 too: optional (rule 2),
`[A-Z]{2,5}-[0-9]+[a-z]*` (rule 3, a 2-5 prefix, not 2-4), with numbering
marked as this guide's own convention; the template shows the suffix is
optional.

skill-patterns.md names where the progress-carrier reference
implementation lives: hydra `development`, not yet `main`.

The gate-68 tasks file cited ADR-005 for i18n, the same wrong number
writing-docs.md had; i18n is ADR-007.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Comment thread docs/claude/writing-specs.md Resolved
…ot refuse

The corrected legacy-heading sentence said /opsx-annotate refuses an app
whose report carries the legacy warning. ADR-038 plans that refusal; the
skill does not have it. The scanner's warning, which asks for a migration
before /opsx-annotate runs, is what exists.

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

@WilcoLouwerse WilcoLouwerse left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Verdict: APPROVE (posted as COMMENT — self-review)

Nothing left to address: all 4 threads are resolved and every finding of both rounds is fixed. What stands between this PR and a merge: a human review; the rules API shows no approval requirement on main.

Round Found Status
1 🔴 1 · 🟡 2 · 🟢 1 — wrong reason for leaving the legacy heading, id rules off ADR-038, progress-carrier reference not on hydra main, stale i18n ADR in gate-68 tasks fixed in 39b21f1
2 🔴 1 — "/opsx-annotate refuses" is ADR intent, not behaviour (fix-induced) fixed in 48af776

Round 2 findings

Finding What Fixed in
r2-f1 /opsx-annotate refusal claim 48af776
Details
  • Delta 4070bace…39b21f11 read inline (Quick, XS); the fix 39b21f11…48af776e checked by a pre-push adversarial agent: clean.
  • ADRs verified: ADR-038, ADR-007, ADR-010.
  • Gates: local run scoped to the diff — 3 failures, all repo-level and outside this docs diff (coding-standard-adoption, composer-cooldown-config, adr-number-collision on a planted test fixture).
  • Before the next round: fix rules ON (fix-induced 1 ≥ new 0).

@WilcoLouwerse
WilcoLouwerse merged commit 9797871 into main Oct 19, 2026
47 checks passed
@WilcoLouwerse
WilcoLouwerse deleted the docs/claude-guides-adr-038-progress-carrier branch October 19, 2026 12:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant