help

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.

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