nevzheng opened a new pull request, #12388: URL: https://github.com/apache/gravitino/pull/12388
### What changes were proposed in this pull request? Gravitino's agent instructions point to GitHub templates, but they do not give pull requests, Issues, and Discussions a shared reader-first writing standard. #12387 asks agents to lead with the bottom line instead of replaying a diff or chronology. This PR adds that guide and routes repository-aware agents through it. It preserves native artifact structure while defining top-down defaults, a conciseness pass before previews, and a freshness check after material changes. A read-only try-it-out prompt supports human evaluation without publishing or gating changes. ### Why are the changes needed? Generated writing can be accurate yet leave readers to infer its purpose, boundaries, and evidence. One shared framework makes the review story consistent without duplicating policy or removing human approval. Part of: #12387 ### Does this PR introduce _any_ user-facing change? No product-facing change. Repository-aware agents now receive shared guidance for pull requests, Issues, and Discussions and warn when published text may be stale. Existing GitHub templates, validation workflows, and design-document guidance remain unchanged. ### How was this patch tested? - `./gradlew rat` — `BUILD SUCCESSFUL in 2s`; one task executed. - `git diff --check` — no errors. - `git diff --name-only -- .github/PULL_REQUEST_TEMPLATE .github/ISSUE_TEMPLATE` — no output; native templates are unchanged. - Reviewed the agent entrypoints and confirmed that they resolve the shared guide without loading the advisory try-out prompt. - No runtime tests were run because this changes documentation and agent instructions only. ### Deep dive - `.github/WRITING_GUIDE.md` owns the shared writing, conciseness, and freshness guidance. - `AGENTS.md` owns routing, preview approval, and lifecycle checks. Codex and Cursor consume it directly; Claude and Gemini import it; Copilot points to it. - Claude-specific memory behavior remains isolated under `.claude/rules/`, while specialized documentation guidance defers PR metadata to the shared guide. - `.github/WRITING_GUIDE_EVAL.md` provides a read-only human try-out session and is not a production instruction. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
