Related Skills:

• kavak-documentation

  - USE FIRST for Kavak-specific patterns, kbroker, STS, GitLab CI, Docker templates

• test-driven-development

  - USE PROACTIVELY for new features and bug fixes (Red-Green-Refactor)
• Check

  .claude/CLAUDE.md

  or

  .cursor/rules/*

  for project-specific conventions

MCP: Use

kavak-platform/plati_query

tool to query Kavak internal documentation before implementing.

• Bugs that need fixing in multiple places
• Inconsistent behavior across the codebase
• Maintenance nightmare for humans

1. VERBS - What actions? (create, save, send, process, calculate, update, delete, etc.)
2. NOUNS - What domain concepts? (the entities mentioned in your task)
3. OUTPUT - What type of result? (Model, Response, Event, etc.)

undefined

• You create a new file >100 lines without documenting reuse analysis
• You duplicate >50% of logic from an existing file
• You copy-paste code instead of calling existing functions
• You create a new method that does the same thing as an existing one

references/architecture.md

• SOLID - Single Responsibility, Open/Closed, Liskov, Interface Segregation, Dependency Inversion
• DRY - Don't Repeat Yourself (extract reusable code) →

  references/dry-detection.md

• YAGNI - You Aren't Gonna Need It (don't build unused features)
• KISS - Keep It Simple, Stupid (simplest solution that works)

• Logic is complex/non-obvious (explain "why", not "what")
• Workarounds or edge cases need context
• Public API documentation (JSDoc/GoDoc)

// ❌ BAD: Obvious comment
const age = user.age; // Get user age

// ✅ GOOD: Explains WHY
// Add 1 day buffer for timezone edge cases in billing cycle
const billingDate = addDays(cycleEnd, 1);

references/code-quality.md

1. Read first - Explore the codebase before making changes
2. Follow existing patterns - If project uses a pattern, continue using it
3. Don't force architecture - Don't refactor to Clean Architecture unless asked
4. Incremental improvement - Apply good practices to NEW code you write
5. Ask if unclear - When patterns conflict, ask the user

Existing project has flat structure? → Keep flat structure
Existing project has no interfaces? → Don't add interfaces everywhere
Existing project uses callbacks? → Use callbacks (unless migrating)

• New greenfield projects
• New modules/features in existing projects (when it fits)
• When explicitly asked to refactor

Note: Use kbroker for events between services. Use pg-boss (Node) or River (Go) for job queues.

Use

test-driven-development

skill for Red-Green-Refactor cycle

1. Write failing test first →

   test-driven-development

   skill
2. Design endpoint →

   references/api-design.md

3. Set up handler →

   references/go/http-handlers.md

   or

   references/node/frameworks.md

4. Add database access →

   references/go/database.md

   or

   references/node/database.md

5. Implement auth →

   references/authentication.md

6. Refactor with tests passing →

   references/code-quality.md

CRITICAL: When task says "do X like Y" or "add similar to existing"

1. Find existing implementation first - search for the feature mentioned in the task
2. Analyze similarity → Is >50% of logic the same?
3. If similar, REUSE or EXTRACT:
   • >70% similar: Inject existing service, call its method
   • 50-70% similar: Extract shared helper, refactor existing to use it
   • <50% similar: OK to create new, but keep it small
4. New code should be <50 lines - if more, you probably missed reuse opportunity
5. Test both old and new paths → Ensure refactoring didn't break existing

1. Profile query →

   references/debugging.md

   (EXPLAIN ANALYZE)
2. Add indexes →

   references/performance.md

3. Add caching →

   references/go/redis-queues.md

   or

   references/node/database.md

1. Write Dockerfile →

   references/devops/docker.md

2. Set up CI/CD →

   references/devops/ci-cd.md

1. Check logs/traces →

   references/debugging.md

2. Profile if slow →

   references/debugging.md

   (pprof/clinic.js)
3. Check DB queries →

   references/debugging.md

   (pg_stat_statements)