docs: onboarding Part 8 — change recipes and the subsystem rewrite guide

[Aakash1337]

Carries the Part 8 addition to docs/onboarding.md that was pushed to the claude/docs-deferrals branch after PR #24 had already merged (so #24's diff never included it — its updated description got ahead of reality). One commit, cherry-picked onto current main. Docs only.

Part 8 — changing the code (from one-line tweaks to full rewrites):

• 8.1 Recipes for the five common change types, each naming the file pairs that must change together and the trap that bites first-timers: config setting (config.py + .env.example, and the boto3/os.environ trap), column/table (models.py + 001_schema_evolution.sql + RLS, and why CI can't catch a missing ALTER), state/transition (states.py is the single source of truth), eligibility check (blocking vs deferrable + the adversarial-test convention), endpoint (routes + schemas + auth + the tenant-vs-admin session choice).
• 8.2 Subsystem rewrite guide — the seam map: every subsystem → its contract → the tests that pin it → whether it's freely replaceable. Compute, senders, pipeline runner, workers, API, UI, scheduler, CRM: yes, with the reason each rewrite is safe. Postgres + db/sql/ called out in bold as the one load-bearing layer you don't casually replace. Plus the five-step rewrite protocol: read the contract/adversarial tests, decision record first, rewrite behind the seam with the DB as safety net, just test-exit-gate as the non-negotiable acceptance bar, additive schema changes.

🤖 Generated with Claude Code

https://claude.ai/code/session_01ASAVj4XgJCH3UcHkZZaYzM

---

Generated by Claude Code

Summary by CodeRabbit

• Documentation
  • Expanded onboarding guidance with practical advice for making common product changes safely.
  • Added recommendations for updating settings, database structures, lead state logic, eligibility checks, and new endpoints.
  • Included a clearer process for larger subsystem rewrites, with steps for reviewing contracts, validating behavior, and keeping changes additive where needed.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: c9f7427c-821f-4fb8-9269-53babe2af247

📥 Commits

Reviewing files that changed from the base of the PR and between 3a62b02 and cb73f7b.

📒 Files selected for processing (1)

• docs/onboarding.md

---

📝 Walkthrough

Walkthrough

Adds a new "Part 8 — changing the code" section to docs/onboarding.md, covering recipes for common changes (config, migrations, state transitions, eligibility checks, endpoints) and guidance for rewriting whole subsystems, including a decision-record and test-gate protocol.

Changes

Onboarding Documentation Update

Layer / File(s)	Summary
Part 8: change recipes and rewrite protocol docs/onboarding.md	Adds "8.1 Recipes for common changes" (config, DB shape, state transitions, eligibility checks, endpoints) and "8.2 Rewriting whole subsystems" (contracts, decision records, seam-based rewrites, test acceptance gates).

Estimated code review effort: 1 (Trivial) | ~5 minutes

Related PRs: None identified.

Suggested labels: documentation

Suggested reviewers: None identified.

Poem

A rabbit sat with quill in paw,
To write the docs, to teach the law,
Of tweaks and seams and rewrite gates,
So future coders meet their fates
With calmer hearts and cleaner code —
Hop on, dear dev, down this new road! 🐇📖

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/relay-onboarding-part8

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}