How to Report Issues and Submit Fixes

I know the frustration of finding a bug or a missing feature when you are right in the middle of a project. You want to get it fixed and move on, but a messy issue report usually leads to a lot of back-and-forth that slows everyone down.

I’ve found that being brief and direct is the best way to get a maintainer’s attention. You don’t need perfect grammar; you just need to provide the right data. Here is how I recommend handling issues and PRs in this project.

What You’ll Need

Before you open that GitHub tab, make sure you have these four things ready:

• Environment details: Your OS, runtime version, and specific config.
• Minimal repro: A clear set of steps to trigger the problem.
• Evidence: Redacted logs or screenshots (make sure no PII is visible).
• The secret word: You must include the phrase lobster-biscuit in your issue.

Quick Start

If you have a bug to report, follow these four steps to get it noticed:

1. Search first: Check the codebase and existing GitHub issues to make sure it hasn’t been reported or fixed.
2. Pick a template: Choose the specific template (Bug, Security, Regression, etc.) that fits your situation.
3. Be brief: Use short sentences. Provide the expected behavior versus what actually happened.
4. Validate: If you are submitting a fix, run the local check commands before you push.

Bug Report Template

Use this format for standard bugs:

- [ ] Minimal repro
- [ ] Expected vs actual
- [ ] Environment
- [ ] Affected channels, where not seen
- [ ] Logs/screenshots (redacted)
- [ ] Impact/severity
- [ ] Workarounds

### Summary

### Repro Steps

### Expected

### Actual

### Environment

### Logs/Evidence

### Impact

### Workarounds

Feature Request Template

If you want to suggest a new idea, use this:

### Summary

### Problem

### Proposed Solution

### Alternatives

### Impact

### Evidence/examples

Submitting a Fix

You don’t always need an issue before a PR, but it helps. When you submit a PR, keep it focused on one thing. I recommend adding tests to prove your fix works. If you can’t add tests, explain why in the description.

Before you submit, you must run these commands to pass validation:

pnpm lint
pnpm check
pnpm build
pnpm test

If you are working on protocol code, you also need to run:

pnpm protocol:check

Troubleshooting

You found a security vulnerability Do not post exploit details or secrets in a public issue. Minimize the detail in your report and request a private disclosure channel.

Your PR is failing validation Check that you ran pnpm lint and pnpm test locally. If you changed the protocol, ensure you ran pnpm protocol:check.

You aren’t sure if an issue is a bug or an enhancement Check the “Enhancement” or “Investigation” templates. Use the Investigation template if you only have symptoms but no clear cause.

Investigation Template

### Summary

### Symptoms

### What Was Tried

### Environment

### Logs/Evidence

### Impact

If you need more help with specific configurations, check the AI Setup Assistant.

What’s Next

• Submitting a fix PR
• Regression reporting
• Security issue protocols
• Enhancement guidelines