From 48d8bbdd890b55244a05a16a6b8db80169c6d40f Mon Sep 17 00:00:00 2001 From: Markus Neusinger <2921697+MarkusNeusinger@users.noreply.github.com> Date: Thu, 15 Oct 2026 09:48:24 +0200 Subject: [PATCH 1/2] docs: align Copilot instructions with CLAUDE.md (blockers rule, uv only) Owner decisions 2026-10-15: - The "fix small build/test blockers directly, even when out of scope" rule applies to every agent. copilot-instructions.md gains it under Important Rules (with the ~20-line bar and ask-first above it), and its Common Issues line no longer tells Copilot to leave pre-existing failures alone. - Python tooling is uv only: the pip fallback is gone from both Copilot lines, and CLAUDE.md states the rule explicitly. Also fixes one clear contradiction found while comparing the two guides: Task Suitability listed "adding new plot types following existing patterns" as a Copilot task, which the mandatory pipeline forbids; it now points at a spec-request issue. Both rules are pinned as mirrored in tests/unit/test_agent_instructions.py. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01GdMSqLR5ww4ji74EUSmk9M --- .github/copilot-instructions.md | 9 +++++---- CLAUDE.md | 2 +- changelog.d/align-copilot-instructions.md | 9 +++++++++ tests/unit/test_agent_instructions.py | 10 ++++++++++ 4 files changed, 25 insertions(+), 5 deletions(-) create mode 100644 changelog.d/align-copilot-instructions.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index e59dd65287..3a7fd20308 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -10,6 +10,7 @@ A companion guide `CLAUDE.md` at the repo root carries the shared rules for Clau - **Repository prose follows the Google developer documentation style guide** - `docs/`, `README.md`, `agentic/docs/`, changelog entries, and PR/issue text use [Google style](https://developers.google.com/style) (sentence-case headings, second person, numbered procedures); the concrete rules and the house-style exception (`docs/reference/style-guide.md` governs website/brand surfaces) live in the `write-docs` skill (`.claude/skills/write-docs/SKILL.md`). Existing docs migrate on touch, not via bulk rewrites. - **Changelog and releases** - see [Changelog + releases](#changelog--releases) below: every PR adds a fragment under `changelog.d/` and adds nothing to `CHANGELOG.md`, a release folds the fragments and bumps the version files via a PR, and the GitHub release is that section condensed, never copied. When reviewing a non-exempt PR that lacks a fragment — or that ADDS a bullet to `[Unreleased]` — flag it; correcting the wording of a bullet already there is allowed and must not be flagged. - **Never echo secret values into transcripts or logs** - Verify secrets by exit code or metadata, never by printing them. +- **Fix small build/test blockers directly, even when out of scope** - If a typecheck error, failing test, lint failure, or other small pipeline blocker shows up while you work on something unrelated, fix it in the same PR or a tiny follow-up — never leave it parked as "pre-existing" or "out of scope". A latent error that doesn't surface locally silently breaks the next Cloud Build, which deploys nothing while every PR check looks green. The bar: if the fix is under ~20 lines and obviously correct, make it; if it would expand scope meaningfully, ask first rather than deferring silently. - **Structural fix over symptomatic fix** - When a cheap symptomatic fix and a correct structural fix compete, take the structural one: fix the cause, never mute the alarm. Never modify working code to make a broken test pass — fix the test or flag it. - **Never manually merge a pipeline PR, and never bypass the pipeline** - Specifications and implementations go through the GitHub Actions workflows: `spec-create.yml` writes `plots/{spec-id}/specification.md` and `.yaml`, `impl-merge.yml` merges implementation PRs and creates their `metadata/*.yaml`, promotes the preview images to GCS and sets the `impl:{library}:done` label. Merging one by hand skips all of that and leaves `quality_score: null`, no review data, missing GCS images and the issue open. So: never write those files by hand, never run `gh pr merge` on a spec or implementation PR, and add the `approved` label to the **issue**, never to the PR. The full DON'T/DO table is in `CLAUDE.md`. Ordinary (non-pipeline) PRs are merged by the repository owner, not by an agent. @@ -23,7 +24,7 @@ A companion guide `CLAUDE.md` at the repo root carries the shared rules for Clau **Good tasks for Copilot:** - Bug fixes in existing plot implementations -- Adding new plot types following existing patterns +- Proposing new plot types as a `spec-request` issue (the pipeline writes the spec and implementations; see Important Rules) - Updating documentation - Writing or improving unit tests - Code refactoring within established patterns @@ -314,7 +315,7 @@ uv run alembic upgrade head ### Known Limitations -- **Package Manager**: `uv` may not be available in all environments. Fallback to `pip` if needed. +- **Package Manager**: Python dependencies are managed with `uv` only — run everything through `uv sync` and `uv run`, never `pip`. If `uv` is missing, install `uv` itself ([installation guide](https://docs.astral.sh/uv/getting-started/installation/)) instead of falling back to `pip`. - **External Dependencies**: Some domains may be blocked. If encountering network issues, document them in the PR. - **Database**: Cloud SQL requires proper credentials. Use `.env.example` as template for local development. @@ -327,7 +328,7 @@ uv run alembic upgrade head ### Common Issues -- **Import errors**: Run `uv sync --all-extras` or `pip install -e ".[dev]"` to install dependencies -- **Test failures**: Ensure you're testing only changes related to your task, not pre-existing issues +- **Import errors**: Run `uv sync --all-extras` to install dependencies +- **Test failures**: Fix a small failure you run into even when your task did not cause it (see "Fix small build/test blockers directly" under Important Rules); ask before a fix that would expand the PR's scope meaningfully - **Linting failures**: Run `uv run ruff check . --fix` to auto-fix common issues - **Type checking**: Add type hints using standard Python typing (e.g., `list[str]`, `dict[str, int]`) diff --git a/CLAUDE.md b/CLAUDE.md index 4845243ae7..24b723aab0 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -88,7 +88,7 @@ Known gaps with NO verification loop yet (reason through carefully and say so in - **Frontend**: Use `yarn` (not npm). Run `cd app && yarn` for installs, `cd app && yarn dev` for dev server. - **Backend**: Python dependencies managed via `pyproject.toml`. For transitive dependencies, update the lock file directly — do not add constraints to `pyproject.toml`. -- **Scripts**: Use `uv run` for running Python scripts. +- **Scripts**: Use `uv run` for running Python scripts. Python tooling is `uv` only — `uv sync` and `uv run`, never `pip`; if `uv` is missing, install `uv` itself instead of falling back to `pip`. ## Claude Code Configuration diff --git a/changelog.d/align-copilot-instructions.md b/changelog.d/align-copilot-instructions.md new file mode 100644 index 0000000000..91e28c06dd --- /dev/null +++ b/changelog.d/align-copilot-instructions.md @@ -0,0 +1,9 @@ +### Changed + +- **Copilot instructions agree with CLAUDE.md.** `.github/copilot-instructions.md` + now carries the "fix small build/test blockers directly, even when out of + scope" rule (under ~20 lines, ask first above that) instead of telling Copilot + to leave pre-existing failures alone, drops the `pip` fallback in favour of + `uv` only (now stated in both guides), and lists new plot types as a + `spec-request` issue rather than a hand-written implementation. The + instruction tests pin both rules on both sides. diff --git a/tests/unit/test_agent_instructions.py b/tests/unit/test_agent_instructions.py index 6dc80c0c64..d1256af34b 100644 --- a/tests/unit/test_agent_instructions.py +++ b/tests/unit/test_agent_instructions.py @@ -307,6 +307,16 @@ def test_every_named_skill_exists() -> None: "a release is condensed, never copied": ["condensed, never copied", "agentic/commands/release.md"], "never echo secret values": ["never echo secret"], "structural fix over symptomatic fix": ["structural fix over symptomatic fix"], + # The obligation (fix it, even out of scope) AND its limit (the ~20-line bar, + # ask first above it). Copilot's guide used to say the opposite — test only + # your own changes, leave pre-existing failures alone — until 2026-10-15. + "fix small build/test blockers, ask first if larger": [ + "fix small build/test blockers directly, even when out of scope", + "~20 lines", + "ask first rather than deferring silently", + ], + # Owner decision 2026-10-15: no `pip` fallback for either audience. + "python tooling is uv only": ["`uv` only", "never `pip`", "instead of falling back to `pip`"], # The repository's most consequential rule, and the one an agent that opens # and edits PRs is most able to break: specs and implementations go through # the workflows, and their PRs are merged by `impl-merge`, never by hand. From 0a85a1b256b852cdaa3461e2611e44301e8c0e54 Mon Sep 17 00:00:00 2001 From: Markus Neusinger <2921697+MarkusNeusinger@users.noreply.github.com> Date: Thu, 15 Oct 2026 09:48:47 +0200 Subject: [PATCH 2/2] chore: add PR reference to the align-copilot-instructions fragment Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01GdMSqLR5ww4ji74EUSmk9M --- changelog.d/align-copilot-instructions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changelog.d/align-copilot-instructions.md b/changelog.d/align-copilot-instructions.md index 91e28c06dd..e5d95e5bff 100644 --- a/changelog.d/align-copilot-instructions.md +++ b/changelog.d/align-copilot-instructions.md @@ -6,4 +6,4 @@ to leave pre-existing failures alone, drops the `pip` fallback in favour of `uv` only (now stated in both guides), and lists new plot types as a `spec-request` issue rather than a hand-written implementation. The - instruction tests pin both rules on both sides. + instruction tests pin both rules on both sides. (#12188)