Repository navigation
docs(claude): requirement headings per ADR-038, current ADR numbers, a progress-carrier pattern - #855
Conversation
…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>
WilcoLouwerse
left a comment
There was a problem hiding this comment.
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
- Id rules diverge from ADR-038 (prefix length, numbering)
- Progress-carrier reference implementation not on hydra main
🟢 Outside the diff
openspec/changes/gate-68-duplicate-index-pages/tasks.md:207still 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>
…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
left a comment
There was a problem hiding this comment.
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…39b21f11read inline (Quick, XS); the fix39b21f11…48af776echecked 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).
What
Three fixes in
docs/claude/, the guides hydra's/review-prskill stages for spec, docs and skill PRs.### 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-annotateruns. 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@specrow is unchanged.review-prsessions: 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 Bashdescription. Reference implementation named (hydradevelopment, not yetmain).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
openspec/architecture/adr-038-canonical-req-id-format.mdon hydramain.docs/claude/*.mdfile carries the### REQ-form (grep -rn "### REQ-" docs/claude/→ only writing-specs.md, now updated).🤖 Generated with Claude Code