# Core Development Guidelines Skill

Deep reflection and problem-solving methodology for full-stack Convex development.

## 1. Reflect deeply before acting

Before implementing any solution, follow this process:

1. **Reflect** - Carefully consider why the current implementation may not be working
2. **Identify** - What's missing, incomplete, or incorrect based on the request
3. **Theorize** - Different possible sources of the problem or areas requiring updates
4. **Distill** - Narrow down to 1-2 most probable root causes or solutions
5. **Proceed** - Only move forward after clear understanding

**Never assume.** If anything is unclear, ask questions and clarify.

## 2. Convex implementation guidelines

### Core principles

**Direct mutation pattern:**
- Use direct mutation calls with plain objects
- Create dedicated mutation functions that map form fields to database fields
- Form field names should exactly match database field names when applicable

**Best practices:**
- Patch directly without reading first
- Use indexed queries for ownership checks (not `ctx.db.get()`)
- Make mutations idempotent with early returns
- Use timestamp-based ordering for new items
- Use `Promise.all()` for parallel independent operations to avoid write conflicts

### Essential documentation

**Functions:**
- Mutations: https://docs.convex.dev/functions/mutation-functions
- Queries: https://docs.convex.dev/functions/query-functions
- Validation: https://docs.convex.dev/functions/validation
- General: https://docs.convex.dev/functions

**Core concepts:**
- Zen of Convex: https://docs.convex.dev/understanding/zen
- TypeScript best practices: https://docs.convex.dev/understanding/best-practices/typescript
- Best practices: https://docs.convex.dev/understanding/best-practices/
- Schema validation: https://docs.convex.dev/database/schemas

**Authentication:**
- WorkOS AuthKit: https://workos.com/docs/authkit/vanilla/nodejs
- WorkOS docs: https://workos.com/docs
- Convex + WorkOS setup: https://docs.convex.dev/auth/authkit/

## 3. Change scope and restrictions

### What to update

- Update Convex schema if needed
- Only update files directly necessary to fix the original request
- When tasks touch changelog.md, changelog page, or files.md:
  - Run `git log --date=short` to check commit history
  - Set release dates to match real commit timeline
  - No placeholders or future months

### What NOT to change

- Do not change UI, layout, design, or color styles unless specifically instructed
- Preserve all admin dashboard sections and frontend components unless explicitly told to update
- Never remove sections, features, or components unless directly requested

## 4. UI/UX guidelines

### Design system compliance

**For pop-ups, alerts, modals, warnings, notifications, and confirmations:**
- Always follow the site's existing design system
- Never use browser default pop-ups
- Use site design system components only

### Follow Vercel guidelines

https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/refs/heads/main/AGENTS.md

## 5. Documentation policy

**IMPORTANT:** Do NOT create documentation files unless explicitly instructed.

**Banned unless requested:**
- README.md
- CONTRIBUTING.md
- SUMMARY.md
- USAGE_GUIDELINES.md

You may include a brief summary in responses, but don't create separate documentation files.

**Formatting rules:**
- Never use emojis in readme or app unless instructed

## 6. Code confidence requirement

**98% confidence rule:**

Don't write any code until you're very confident (98% or more) in what needs to be done.

If unclear, ask for more information.

## 7. Git safety

Follow all rules in `.claude/skills/gitrules.md`:

- Never use `git checkout` to revert changes without examining what will be destroyed
- Always use `git diff <file>` before any destructive operation
- Never run `git reset --hard`, `git checkout -- .`, `git clean -fd`, or `git stash drop` without explicit user approval
- Always run `git status` first to check for uncommitted changes
- When user asks to "undo" changes, manually edit files to revert specific sections instead of using checkout

## Quick reference checklist

Before writing code:
- [ ] Have I reflected on the root cause?
- [ ] Do I understand what's actually broken?
- [ ] Am I 98% confident in the solution?
- [ ] Am I only changing files that need to change?
- [ ] Am I preserving existing UI/features not mentioned?
- [ ] Am I using the site's design system (not browser defaults)?
- [ ] Am I following Convex mutation best practices?
- [ ] Have I checked the relevant docs?

When uncertain:
- [ ] Ask clarifying questions
- [ ] Don't assume
- [ ] Reference documentation
- [ ] Narrow down to 1-2 most likely solutions

Before git operations:
- [ ] Have I run `git status` first?
- [ ] Am I about to run a destructive command?
- [ ] Have I shown the user what will be affected?
- [ ] Do I have explicit user approval for destructive operations?
- [ ] Am I following `.claude/skills/gitrules.md`?