Compare commits

...
1 Commits
Author SHA1 Message Date
Tunglies d7ac6b5bca chore(docs): centralize issue guidance and trim PR descriptions 2026-11-16 23:43:58 +08:00
5 changed files with 73 additions and 18 deletions
+31
View File
@@ -0,0 +1,31 @@
# Issue and PR Guidelines
These rules apply to Issue and PR work, including operations through `gh` or an
API. The root [AGENTS.md](../AGENTS.md) defines the repository-wide contract.
## Issues
When creating, drafting, triaging, splitting, or implementing from a community
issue, follow [ISSUE_GUIDELINES.md](ISSUE_GUIDELINES.md). Do not create or modify
GitHub issues without explicit authorization.
## PR Descriptions
When creating or updating a PR body, follow the
[PR template](PULL_REQUEST_TEMPLATE.md). Describe the final change; replace stale
text instead of appending work history. Omit routine check-pass declarations,
including Clippy, lint, and local tests. Keep only evidence and limitations that
help reviewers assess the change; the template defines what belongs in the body
and when Scope is needed.
Before publishing or updating a PR body, remove repetition, self-evaluation, and
details already clear from the diff. Keep only sentences that help review the
change.
## AI Disclosure
When an agent creates or co-creates a PR or Issue, append a final body line with
the model and effort used (e.g. `Assisted by: GPT-5.6 High`). Effort may be omitted
when the runtime does not report it. Human contributors are not asked to disclose
AI assistance. Disclosure is transparency only and carries no positive or
negative weight.
+29 -1
View File
@@ -1,3 +1,29 @@
<!--
Describe the final problem, approach, and evidence needed to review this change.
When updating the body, replace stale text instead of appending implementation
history or review-round summaries.
State each fact once. Omit details already clear from the diff unless they
explain a non-obvious constraint or trade-off. Describe concrete behavior instead
of self-evaluation or unsupported assurances such as "more robust" or "seamless".
Mention unchanged behavior or excluded areas only when they matter to review.
Before publishing, remove any sentence whose deletion loses no information
needed to understand the problem, approach, evidence, or material limitations.
Omit file-by-file diff summaries, internal planning scores, agent handoffs, and
routine check results such as "Clippy passed", "lint passed", or "local tests
passed". Do not add a Validation/Testing section for a command checklist.
Include concrete before/after behavior or measurements when they support the
change, and retain limitations that affect review. Link reviewer-accessible
details when needed; do not paste full scripts, logs, or test matrices into the
body, including collapsed sections.
Keep Scope only when explaining necessary changes outside the core fix, PR
dependencies, or why added tests are needed. Do not repeat Approach there.
For small changes, Problem and Approach may be combined into one short paragraph;
remove unnecessary headings instead of adding text to fill them.
-->
## Problem ## Problem
What breaks or what is missing. Product bug fixes and features require a What breaks or what is missing. Product bug fixes and features require a
@@ -14,4 +40,6 @@ Why this change solves the problem — the reasoning behind the approach, not a
## Scope ## Scope
What changed. If anything outside the core fix was touched, explain why it was necessary. New tests are not expected by default — if any were added, justify why each is needed. Optional: explain necessary changes outside the core fix, PR dependencies, or
why added tests are needed. Otherwise remove this section. New tests are not
expected by default.
+5 -2
View File
@@ -12,6 +12,7 @@ on:
- REVIEW.md - REVIEW.md
- src/AGENTS.md - src/AGENTS.md
- src-tauri/AGENTS.md - src-tauri/AGENTS.md
- .github/AGENTS.md
- .github/ISSUE_GUIDELINES.md - .github/ISSUE_GUIDELINES.md
- .github/agents/agentic-workflows.md - .github/agents/agentic-workflows.md
- .github/skills/agentic-workflows/SKILL.md - .github/skills/agentic-workflows/SKILL.md
@@ -30,6 +31,7 @@ on:
- REVIEW.md - REVIEW.md
- src/AGENTS.md - src/AGENTS.md
- src-tauri/AGENTS.md - src-tauri/AGENTS.md
- .github/AGENTS.md
- .github/ISSUE_GUIDELINES.md - .github/ISSUE_GUIDELINES.md
- .github/agents/agentic-workflows.md - .github/agents/agentic-workflows.md
- .github/skills/agentic-workflows/SKILL.md - .github/skills/agentic-workflows/SKILL.md
@@ -57,7 +59,8 @@ jobs:
check AGENTS.md 'Issue first' check AGENTS.md 'Issue first'
check AGENTS.md 'Author accountability' check AGENTS.md 'Author accountability'
check AGENTS.md 'pr-ai-slop-review' check AGENTS.md 'pr-ai-slop-review'
check AGENTS.md 'Disclose AI automation' check AGENTS.md '(.github/AGENTS.md)'
check .github/AGENTS.md '## AI Disclosure'
check CONTRIBUTING.md 'Assisted by:' check CONTRIBUTING.md 'Assisted by:'
check .github/workflows/pr-ai-slop-review.md '(../../CONTRIBUTING.md)' check .github/workflows/pr-ai-slop-review.md '(../../CONTRIBUTING.md)'
check .github/workflows/pr-ai-slop-review.md '(../../AGENTS.md)' check .github/workflows/pr-ai-slop-review.md '(../../AGENTS.md)'
@@ -84,7 +87,7 @@ jobs:
sources = [ sources = [
"AGENTS.md", "CONTRIBUTING.md", "REVIEW.md", "CLAUDE.md", "GEMINI.md", "AGENTS.md", "CONTRIBUTING.md", "REVIEW.md", "CLAUDE.md", "GEMINI.md",
"src/AGENTS.md", "src-tauri/AGENTS.md", ".github/ISSUE_GUIDELINES.md", "src/AGENTS.md", "src-tauri/AGENTS.md", ".github/AGENTS.md", ".github/ISSUE_GUIDELINES.md",
".github/PULL_REQUEST_TEMPLATE.md", ".github/workflows/pr-ai-slop-review.md", ".github/PULL_REQUEST_TEMPLATE.md", ".github/workflows/pr-ai-slop-review.md",
".github/workflows/pr-verify-fix.md", ".github/workflows/pr-verify-fix.md",
".github/agents/agentic-workflows.md", ".github/skills/agentic-workflows/SKILL.md", ".github/agents/agentic-workflows.md", ".github/skills/agentic-workflows/SKILL.md",
+4 -12
View File
@@ -48,16 +48,11 @@ the ownership evidence the AI-slop review evaluates (see
8. **Minimal diffs.** Match the surrounding code's style, naming, and comment 8. **Minimal diffs.** Match the surrounding code's style, naming, and comment
density. Do not introduce new dependencies or restructure working code unless density. Do not introduce new dependencies or restructure working code unless
the linked issue or stated task demands it. the linked issue or stated task demands it.
9. **Disclose AI automation.** When an agent creates or co-creates a PR or Issue, 9. **Compiled workflows.** Agentic workflow Markdown, including the
append a final body line with the model and effort used (e.g.
`Assisted by: GPT-5.6 High`). Effort may be omitted when the runtime does not
report it. Human contributors are not asked to disclose AI assistance.
Disclosure is transparency only and carries no positive or negative weight.
10. **Compiled workflows.** Agentic workflow Markdown, including the
[AI-slop policy](.github/workflows/pr-ai-slop-review.md) and shared imports, [AI-slop policy](.github/workflows/pr-ai-slop-review.md) and shared imports,
is compiled: after editing it, run `gh aw compile` and commit the affected is compiled: after editing it, run `gh aw compile` and commit the affected
`.lock.yml` files. Never edit lock files directly. `.lock.yml` files. Never edit lock files directly.
11. **Changelog.** Entries follow the rules in 10. **Changelog.** Entries follow the rules in
[`template/Changelog.md`](template/Changelog.md): one line per [`template/Changelog.md`](template/Changelog.md): one line per
user-visible change, no internals. user-visible change, no internals.
@@ -78,8 +73,5 @@ the ownership evidence the AI-slop review evaluates (see
## Issue and PR Workflows ## Issue and PR Workflows
When drafting, triaging, splitting, or implementing from a community issue, use For Issue and PR work, read [`.github/AGENTS.md`](.github/AGENTS.md), including
the conditional checklist in [`.github/ISSUE_GUIDELINES.md`](.github/ISSUE_GUIDELINES.md). when using `gh` or an API without editing files under `.github/`.
Do not make GitHub issue changes without explicit authorization. For PRs, follow
the directly loaded [PR template](.github/PULL_REQUEST_TEMPLATE.md); do not
duplicate its prompts here.
+4 -3
View File
@@ -168,9 +168,10 @@ to run every command for every change. Run commands from the repository root.
Tie results to the code reviewed: identify the base/head commits for branch Tie results to the code reviewed: identify the base/head commits for branch
comparisons and include task-relevant staged, unstaged, and untracked files in a comparisons and include task-relevant staged, unstaged, and untracked files in a
local review. Report local review. Keep command-level results in the working conversation. For PR
the command or interaction, observed result, and material gaps in the existing descriptions, follow the [PR template](.github/PULL_REQUEST_TEMPLATE.md): include
conversation or PR; no separate verification report is required. Static checks, behavioral evidence and material gaps relevant to review, omitting routine check
pass lists. No separate verification report is required. Static checks,
mocks, browser previews, native runs, and remote CI establish different things. mocks, browser previews, native runs, and remote CI establish different things.
When code changes after verification, repeat affected checks. Attribute a failure When code changes after verification, repeat affected checks. Attribute a failure
to the baseline only after comparing the same check on the base revision. to the baseline only after comparing the same check on the base revision.