diff --git a/.cursor/rules/coding-guidelines.mdc b/.cursor/rules/coding-guidelines.mdc new file mode 100644 index 0000000..edd317f --- /dev/null +++ b/.cursor/rules/coding-guidelines.mdc @@ -0,0 +1,70 @@ +--- +description: Behavioral guidelines to reduce common LLM coding mistakes. Use when writing, reviewing, or refactoring code to avoid overcomplication, make surgical changes, surface assumptions, and define verifiable success criteria. +alwaysApply: true +--- + +# Karpathy behavioral guidelines + +Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed. + +**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment. + +## 1. Think Before Coding + +**Don't assume. Don't hide confusion. Surface tradeoffs.** + +Before implementing: +- State your assumptions explicitly. If uncertain, ask. +- If multiple interpretations exist, present them - don't pick silently. +- If a simpler approach exists, say so. Push back when warranted. +- If something is unclear, stop. Name what's confusing. Ask. + +## 2. Simplicity First + +**Minimum code that solves the problem. Nothing speculative.** + +- No features beyond what was asked. +- No abstractions for single-use code. +- No "flexibility" or "configurability" that wasn't requested. +- No error handling for impossible scenarios. +- If you write 200 lines and it could be 50, rewrite it. + +Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify. + +## 3. Surgical Changes + +**Touch only what you must. Clean up only your own mess.** + +When editing existing code: +- Don't "improve" adjacent code, comments, or formatting. +- Don't refactor things that aren't broken. +- Match existing style, even if you'd do it differently. +- If you notice unrelated dead code, mention it - don't delete it. + +When your changes create orphans: +- Remove imports/variables/functions that YOUR changes made unused. +- Don't remove pre-existing dead code unless asked. + +The test: Every changed line should trace directly to the user's request. + +## 4. Goal-Driven Execution + +**Define success criteria. Loop until verified.** + +Transform tasks into verifiable goals: +- "Add validation" → "Write tests for invalid inputs, then make them pass" +- "Fix the bug" → "Write a test that reproduces it, then make it pass" +- "Refactor X" → "Ensure tests pass before and after" + +For multi-step tasks, state a brief plan: +``` +1. [Step] → verify: [check] +2. [Step] → verify: [check] +3. [Step] → verify: [check] +``` + +Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification. + +--- + +**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes. diff --git a/docs/relaunch-brief.md b/docs/relaunch-brief.md index 9dc4911..5e296a9 100644 --- a/docs/relaunch-brief.md +++ b/docs/relaunch-brief.md @@ -1,40 +1,29 @@ # CommunityRule relaunch -A short high-level summary of what's being built, what it replaces, and -how the cutover will work. +A short high-level summary of what's being built, what it replaces, and how the cutover will work. ## What gets replaced -The existing `CommunityRule` Cloudron app currently hosts three things in -one container: +The existing `CommunityRule` Cloudron app currently hosts three things in one container: - The static marketing site. - The Express + MySQL backend (rule drafting, publishing, OTP sign-in). - A Flask chatbot. -All three retire together when the new app goes live. The chatbot is -**not** being migrated or replaced in this stage. +All three retire together when the new app goes live. The chatbot is **not** being migrated or replaced in this stage. ## What the new app is -- A Next.js application with a Postgres database, packaged as a - Cloudron app (Docker image + `CloudronManifest.json`). +- A Next.js application with a Postgres database, packaged as a Cloudron app (Docker image + `CloudronManifest.json`). - Uses Cloudron's **postgresql + sendmail + localstorage** addons. - Cloudron's built-in container supervisor keeps it running. -- Sign-in changes from 4-digit email **codes** to email **links** - ("magic link" authentication). Users click a link in their inbox - instead of typing a code. -- One visible process, one port (3000), one health check - (`/api/health`), ~512 MiB memory — the same footprint as the - existing app. +- Cloudron's built-in container supervisor keeps it running. +- Sign-in changes from 4-digit email **codes** to email **links** ("magic link" authentication). Users click a link in their inbox instead of typing a code. +- One visible process, one port (3000), one health check (`/api/health`), ~512 MiB memory the same footprint as the existing app. ## What does NOT carry over - **No user accounts.** New sign-ins start fresh. -- **No published rules from the old database.** We'll count the - existing `rules` table before cutover and decide whether to publish - a read-only archive (CSV/JSON) somewhere for anyone looking for - their old work. +- **No published rules from the old database.** We'll count the existing `rules` table before cutover and decide whether to publish a read-only archive (CSV/JSON) somewhere for anyone looking for their old work. - **No chatbot.** ## How the cutover will work @@ -43,30 +32,22 @@ Side-by-side, the legacy app keeps running untouched until the new one is verified. 1. **Staging phase.** New app installed at - `staging.communityrule.info` (auto-provisioned by Cloudron). Legacy - app at the apex is not touched. Quiet testing within MEDLab/stakeholders. -2. **Cutover phase.** When staging is green and we're ready, schedule - a low-traffic window. During the window (roughly 5–15 minutes of - apex downtime): + `staging.communityrule.info` (auto-provisioned by Cloudron). Legacy app at the apex is not touched. Quiet testing within MEDLab/stakeholders. +2. **Cutover phase.** When staging is green and we're ready, schedule a low-traffic window. During the window (roughly 5–15 minutes of apex downtime): - Take a final backup of the legacy app (Cloudron one-click). - - Pull a copy of the legacy `rules` table if we decided to publish - an archive. + - Pull a copy of the legacy `rules` table if we decided to publish an archive. - Uninstall the legacy app at the apex `communityrule.info`. - Move the new app to the apex. - Smoke-test, confirm backups are on, done. -3. **Post-cutover.** Legacy backup retained ≥ 90 days as a safety net. - Legacy source repos get README pointers to the new app and are archived. +3. **Post-cutover.** Legacy backup retained ≥ 90 days as a safety net. Legacy source repos get README pointers to the new app and are archived. -Rollback plan during the window: restore the legacy backup to a scratch -Cloudron slot and point DNS back. Realistic only if we discover -something genuinely broken in the first few minutes. +Rollback plan during the window: restore the legacy backup to a scratch Cloudron slot and point DNS back. Realistic only if we discover something genuinely broken in the first few minutes. ## Rough timeline Roughly this order: -1. **Code prep** — small local change so the app reads Cloudron's - injected `CLOUDRON_*` env vars natively. No infra impact. +1. **Code prep** — small local change so the app reads Cloudron's injected `CLOUDRON_*` env vars natively. No infra impact. 2. **Build and push the app image** to a container registry. 3. **Install at staging** subdomain, smoke test, soft launch. 4. **Apex cutover window** — the brief downtime above.