wiki/.claude/skills/help.md

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?