docs: default caveman style for issues, PRs, and reviews
CI & Release / Verify documentation (push) Skipped
CI & Release / Verify simulator (push) Skipped
CI & Release / Trivy scan (push) Skipped
CI & Release / Semantic Release (push) Skipped
CI & Release / Verify documentation (pull_request) Successful in 5s
CI & Release / Verify simulator (pull_request) Failing after 9s
CI & Release / Trivy scan (pull_request) Skipped
CI & Release / Semantic Release (pull_request) Skipped

Document caveman-full as the collaboration voice in AGENTS and CONTRIBUTING,
and add Gitea issue/PR templates that pre-fill terse structure.
This commit is contained in:
2026-07-10 10:56:13 +01:00
parent e6e57843cb
commit bed6f93626
6 changed files with 110 additions and 0 deletions
+35
View File
@@ -77,6 +77,41 @@ test: cover broadcast frame roundtrip
Never include AI tool references, `Co-authored-by` trailers for assistants, or
identifying names of people, companies, or locations.
## Caveman style (default)
Use **caveman-full** in **issues**, **pull requests**, and **reviews** unless the
author explicitly asks otherwise.
| Do | Skip |
| --- | --- |
| Short lines, fragments OK | Long preamble ("I wanted to start by saying…") |
| Lead with what / why / verdict | Filler ("just", "basically", "kind of") |
| Bullets, checklists | Repeated context already in diff or issue |
| Exact terms, paths, code | Invented abbreviations or vague "the thing" |
**Examples**
| Fluffy | Caveman |
| --- | --- |
| I think we should probably consider adding a link checker to CI because links might break. | Add CI link checker. Broken relative links fail merge. |
| This pull request implements the documentation improvements that were discussed in the audit. | Docs audit: glossary T0T4, fix ground README link, rsync wording. |
| LGTM but maybe we could think about whether the anchor format is consistent? | Merge OK. Fix glossary anchors in follow-up (#1). |
README intensity: root = caveman-lite; `simulator/`, `prototype/`, `infra/`, `docs/adr/` READMEs =
caveman-full. Numbered design docs in `docs/` stay full prose.
Gitea pre-fills [issue](.github/ISSUE_TEMPLATE/default.md) and
[PR](.github/pull_request_template.md) templates with this style.
### Reviews
Default review voice = caveman-full:
1. **Verdict first** — merge / wait / no, or approve / request changes
2. **Findings** — bullet per blocker or nit; file + line when useful
3. **Scope** — say if issue AC met, partial, or out of scope
4. No essay; link ADR, issue, or doc section instead of restating design
## Pull request checklist
- [ ] Tests added or updated; `pytest tests/ -q` passes locally