From 50e687d17d7c7cd825efc23a67b76360c3c77ba8 Mon Sep 17 00:00:00 2001
From: Tak Hoffman <781889+Takhoffman@users.noreply.github.com>
Date: Thu, 5 Feb 2026 23:59:47 -0600
Subject: [PATCH] Docs: add PR and issue submission guides (#10150)

* Docs: add PR and issue submission guides

* Docs: fix LLM-assisted wording
---
 AGENTS.md                        |   2 +
 docs/docs.json                   |   2 +-
 docs/help/submitting-a-pr.md     | 214 +++++++++++++++++++++++++++++++
 docs/help/submitting-an-issue.md | 165 ++++++++++++++++++++++++
 4 files changed, 382 insertions(+), 1 deletion(-)
 create mode 100644 docs/help/submitting-a-pr.md
 create mode 100644 docs/help/submitting-an-issue.md

diff --git a/AGENTS.md b/AGENTS.md
index 11b4becf3a..482c8fe523 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -95,6 +95,8 @@
 - Group related changes; avoid bundling unrelated refactors.
 - Changelog workflow: keep latest released version at top (no `Unreleased`); after publishing, bump version and start a new top section.
 - PRs should summarize scope, note testing performed, and mention any user-facing changes or new flags.
+- Read this when submitting a PR: `docs/help/submitting-a-pr.md` ([Submitting a PR](https://docs.openclaw.ai/help/submitting-a-pr))
+- Read this when submitting an issue: `docs/help/submitting-an-issue.md` ([Submitting an Issue](https://docs.openclaw.ai/help/submitting-an-issue))
 - PR review flow: when given a PR link, review via `gh pr view`/`gh pr diff` and do **not** change branches.
 - PR review calls: prefer a single `gh pr view --json ...` to batch metadata/comments; run `gh pr diff` only when needed.
 - Before starting a review when a GH Issue/PR is pasted: run `git pull`; if there are local changes or unpushed commits, stop and alert the user before reviewing.
diff --git a/docs/docs.json b/docs/docs.json
index 3f2b5b118e..62a3959366 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -1230,7 +1230,7 @@
               },
               {
                 "group": "Developer workflows",
-                "pages": ["start/setup"]
+                "pages": ["start/setup", "help/submitting-a-pr", "help/submitting-an-issue"]
               },
               {
                 "group": "Docs meta",
diff --git a/docs/help/submitting-a-pr.md b/docs/help/submitting-a-pr.md
new file mode 100644
index 0000000000..2259a730fe
--- /dev/null
+++ b/docs/help/submitting-a-pr.md
@@ -0,0 +1,214 @@
+---
+summary: "How to submit a high signal PR"
+title: "Submitting a PR"
+---
+
+# Submitting a PR
+
+Good PRs make it easy for reviewers to understand intent, verify behavior, and land changes safely. This guide focuses on high-signal, low-noise submissions that work well with both human review and LLM-assisted review.
+
+## What makes a good PR
+
+- [ ] Clear intent: explain the problem, why it matters, and what the change does.
+- [ ] Tight scope: keep changes focused and avoid drive-by refactors.
+- [ ] Behavior summary: call out user-visible changes, config changes, and defaults.
+- [ ] Tests: list what ran, what was skipped, and why.
+- [ ] Evidence: include logs, screenshots, or short recordings for UI or workflows.
+- [ ] Code word: include “lobster-biscuit” somewhere in the PR description to confirm you read this guide.
+- [ ] Baseline checks: run the relevant `pnpm` commands for this repo and fix failures before opening the PR.
+- [ ] Due diligence: search the codebase for existing functionality and check GitHub for related issues or prior fixes.
+- [ ] Grounded in reality: claims should be backed by evidence, reproduction, or direct observation.
+- [ ] Title guidance: use a verb + scope + outcome (for example `Docs: add PR and issue templates`).
+
+Guideline: concision > grammar. Be terse if it makes review faster.
+
+Baseline validation commands (run as appropriate for the change, and fix failures before submitting):
+
+- `pnpm lint`
+- `pnpm check`
+- `pnpm build`
+- `pnpm test`
+- If you touch protocol code: `pnpm protocol:check`
+
+## Progressive disclosure
+
+Use a short top section, then deeper details as needed.
+
+1. Summary and intent
+2. Behavior changes and risks
+3. Tests and verification
+4. Implementation details and evidence
+
+This keeps review fast while preserving deep context for anyone who needs it.
+
+## Common PR types and expectations
+
+- [ ] Fix: include clear repro, root cause summary, and verification steps.
+- [ ] Feature: include use cases, behavior changes, and screenshots or demos when UI is involved.
+- [ ] Refactor: explicitly state “no behavior change” and list what moved or was simplified.
+- [ ] Chore/Maintenance: note why it matters (build time, CI stability, dependency hygiene).
+- [ ] Docs: include before/after context and link to the updated page. Run `pnpm format`.
+- [ ] Test: explain the gap it covers and how it prevents regressions.
+- [ ] Perf: include baseline and after metrics, plus how they were measured.
+- [ ] UX/UI: include screenshots or short recordings and any accessibility impact.
+- [ ] Infra/Build: call out affected environments and how to validate.
+- [ ] Security: include threat or risk summary, repro steps, and verification plan. Avoid sensitive data in public logs.
+- [ ] Security: keep reports grounded in reality; avoid speculative claims.
+
+## Checklist
+
+- [ ] Problem and intent are clear
+- [ ] Scope is focused
+- [ ] Behavior changes are listed
+- [ ] Tests are listed with results
+- [ ] Evidence is attached when needed
+- [ ] No secrets or private data
+- [ ] Grounded in reality: no guesswork or invented context.
+
+## Template
+
+```md
+## Summary
+
+## Behavior Changes
+
+## Codebase and GitHub Search
+
+## Tests
+
+## Evidence
+```
+
+## Templates by PR type
+
+### Fix
+
+```md
+## Summary
+
+## Repro Steps
+
+## Root Cause
+
+## Behavior Changes
+
+## Tests
+
+## Evidence
+```
+
+### Feature
+
+```md
+## Summary
+
+## Use Cases
+
+## Behavior Changes
+
+## Existing Functionality Check
+
+I searched the codebase for existing functionality before implementing this.
+
+## Tests
+
+## Evidence
+```
+
+### Refactor
+
+```md
+## Summary
+
+## Scope
+
+## No Behavior Change Statement
+
+## Tests
+```
+
+### Chore/Maintenance
+
+```md
+## Summary
+
+## Why This Matters
+
+## Tests
+```
+
+### Docs
+
+```md
+## Summary
+
+## Pages Updated
+
+## Screenshots or Before/After
+
+## Formatting
+
+pnpm format
+```
+
+### Test
+
+```md
+## Summary
+
+## Gap Covered
+
+## Tests
+```
+
+### Perf
+
+```md
+## Summary
+
+## Baseline
+
+## After
+
+## Measurement Method
+
+## Tests
+```
+
+### UX/UI
+
+```md
+## Summary
+
+## Screenshots or Video
+
+## Accessibility Impact
+
+## Tests
+```
+
+### Infra/Build
+
+```md
+## Summary
+
+## Environments Affected
+
+## Validation Steps
+```
+
+### Security
+
+```md
+## Summary
+
+## Risk Summary
+
+## Repro Steps
+
+## Mitigation or Fix
+
+## Verification
+
+## Tests
+```
diff --git a/docs/help/submitting-an-issue.md b/docs/help/submitting-an-issue.md
new file mode 100644
index 0000000000..a91a4678bb
--- /dev/null
+++ b/docs/help/submitting-an-issue.md
@@ -0,0 +1,165 @@
+---
+summary: "How to file high signal issues and bug reports"
+title: "Submitting an Issue"
+---
+
+# Submitting an Issue
+
+Good issues make it easy to reproduce, diagnose, and fix problems quickly. This guide covers what to include for bugs, regressions, and feature gaps.
+
+## What makes a good issue
+
+- [ ] Clear title: include the area and the symptom.
+- [ ] Repro steps: minimal steps that consistently reproduce the issue.
+- [ ] Expected vs actual: what you thought would happen and what did.
+- [ ] Impact: who is affected and how severe the problem is.
+- [ ] Environment: OS, runtime, versions, and relevant config.
+- [ ] Evidence: logs, screenshots, or recordings (redacted; prefer non-PII data).
+- [ ] Scope: note if it is new, regression, or long-standing.
+- [ ] Code word: include “lobster-biscuit” somewhere in the issue description to confirm you read this guide.
+- [ ] Due diligence: search the codebase for existing functionality and check GitHub to see if the issue is already filed or fixed.
+- [ ] I searched for existing and recently closed issues/PRs.
+- [ ] For security reports: confirmed it has not already been fixed or addressed recently.
+- [ ] Grounded in reality: claims should be backed by evidence, reproduction, or direct observation.
+
+Guideline: concision > grammar. Be terse if it makes review faster.
+
+Baseline validation commands (run as appropriate for the change, and fix failures before submitting a PR):
+
+- `pnpm lint`
+- `pnpm check`
+- `pnpm build`
+- `pnpm test`
+- If you touch protocol code: `pnpm protocol:check`
+
+## Templates
+
+### Bug report
+
+```md
+## Bug report checklist
+
+- [ ] Minimal repro steps
+- [ ] Expected vs actual
+- [ ] Versions and environment
+- [ ] Affected channels and where it does not reproduce
+- [ ] Logs or screenshots
+- [ ] Evidence is redacted and non-PII where possible
+- [ ] Impact and severity
+- [ ] Any known workarounds
+
+## Summary
+
+## Repro Steps
+
+## Expected
+
+## Actual
+
+## Environment
+
+## Logs or Evidence
+
+## Impact
+
+## Workarounds
+```
+
+### Security issue
+
+```md
+## Summary
+
+## Impact
+
+## Affected Versions
+
+## Repro Steps (if safe to share)
+
+## Mitigation or Workaround
+
+## Evidence (redacted)
+```
+
+Security note: avoid posting secrets or exploit details in public issues. If the report is sensitive, keep repro details minimal and ask for a private disclosure path.
+
+### Regression report
+
+```md
+## Summary
+
+## Last Known Good
+
+## First Known Bad
+
+## Repro Steps
+
+## Expected
+
+## Actual
+
+## Environment
+
+## Logs or Evidence
+
+## Impact
+```
+
+### Feature request
+
+```md
+## Summary
+
+## Problem
+
+## Proposed Solution
+
+## Alternatives Considered
+
+## Impact
+
+## Evidence or Examples
+```
+
+### Enhancement request
+
+```md
+## Summary
+
+## Current Behavior
+
+## Desired Behavior
+
+## Why This Matters
+
+## Alternatives Considered
+
+## Evidence or Examples
+```
+
+### Investigation request
+
+```md
+## Summary
+
+## Symptoms
+
+## What Was Tried
+
+## Environment
+
+## Logs or Evidence
+
+## Impact
+```
+
+## If you are submitting a fix PR
+
+Creating a separate issue first is optional. If you skip it, include the relevant details in the PR description.
+
+- Keep the PR focused on the issue.
+- Include the issue number in the PR description.
+- Add tests when possible, or explain why they are not feasible.
+- Note any behavior changes and risks.
+- Include redacted logs, screenshots, or videos that validate the fix.
+- Run relevant `pnpm` validation commands and report results when appropriate.