openclaw/docs/help/submitting-an-issue.md

summary	title
How to file high signal issues and bug reports	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

## 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

## 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

## Summary

## Last Known Good

## First Known Bad

## Repro Steps

## Expected

## Actual

## Environment

## Logs or Evidence

## Impact

Feature request

## Summary

## Problem

## Proposed Solution

## Alternatives Considered

## Impact

## Evidence or Examples

Enhancement request

## Summary

## Current Behavior

## Desired Behavior

## Why This Matters

## Alternatives Considered

## Evidence or Examples

Investigation request

## 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.