RequestDesk Feature Planner Skill

🚨 CRITICAL RULES - READ FIRST 🚨

1. NEVER Directly Modify the Database

ALL database changes MUST go through migrations. NO EXCEPTIONS.

This has caused 5+ hour debugging sessions when:

• •Claude added data directly to local MongoDB
• •Production failed because data didn't exist
• •Nobody documented what was added

If a feature needs data:

1. •Create a migration file in backend/app/migrations/versions/
2. •Migration runs on ALL environments automatically
3. •Document what data is being added

See architecture/database.md for full details.

2. NO Collection Without a Model

ALWAYS create Pydantic models before/alongside collections.

Every collection needs:

• •{Feature}Create - Input validation
• •{Feature}Update - Partial updates
• •{Feature}Response - API output

See architecture/database.md for full pattern.

3. NO MUI Components

All new UI must use Tailwind CSS + Catalyst UI Kit. See architecture/frontend.md.

4. Use Service Layer Pattern

Business logic goes in services, not routers. See architecture/backend.md.

5. NO Large Files - Use Modular Structure

Files should be < 300 lines. NEVER keep adding to existing files.

When a router/service grows, split it into a modular directory:

routers/v2/tickets/           # CORRECT - modular structure
├── __init__.py               # 69 lines - just imports & composition
├── core/
│   ├── create.py             # 396 lines
│   ├── read.py               # 536 lines
│   ├── update.py             # 342 lines
│   └── delete.py             # 115 lines
├── features/
│   ├── assignment.py         # 298 lines
│   ├── followers.py          # 285 lines
│   └── archive.py            # 192 lines
├── notifications/
│   └── status_notifications.py
└── utils/
    ├── validators.py
    ├── permissions.py
    └── helpers.py

vs WRONG approach (current problem files):

• •llm.py - 2,447 lines ❌
• •config.py - 2,217 lines ❌
• •brand_personas.py - 2,138 lines ❌

When adding new functionality:

1. •Check file size first - if > 300 lines, create modular structure
2. •New features go in features/ subdirectory
3. •Shared logic goes in utils/
4. •Main __init__.py only does router composition

See architecture/backend.md for full modular router pattern.

6. Read Guidelines Before Implementing

ALWAYS read these documents in cb-requestdesk/todo/ before starting any work:

CB Architecture Flow (memorize this):

Frontend → DataLayer → Router → Service Layer → Model → Collection

Purpose

Help plan features and enhancements for RequestDesk.ai by understanding the existing architecture, identifying reusable components, and generating implementation specs that Claude Code can execute.

When to Use This Skill

• •Planning new features before implementation
• •Designing enhancements to existing functionality
• •Understanding how a feature fits into the existing architecture
• •Generating specs for handoff to Claude Code

Planning Workflow

Step 1: Understand the Request

Ask clarifying questions:

• •What problem does this solve for users?
• •Who are the target users (admin, content manager, writer, client)?
• •What's the expected user workflow?
• •Are there similar features we can reference?

Step 2: Architecture Analysis

Reference the architecture docs to determine:

• •Which layers are affected (Frontend, Backend, Database)
• •Which existing services/components can be reused
• •What new endpoints/models are needed
• •Database schema changes required

Step 3: Check Feature Registry

Look for:

• •Similar existing features to reference
• •Reusable components and patterns
• •Potential conflicts or dependencies
• •Integration points

Step 4: Generate Spec

Use the templates/feature-spec.md template to create:

• •Clear requirements and acceptance criteria
• •Technical implementation plan
• •File-by-file changes needed
• •Testing strategy

Architecture Reference

Output Format

Always generate specs in this format for Claude Code:

## Feature: [Name]

### Requirements
- [ ] Requirement 1
- [ ] Requirement 2

### Acceptance Criteria
- [ ] AC 1
- [ ] AC 2

### Implementation Plan
1. Backend changes
2. Frontend changes
3. Database changes

### Files to Modify
- `path/to/file.py` - Description of changes
- `path/to/component.tsx` - Description of changes

### Testing
- Manual test steps
- Edge cases to verify

Key Principles

1. •Use Existing Patterns - Don't reinvent; follow established conventions
2. •Service Layer First - Business logic in services, not routers
3. •Company Isolation - All data filtered by company_id
4. •Role-Based Access - Check user roles for permissions
5. •No Hardcoding - Use database-driven configuration
6. •Docker Development - All testing in containers

Handoff to Claude Code

When spec is complete, user should:

1. •Save spec to todo/current/[category]/[feature-name]/
2. •Run /create-branch cb-requestdesk [spec-path]
3. •Claude Code will implement based on the spec