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
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
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
- src/AGENTS.md
- src-tauri/AGENTS.md
- .github/AGENTS.md
- .github/ISSUE_GUIDELINES.md
- .github/agents/agentic-workflows.md
- .github/skills/agentic-workflows/SKILL.md
@@ -30,6 +31,7 @@ on:
- REVIEW.md
- src/AGENTS.md
- src-tauri/AGENTS.md
- .github/AGENTS.md
- .github/ISSUE_GUIDELINES.md
- .github/agents/agentic-workflows.md
- .github/skills/agentic-workflows/SKILL.md
@@ -57,7 +59,8 @@ jobs:
check AGENTS.md 'Issue first'
check AGENTS.md 'Author accountability'
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 .github/workflows/pr-ai-slop-review.md '(../../CONTRIBUTING.md)'
check .github/workflows/pr-ai-slop-review.md '(../../AGENTS.md)'
@@ -84,7 +87,7 @@ jobs:
sources = [
"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/workflows/pr-verify-fix.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
density. Do not introduce new dependencies or restructure working code unless
the linked issue or stated task demands it.
9. **Disclose AI automation.** 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.
10. **Compiled workflows.** Agentic workflow Markdown, including the
9. **Compiled workflows.** Agentic workflow Markdown, including the
[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
`.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
user-visible change, no internals.
@@ -78,8 +73,5 @@ the ownership evidence the AI-slop review evaluates (see
## Issue and PR Workflows
When drafting, triaging, splitting, or implementing from a community issue, use
the conditional checklist in [`.github/ISSUE_GUIDELINES.md`](.github/ISSUE_GUIDELINES.md).
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.
For Issue and PR work, read [`.github/AGENTS.md`](.github/AGENTS.md), including
when using `gh` or an API without editing files under `.github/`.
+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
comparisons and include task-relevant staged, unstaged, and untracked files in a
local review. Report
the command or interaction, observed result, and material gaps in the existing
conversation or PR; no separate verification report is required. Static checks,
local review. Keep command-level results in the working conversation. For PR
descriptions, follow the [PR template](.github/PULL_REQUEST_TEMPLATE.md): include
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.
When code changes after verification, repeat affected checks. Attribute a failure
to the baseline only after comparing the same check on the base revision.