Pulled from a retrospective on a feature PR that exercised every rule
already in the doc, and surfaced eight gaps where the doc was silent.
- Protocol-introducing changes (new section): require an explicit
cross-client compatibility section, on-relay wire-format verification
via nak, and a NIP spec citation when claiming "NIP-X allows this".
These three together prevent the "syncs across devices" handwave
from masking real interop questions.
- Release-minified build subsection in "Build and install both
flavours": call out the existing benchmark build type
(com.vitorpamplona.amethyst.benchmark, profileable=true, R8-active)
as the cheap rig for catching ViewModel-factory / expect-actual /
serialization R8-stripping bugs before the reviewer does.
- Strip diagnostic Log.d before commit: explicit policy. Lambda Log
is required for committed logs; temporary debug Log.d gets removed.
- Regression-test-plan worked example: shows the required
### Feature test plan / ### Regression test plan structure with a
real-shaped example, so contributors don't ship the wrong subheadings.
- Multi-device sync touch-point: added to the regression sweep
checklist for features that publish per-account state to relays.
- R8-minified-build touch-point: added to the same checklist for
reflection-heavy code paths.
- "When on-device QA finds bugs in your own diff" subsection in
"Code review pass": promote the pattern of landing manual-QA
fixes as a separate commit with root-cause prose, not folding
silently into the feature commit.
- Working-notes convention in "Everything else": clarify
docs/plans/ is tracked, docs/brainstorms/ + docs/superpowers/
are gitignored. Saves AI tools from trying to commit scratch work.
Two additional gates on top of the AI-companion guide:
- Automated tests for new logic — quartz/ and commons/ get unit
tests; bug fixes get a regression test; UI-only stays exempt
from automated UI tests but keeps the manual on-device test
plan + screenshots. Pointer into CONTRIBUTING.md § Interop tests.
- Code review pass before opening the PR — run a second-agent
review with a different model or skill (/simplify, /kotlin-review,
/security-review, /code-review), then re-run tests and manual
test plan to catch fix-introduced regressions.
CONTRIBUTING.md pointer paragraph updated to enumerate the two new
gates.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Companion to CONTRIBUTING.md targeting external PRs whose diff was
substantially authored by an AI coding assistant. Adds five gates the
existing doc does not cover:
- Research before code (issue still valid, decentralisation fit)
- Build and install both flavours (Play + F-Droid)
- Performance and resource hygiene (main-thread, coroutines,
LocalCache reuse, relay subscriptions, KMP source sets, lambda Log)
- Regression test plan alongside feature test plan
- Don't-touch list (signer/KeyStore, release pipeline, NIP direction)
Filename deliberately avoids AGENTS.md to keep internal dev-team
agents unaffected by auto-load conventions. CONTRIBUTING.md and the
PR template each gain a one-line pointer.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
davotoula