workflow: read a repo's canonical contributor doc before starting work

[d-morrison]

Incident

UCD-SERG/serocalculator#661 (2026-08-10): serocalculator/CLAUDE.md opens by naming .github/copilot-instructions.md "the source of truth for repository-specific style and workflow" and calling itself "a short orientation." A session read only the short file before starting work on that PR. A docs-only change shipped with no DESCRIPTION dev-version bump, and version-check.yaml caught it --- copilot-instructions.md line 645 states the requirement outright: "ALWAYS increment dev version number to be one ahead of main branch before requesting PR review." A second commit fixed the CI failure that a first read would have avoided.

Why the rule was invisible

The rule already existed, word for word, at memories/preferences.md's "Before opening a PR, read the repo's own agent/contributor instructions" bullet. It went unconsulted because memories/ files are not auto-loaded into a session's context the way CLAUDE.md and its @shared/... fragments are --- a session has to take the extra step of grepping/reading a memory file on demand, and nothing prompted that here.

What this PR does

• Adds shared/workflow/read-canonical-doc-before-starting.md: read a repo's fuller canonical doc before starting work, not just before pushing --- distinct from ardi.md's pre-push self-review, which assumes the conventions are already known. Includes the incident above as its case record.
• Wires it into CLAUDE.md with a new section between "Claim a GitHub PR/issue before working on it" and "Open a PR immediately after claiming an issue," per check-purpose-before-reusing.md's guidance to place new fragments deliberately rather than force them into an oversized file (ardi.md is already 1521 lines, well over the 1200-line advisory threshold, so the new content is not added there).
• Points memories/preferences.md's existing (more detailed, R-package-specific) bullet at the new fragment, and fixes a stale citation on the same line: it named tools.md for the "R-package PR CI gates" section, which actually lives in memories/r-quarto.md.
• Bumps test_check_context_closure.py's pinned anchored-import count from 79 to 80, per that test's own documented remedy for an @-import addition to CLAUDE.md.

Verification

• check-context-closure.py: exits 0; the new @shared/workflow/read-canonical-doc-before-starting.md import resolves.
• check-links.py: 1352 relative links across 474 files, none broken.
• check-memory-file-size.py: no memory file exceeds 1200 lines (preferences.md is 1017).
• markdownlint-cli2: 0 issues in 500 files.
• Punctuation scan (added lines, three-dot range): 0 banned glyphs in 102 added lines.
• check-new-line-breaks (real script from a d-morrison/gha checkout): no lines missing semantic breaks.
• Full offline scripts/test_*.py suite: all green except two suites (test_ai_session, test_compare_shell_forms) that are pre-existing failures on origin/main itself, unrelated to this diff, and already tracked in Two script test suites fail on a clean main: test_ai_session (4 cases) and test_compare_shell_forms (1 case) #1382.

Placement decision

Considered adding the rule directly into ardi.md's existing "Self-review against the project's own stated conventions before every push" section, since that's the nearest existing fragment on this topic. Rejected: that section is about self-reviewing a diff against already-known conventions before a push; this rule is about the moment before anything is known, at the start of work, and ardi.md is already oversized. A new, small, focused fragment (shared/workflow/check-open-prs-before-duplicating.md-sized) was the better fit.

Closes nothing --- no existing tracking issue covers this; this PR is the tracking record and the fix in one, consistent with CLAUDE.md's "Encoding reusable feedback into ai-config" section.

---

Generated by Claude Code

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[github-actions]

Claude finished review — View run

---

Code Review: PR #1389 — "workflow: read a repo's canonical contributor doc before starting work"

Scope note: This PR modifies the ai-config corpus itself (a Markdown/Python knowledge-base repo for Claude Code conventions), not an R package or Quarto site. The SERG lab manual's R/Quarto-specific sections (coding style for R objects, function length limits, {here} usage, tidyverse idioms) don't apply to this diff — there's no R or Quarto code here. I evaluated this diff against the repo's own stated conventions (CLAUDE.md and its shared/ fragments) instead, which is the applicable standard for this repository.

What changed

• Adds shared/workflow/read-canonical-doc-before-starting.md: a new rule that a repo's fuller canonical contributor doc (e.g. .github/copilot-instructions.md) should be read at the start of work, not just before pushing.
• Wires it into CLAUDE.md via @-import, placed between "Claim a GitHub PR/issue" and "Open a PR immediately after claiming an issue."
• Repoints an existing memories/preferences.md bullet's stale citation from tools.md to r-quarto.md, and cross-links it to the new fragment.
• Bumps scripts/test_check_context_closure.py's pinned anchored-import-count regression test from 79 to 80.

Verification performed

• Confirmed memories/tools.md does not contain "R-package PR CI gates" and memories/r-quarto.md does (line 269) — the citation fix is correct, and memories/MEMORY.md's own table already pointed to r-quarto.md for this topic, so this closes a pre-existing inconsistency.
• Ran the full local test suite (scripts/test_*.py, 12 files): all pass except test_ai_session.py and test_compare_shell_forms.py, which fail identically and are confirmed pre-existing/tracked in ai-config#1382 (verified the issue exists and matches the exact failure signatures reproduced on this branch).
• check-context-closure.py, check-links.py (1352 links, 0 broken), and check-memory-file-size.py all ran clean, matching the PR body's claims.
• Verified every citation in the new fragment against live sources: ardi.md's "Self-review against the project's own stated conventions" section title (exists), keep-checkouts-fresh.md's "a bare citation is invisible..." quote (exact match), and — most importantly — the external incident citation UCD-SERG/serocalculator#661: confirmed via gh that this PR is real, merged, and its second commit is literally titled "Bump dev version to pass version-check," and confirmed serocalculator/.github/copilot-instructions.md line 645 reads verbatim "ALWAYS increment dev version number to be one ahead of main branch before requesting PR review," and serocalculator/CLAUDE.md calls copilot-instructions.md "the source of truth... a short orientation" word-for-word. No hallucinations.
• Checked semantic-line-break and ASCII-punctuation compliance on all added lines (no banned glyphs, no multi-sentence lines) and confirmed markdown links resolve correctly.
• All CI checks (validate, new-line-breaks / check-new-line-breaks) report SUCCESS.

Findings

No blocking issues.

One optional, non-blocking observation (not tied to a specific enforceable rule, so not posted as a blocking finding): in scripts/test_check_context_closure.py's history-annotation comment, prior entries cite this repo's own PR/issue number for each import-count bump (ai-config#1065, ai-config#1205, ai-config#1325, ai-config#1334), while this entry cites the external UCD-SERG/serocalculator#661 instead. The citation itself is accurate (verified above) and the PR body explains why no ai-config tracking issue exists, but a future reader searching this repo's own tracker for "what changed this pin" won't find this PR (#1389) referenced the way earlier entries reference their own PR/issue. This is a minor documentation-consistency nit, not a defect — no action required.

ℹ️ Inline comments were unavailable in this environment; findings appear above with path references.

Verdict

Verdict

Ready for merge

[github-actions]

💰 Cost: $11.2961 (review) — run