@gguf/claw 2026.2.4 → 2026.2.5

package/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
+```

package/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.