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:
- Reflect: Carefully consider why the current implementation may not be working
- Identify: What's missing, incomplete, or incorrect based on the request
- Theorize: Different possible sources of the problem or areas requiring updates
- Distill: Narrow down to 1-2 most probable root causes or solutions
- 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=shortto check commit history - Set release dates to match real commit timeline
- No placeholders or future months
- Run
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.
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
