From aaf143df78fa0382df5e0faac69ae35c488c6a75 Mon Sep 17 00:00:00 2001 From: XuPeng-SH Date: Wed, 14 Oct 2026 15:34:30 +0800 Subject: [PATCH 1/2] docs(skills): validate GitHub templates before delivery --- .agents/skills/mo-dev/SKILL.md | 2 + .../mo-dev/references/github-delivery.md | 70 +++++++++++++++++++ .agents/skills/mo-self-review/SKILL.md | 2 + 3 files changed, 74 insertions(+) create mode 100644 .agents/skills/mo-dev/references/github-delivery.md diff --git a/.agents/skills/mo-dev/SKILL.md b/.agents/skills/mo-dev/SKILL.md index e9d671344a9f9..b7be31dbe6214 100644 --- a/.agents/skills/mo-dev/SKILL.md +++ b/.agents/skills/mo-dev/SKILL.md @@ -52,6 +52,7 @@ Read a reference when its trigger applies: | Need | Read | |---|---| | Change/risk map, efficient validation order, CI/local evidence reuse | [references/validation-evidence.md](references/validation-evidence.md) | +| Create/update a GitHub PR or issue, or diagnose a PR-description/commit-message check | [references/github-delivery.md](references/github-delivery.md) | | Credible shared-state/lifecycle/synchronization/timing failure mode | [references/race-validation.md](references/race-validation.md) | | Large/complex feature or major refactor; design document review (RFC optional) | [references/feature-design-review.md](references/feature-design-review.md) | | UT/BVT purpose, orthogonality, fixture reuse, cost/flakiness, result and execution evidence | [references/testing-contract.md](references/testing-contract.md) | @@ -239,6 +240,7 @@ Before delivery, the record must show: □ UT/BVT and specialized-domain decisions recorded □ every required proof is validly reused or passed; gaps/pending work are explicit □ generated/delivery artifacts, diff stat, and unintended files checked +□ PR/issue delivery in scope: current-template and LF-body preflight passed; verify remote body after publication □ `mo-self-review` has zero unresolved blockers ``` diff --git a/.agents/skills/mo-dev/references/github-delivery.md b/.agents/skills/mo-dev/references/github-delivery.md new file mode 100644 index 0000000000000..cfa16ea92ddf7 --- /dev/null +++ b/.agents/skills/mo-dev/references/github-delivery.md @@ -0,0 +1,70 @@ +# GitHub PR and issue delivery + +Use this reference when reviewing a PR description, creating or updating a +PR/issue, or investigating a description-dependent check. Metadata-only delivery +does not require rerunning product tests. In external review, inspect the stored +body and report actionable mismatches; do not edit it without authorization. + +## Use the repository's current template + +- Read the current template from the target repository's verified default + branch; a long-lived working branch can contain an obsolete template. +- For PRs, start from `.github/PULL_REQUEST_TEMPLATE.md` (or the repository's + selected PR template). Preserve its heading text, punctuation, level, and + order; fill its sections and applicable type checkboxes. Keep validation and + limitations in the description section unless the template provides another + place. Replace placeholders with real content and link the relevant issues; + use closing keywords only for issues this change actually closes. +- For issues, select the appropriate `.github/ISSUE_TEMPLATE/*.yml` form or + Markdown template. CLI/API creation does not enforce GitHub issue-form + validation: render form field labels as Markdown headings and populate the + required fields/checklists. Honor the selected template's title convention + and metadata defaults within the authorized creation scope. Do not claim a + duplicate search or reproduction was performed unless it was. Mark missing + facts explicitly; never invent a commit, environment, or result. +- When updating an existing body, preserve useful author content and inspect + the body immediately before the write to avoid overwriting concurrent edits. + Template alignment is not a reason to relabel or reassign an existing issue. + +## Normalize and verify the actual body + +Before publication, serialize UTF-8 with LF line endings, removing a leading +UTF-8 BOM and converting CRLF or lone CR to LF. Keep real newlines, not literal +`\n` text used as paragraph separators. Preserve intentional escape sequences +inside code examples. Normalize the final file or structured argument being sent, +not just a displayed preview. For an already prepared body file: + +```python +from pathlib import Path +body_path = Path("/tmp/mo-pr-body.md") # use this task's actual body file +body = body_path.read_bytes().decode("utf-8-sig") +body = body.replace("\r\n", "\n").replace("\r", "\n") +body_path.write_bytes(body.encode("utf-8")) +``` + +Check required sections and their substantive content against the template. +If Mergify extracts a section, also inspect the current `.github/mergify.yml` +and compare its `get_section(...)` argument with the actual heading. Do not +paraphrase, decorate, indent, or put that heading inside a code block. +MatrixOne currently extracts `## What this PR does / why we need it:`; read +the current configuration rather than treating this spelling as permanent. + +Template/content and encoding checks are the pre-publication gate. Remote +readback is a post-publication check, so it cannot block creation of a new PR. +Publish within the authorized scope with a structured tool argument or +`gh ... --body-file `. +Read the stored body back through GitHub, check LF and required headings, and +compare it with the intended text. For a failed description check, inspect the +new check result when available; a successful body update alone does not prove +the automation recovered. Report pending checks explicitly. + +## Diagnose without overclaiming + +`Invalid commit message` / `section not found` identifies template rendering +failure. CRLF is a candidate cause when the expected heading is present; prove +it with the parser or a new successful check after changing only line endings, +with unchanged configuration, before calling it the root cause. Distinguish +this from workflow-permission errors and product CI failures. If one targeted +correction still fails, inspect the template/parser evidence and report the +remaining blocker rather than repeatedly editing metadata or rerunning unrelated +CI. diff --git a/.agents/skills/mo-self-review/SKILL.md b/.agents/skills/mo-self-review/SKILL.md index 602b3bccc6249..7fca55eed9a65 100644 --- a/.agents/skills/mo-self-review/SKILL.md +++ b/.agents/skills/mo-self-review/SKILL.md @@ -56,6 +56,7 @@ deep tracing, not awareness of in-scope changes that can interact with it. | Trigger | Read | |---|---| | Every non-trivial review: change map, R0-R3 routing, evidence reuse, efficient validation | [../mo-dev/references/validation-evidence.md](../mo-dev/references/validation-evidence.md) | +| PR description review, PR/issue creation or body update; Mergify description/commit-message failure | [../mo-dev/references/github-delivery.md](../mo-dev/references/github-delivery.md) | | Credible shared-state/lifecycle/synchronization/timing failure mode | [../mo-dev/references/race-validation.md](../mo-dev/references/race-validation.md) | | Large/complex feature or major refactor; design document (RFC optional) | [../mo-dev/references/feature-design-review.md](../mo-dev/references/feature-design-review.md) | | Shared state, cancel/close, callbacks, retry/restart, pooling/reuse, async cleanup | [references/concurrency-lifecycle.md](references/concurrency-lifecycle.md) | @@ -203,6 +204,7 @@ partial-output, or surviving-process runs are not green. □ each finding has a concrete path or objective gate failure and source re-read □ decisions logged, severity calibrated last, zero unresolved blockers for PASS □ final delivery diff/generated artifacts checked in self mode +□ PR description/template checked where applicable; delivery body preflight passed before publication, remote readback afterward ``` For index-plugin changes, additionally run the linked section-9 candidate From 217fd97e9c5e57df967a048d89929fa39b97bec8 Mon Sep 17 00:00:00 2001 From: XuPeng-SH Date: Wed, 14 Oct 2026 15:47:51 +0800 Subject: [PATCH 2/2] docs(skills): require relevant issue references for PRs --- .agents/skills/mo-dev/references/github-delivery.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/.agents/skills/mo-dev/references/github-delivery.md b/.agents/skills/mo-dev/references/github-delivery.md index cfa16ea92ddf7..fe3273b59c14d 100644 --- a/.agents/skills/mo-dev/references/github-delivery.md +++ b/.agents/skills/mo-dev/references/github-delivery.md @@ -13,8 +13,13 @@ body and report actionable mismatches; do not edit it without authorization. selected PR template). Preserve its heading text, punctuation, level, and order; fill its sections and applicable type checkboxes. Keep validation and limitations in the description section unless the template provides another - place. Replace placeholders with real content and link the relevant issues; - use closing keywords only for issues this change actually closes. + place. Replace placeholders with real content. MatrixOne PRs must link a real, + relevant issue in the issue section; do not substitute `N/A` or a PR number. + Search existing issues, including closed ones, before preparing a new issue. + Use `Related to #...` for follow-up work on a closed issue, and closing keywords + only for open issues this change actually closes. If no relevant issue exists, + prepare one with the appropriate template and publish within the authorized + scope; do not invent an issue number or attach unrelated work. - For issues, select the appropriate `.github/ISSUE_TEMPLATE/*.yml` form or Markdown template. CLI/API creation does not enforce GitHub issue-form validation: render form field labels as Markdown headings and populate the