@lenne.tech/cli 1.0.1 → 1.0.2

package/build/templates/claude-skills/building-stories-with-tdd/workflow.md

@@ -0,0 +1,1004 @@
+---
+name: story-tdd-workflow
+version: 1.0.0
+description: Complete 7-step TDD workflow with detailed implementation steps, testing guidelines, and validation process
+---
+
+# Story-Based TDD Workflow - The Seven Steps
+
+## Table of Contents
+- [Step 1: Story Analysis & Validation](#step-1-story-analysis--validation)
+- [Step 2: Create Story Test](#step-2-create-story-test)
+- [Step 3: Run Tests & Analyze Failures](#step-3-run-tests--analyze-failures)
+- [Step 3a: Fix Test Errors (if needed)](#step-3a-fix-test-errors-if-needed)
+- [Step 4: Implement/Extend API Code](#step-4-implementextend-api-code)
+- [Step 5: Validate & Iterate](#step-5-validate--iterate)
+- [Step 5a: Code Quality & Refactoring Check](#step-5a-code-quality--refactoring-check)
+- [Step 5b: Final Validation](#step-5b-final-validation)
+
+This skill follows a rigorous 7-step iterative process (with Steps 5, 5a, 5b for final validation and refactoring):
+
+## Step 1: Story Analysis & Validation
+
+**Before writing ANY code or tests:**
+
+1. **Read and analyze the complete user story/requirement**
+   - Identify all functional requirements
+   - List all acceptance criteria
+   - Note any technical constraints
+
+2. **🔍 VERIFY existing API structure - NEVER assume!**
+   - **Read actual Controller files** to verify endpoints exist:
+     - Check HTTP methods (GET, POST, PUT, DELETE)
+     - Verify exact endpoint paths (e.g., `/api/users` vs `/users`)
+     - Confirm request/response structures
+   - **Read actual Resolver files** for GraphQL:
+     - Verify mutation/query names exist
+     - Check input types and field names
+     - Confirm return types
+   - **Read existing test files** to understand patterns:
+     - How are endpoints called in practice?
+     - What authentication is used?
+     - What response structure is expected?
+   - **Document what EXISTS vs what NEEDS to be created:**
+     - Existing: `/api/products` GET, POST (verified in product.controller.ts:45)
+     - Missing: `/api/products/:id/reviews` POST (needs implementation)
+
+3. **Identify contradictions or ambiguities**
+   - Look for conflicting requirements
+   - Check for unclear specifications
+   - Verify if requirements match existing architecture
+   - **Verify assumed endpoints actually exist!**
+
+4. **Ask developer for clarification IMMEDIATELY if needed**
+   - Don't assume or guess requirements
+   - Don't assume endpoints exist without verification
+   - Clarify contradictions BEFORE writing tests
+   - Get confirmation on architectural decisions
+   - Verify security/permission requirements
+
+**⚠️ CRITICAL:** If you find ANY contradictions or ambiguities, STOP and use AskUserQuestion to clarify BEFORE proceeding to Step 2.
+
+**⚠️ CRITICAL:** If you assume an endpoint exists but didn't verify it in the code, you are doing it WRONG! Always read the actual controller/resolver files first.
+
+**Step 1 Checklist:**
+- [ ] Story completely read and understood
+- [ ] All functional requirements identified
+- [ ] All acceptance criteria listed
+- [ ] Existing API structure verified (Controllers/Resolvers read)
+- [ ] Documented what EXISTS vs what NEEDS creation
+- [ ] No contradictions or ambiguities (or clarified with developer)
+- [ ] Ready for Step 2
+
+## Step 2: Create Story Test
+
+**🔍 BEFORE Creating New Tests - Check Existing Tests First!**
+
+**CRITICAL:** Before writing ANY new test, verify that the functionality isn't already tested!
+
+1. **Search existing tests** in `tests/` directory:
+   - Look for tests covering the same endpoints/mutations
+   - Check if existing tests already validate the behavior
+   - Identify tests that might need updates due to story changes
+
+2. **If functionality is already tested:**
+   - ✅ **DO NOT** create duplicate tests
+   - ✅ **Extend** existing tests if new edge cases are needed
+   - ✅ **Update** existing tests if the story changes expected behavior
+
+3. **If story changes require modifying existing tests:**
+   - ⚠️ **ALWAYS inform the user** about which tests will be modified and why
+   - ⚠️ **Only modify tests** when story requirements explicitly change the expected behavior
+   - ❌ **NEVER modify tests just because they fail** - failing tests indicate bugs in implementation!
+
+**🚨 CRITICAL RULE: Tests Protect Against Unintended Side Effects!**
+
+```
+Test fails after your changes?
+    │
+    ├─► Does the story EXPLICITLY require this behavior change?
+    │   │
+    │   ├─► YES (documented in story requirements):
+    │   │   └─► ✅ Update the test AND inform the user:
+    │   │       "Updating test X because story requires behavior Y"
+    │   │
+    │   └─► NO (not mentioned in story):
+    │       └─► ❌ DO NOT modify the test!
+    │           └─► Fix your implementation instead
+    │               (you introduced an unintended side effect)
+```
+
+**Example - WRONG approach:**
+```typescript
+// Test fails: "expected status 200, got 401"
+// ❌ WRONG: Just change the expected status
+expect(response.status).toBe(401); // Changed from 200 to make test pass
+```
+
+**Example - CORRECT approach:**
+```typescript
+// Test fails: "expected status 200, got 401"
+// ✅ CORRECT: Investigate WHY it fails
+// → Found: Missing authentication token in new implementation
+// → Fix: Add proper authentication, keep test expecting 200
+```
+
+**When to inform user about test changes:**
+- "Modifying `user-registration.story.test.ts` - story now requires email verification before login"
+- "Updating expected response in `product-search.test.ts` - story adds new `category` field to response"
+- "Adjusting test data in `order-processing.test.ts` - story changes minimum order amount from 10 to 20"
+
+**📖 For detailed guidance on handling failing tests, see: `handling-existing-tests.md`**
+
+---
+
+**🚨 CRITICAL: ALWAYS TEST THROUGH API - NEVER DIRECT SERVICE/DB ACCESS! 🚨**
+
+**FUNDAMENTAL RULE - Read This First:**
+
+Tests MUST go through REST/GraphQL interfaces (Controller/Resolver) using TestHelper. Direct Service or Database access in test logic makes tests WORTHLESS because they bypass the actual API layer that users interact with.
+
+**✅ ALWAYS DO:**
+- ✅ Test via REST endpoints: `testHelper.rest('/api/users', { method: 'POST', ... })`
+- ✅ Test via GraphQL: `testHelper.graphQl('mutation { createUser(...) }', { ... })`
+- ✅ Use TestHelper for ALL functional testing
+- ✅ Test the complete chain: Controller/Resolver → Guards → Service → Database
+
+**❌ NEVER DO:**
+- ❌ Direct Service calls: `userService.create()` - bypasses authentication!
+- ❌ Direct DB queries in tests: `db.collection('users').findOne()` - bypasses business logic!
+- ❌ Service instantiation: `new UserService()` - bypasses dependency injection!
+- ❌ Mocking Controllers or Resolvers - defeats the purpose!
+
+**Why This Rule Is Absolute:**
+- **Security:** Direct Service access bypasses authentication, authorization, guards, decorators
+- **Reality:** Tests must verify what actual users experience through the API
+- **Business Logic:** Services might have additional validation that gets bypassed
+- **Worthless Tests:** Tests that bypass the API cannot catch real bugs
+
+**🔓 RARE Exceptions - Only for Test Setup/Cleanup (NOT for testing functionality):**
+
+Direct database access is ONLY allowed in these specific cases:
+
+**✅ Allowed in beforeAll/beforeEach/afterAll/afterEach:**
+- Setting user roles: `await db.collection('users').updateOne({ _id: userId }, { $set: { roles: ['admin'] } })`
+- Setting verified status: `await db.collection('users').updateOne({ _id: userId }, { $set: { verified: true } })`
+- Cleanup: `await db.collection('products').deleteMany({ createdBy: testUserId })`
+- Read-only verification when NO API endpoint exists: `const count = await db.collection('logs').countDocuments()`
+
+**⚠️ Ask Yourself First:**
+Before using direct DB/Service access, ask:
+1. Can I do this via an API endpoint? → If YES, use the API!
+2. Am I testing functionality? → If YES, MUST use API!
+3. Is this just setup/cleanup? → Only then consider direct access
+4. Am I setting roles/verified status? → Allowed exception
+5. Am I reading data that has NO API endpoint? → Allowed, but prefer API
+
+**❌ Still NEVER Allowed - Even in Setup:**
+- ❌ Testing functionality via Services
+- ❌ Creating test data via Services when API exists
+- ❌ Verifying results via DB when API query exists
+- ❌ Writing to DB for anything other than roles/verified/cleanup
+
+**Example of correct usage:**
+
+```typescript
+describe('User Registration Story', () => {
+  let testHelper: TestHelper;
+  let db: Db;
+  let createdUserId: string;
+
+  beforeAll(async () => {
+    testHelper = new TestHelper(app);
+    db = app.get<Connection>(getConnectionToken()).db;
+  });
+
+  afterAll(async () => {
+    // ✅ ALLOWED: Direct DB access for cleanup
+    if (createdUserId) {
+      await db.collection('users').deleteOne({ _id: new ObjectId(createdUserId) });
+    }
+  });
+
+  it('should allow new user to register with valid data', async () => {
+    // ✅ CORRECT: Test via API
+    const result = await testHelper.rest('/auth/signup', {
+      method: 'POST',
+      payload: {
+        email: 'newuser@test.com',
+        password: 'SecurePass123!',
+        firstName: 'John',
+        lastName: 'Doe'
+      },
+      statusCode: 201
+    });
+
+    expect(result.id).toBeDefined();
+    expect(result.email).toBe('newuser@test.com');
+    createdUserId = result.id;
+
+    // ✅ ALLOWED: Set verified flag for subsequent tests
+    await db.collection('users').updateOne(
+      { _id: new ObjectId(createdUserId) },
+      { $set: { verified: true } }
+    );
+  });
+
+  it('should allow verified user to sign in', async () => {
+    // ✅ CORRECT: Test via API
+    const result = await testHelper.rest('/auth/signin', {
+      method: 'POST',
+      payload: {
+        email: 'newuser@test.com',
+        password: 'SecurePass123!'
+      },
+      statusCode: 201
+    });
+
+    expect(result.token).toBeDefined();
+    expect(result.user.email).toBe('newuser@test.com');
+
+    // ❌ WRONG: Don't verify via direct DB access
+    // const dbUser = await db.collection('users').findOne({ email: 'newuser@test.com' });
+
+    // ✅ CORRECT: Verify via API
+    const profile = await testHelper.rest('/api/users/me', {
+      method: 'GET',
+      token: result.token,
+      statusCode: 200
+    });
+    expect(profile.email).toBe('newuser@test.com');
+  });
+});
+```
+
+---
+
+**🔍 BEFORE Writing Any Tests - Study the TestHelper:**
+
+**CRITICAL: Read the TestHelper source file to understand all available features!**
+
+```
+node_modules/@lenne.tech/nest-server/src/test/test.helper.ts
+```
+
+This file documents ALL TestHelper capabilities:
+- `rest()` and `graphQl()` methods with all options
+- File uploads via `attachments` option
+- Debugging with `log` and `logError` options in `TestRestOptions`
+- Custom headers, status code validation
+- Authentication token handling
+
+**Study this file BEFORE writing tests** to avoid reinventing functionality that already exists!
+
+---
+
+**Location:** `tests/stories/` directory (create if it doesn't exist)
+
+**Directory Creation:**
+If the `tests/stories/` directory doesn't exist yet, create it first:
+```bash
+mkdir -p tests/stories
+```
+
+**Naming Convention:** `{feature-name}.story.test.ts`
+- Example: `user-registration.story.test.ts`
+- Example: `product-search.story.test.ts`
+- Example: `order-processing.story.test.ts`
+
+**📁 File Organization - Avoid Too Many Files:**
+
+**IMPORTANT:** Before creating a NEW test file, check if existing test files can be extended!
+
+Story tests typically require significant setup (TestHelper, database connections, test users, etc.), so files naturally grow larger. A typical story test file ranges from 400-800 lines, with complex features reaching 1000+ lines.
+
+**✅ PREFER extending existing files when:**
+- The new tests relate to the same feature/module
+- The existing file is not excessively large (< 1000 lines)
+- The tests share similar setup/teardown logic
+- It makes logical sense to group them together
+
+**✅ CREATE new files when:**
+- Testing a completely different feature/module
+- The existing file would exceed ~1000-1200 lines
+- The tests require significantly different setup
+- It improves clarity and maintainability
+
+**Example:**
+```
+tests/stories/
+  user-authentication.story.test.ts    # Login, logout, password reset, session handling
+  user-profile.story.test.ts           # Profile CRUD, settings, preferences
+  product-management.story.test.ts     # Product CRUD, variants, pricing
+  order-processing.story.test.ts       # Cart, checkout, payment, fulfillment
+```
+
+**Why this matters:**
+- Too many small files → Hard to navigate, duplicate setup code, redundant boilerplate
+- Too few large files → Hard to read, slow to run, merge conflicts
+- Balance: Group related tests, split when files grow beyond ~1000 lines
+
+**🔍 BEFORE Writing Tests - Verify Your Assumptions:**
+
+**CRITICAL: Only write tests for endpoints that you have VERIFIED exist in the code!**
+
+1. **For REST endpoints:**
+   ```typescript
+   // ✅ CORRECT: Verified endpoint exists in user.controller.ts
+   await testHelper.rest('/api/users', { method: 'POST', ... });
+
+   // ❌ WRONG: Assumed endpoint without verification
+   await testHelper.rest('/api/users/profile', { method: 'PUT', ... });  // Does this exist?
+   ```
+
+2. **For GraphQL mutations/queries:**
+   ```typescript
+   // ✅ CORRECT: Verified 'createUser' mutation exists in user.resolver.ts
+   await testHelper.graphQl({ name: 'createUser', type: TestGraphQLType.MUTATION, ... });
+
+   // ❌ WRONG: Assumed mutation without verification
+   await testHelper.graphQl({ name: 'updateUserProfile', ... });  // Does this exist?
+   ```
+
+3. **Document your verification:**
+   ```typescript
+   // Test for user creation
+   // Verified: POST /api/users exists in src/server/modules/user/user.controller.ts:34
+   // Verified: Requires authentication (S_USER role)
+   // Verified: Returns User object with id, email, firstName, lastName
+   it('should create new user', async () => {
+     const result = await testHelper.rest('/api/users', {
+       method: 'POST',
+       payload: { email: 'test@example.com', ... },
+       token: adminToken,
+       statusCode: 201
+     });
+     // ...
+   });
+   ```
+
+**Test Structure:**
+
+1. **Study existing story tests** (if any exist in `tests/stories/`)
+   - Follow established patterns and conventions
+   - Use similar setup/teardown approaches
+   - Match coding style and organization
+
+2. **Study other test files** for patterns:
+   - Check `test/**/*.test.ts` files
+   - Understand authentication setup
+   - Learn data creation patterns
+   - See how API calls are made
+
+3. **Write comprehensive story test** that includes:
+   - Clear test description matching the story
+   - Setup of test data and users
+   - All acceptance criteria as test cases
+   - Proper authentication/authorization
+   - Validation of responses and side effects
+   - Cleanup/teardown
+
+4. **Ensure tests cover:**
+   - Happy path scenarios
+   - Edge cases
+   - Error conditions
+   - Security/permission checks
+   - Data validation
+
+**Example test structure:**
+```typescript
+describe('User Registration Story', () => {
+  let createdUserIds: string[] = [];
+  let createdProductIds: string[] = [];
+
+  // Setup
+  beforeAll(async () => {
+    // Initialize test environment
+  });
+
+  afterAll(async () => {
+    // 🧹 CLEANUP: Delete ALL test data created during tests
+    // This prevents side effects on subsequent test runs
+    if (createdUserIds.length > 0) {
+      await db.collection('users').deleteMany({
+        _id: { $in: createdUserIds.map(id => new ObjectId(id)) }
+      });
+    }
+    if (createdProductIds.length > 0) {
+      await db.collection('products').deleteMany({
+        _id: { $in: createdProductIds.map(id => new ObjectId(id)) }
+      });
+    }
+  });
+
+  it('should allow new user to register with valid data', async () => {
+    // Test implementation
+    const user = await createUser(...);
+    createdUserIds.push(user.id); // Track for cleanup
+  });
+
+  it('should reject registration with invalid email', async () => {
+    // Test implementation
+  });
+
+  it('should prevent duplicate email registration', async () => {
+    // Test implementation
+  });
+});
+```
+
+**🚨 CRITICAL: Test Data Management for Parallel Execution**
+
+**ALWAYS follow these rules to ensure tests can run in parallel safely!**
+
+Tests run in parallel, so improper test data management causes:
+- Conflicts between parallel tests (duplicate keys, race conditions)
+- False positives/negatives in tests
+- Flaky tests that pass/fail randomly
+- Contaminated test database
+- Hard-to-debug test failures
+
+**📋 GOLDEN RULES for Test Data:**
+
+1. **Email Addresses Must End with @test.com**
+   ```typescript
+   // ✅ CORRECT: Will be excluded from external services (e2e.brevo.exclude)
+   // Includes timestamp + random suffix for uniqueness even within same millisecond
+   const testEmail = `user-${Date.now()}-${Math.random().toString(36).substring(2, 8)}@test.com`;
+
+   // ⚠️ LESS SAFE: Only timestamp (collision risk if tests run in same millisecond)
+   const testEmail = `user-${Date.now()}@test.com`;
+
+   // ❌ WRONG: Won't be excluded, may trigger external emails
+   const testEmail = 'testuser@example.com';
+   ```
+
+   **Why:** Configuration in `src/config.env.ts` uses `e2e.brevo.exclude` to filter out @test.com emails from external services. The random suffix ensures uniqueness even when multiple tests run simultaneously.
+
+2. **NEVER Reuse Same Data Across Test Files**
+   ```typescript
+   // ❌ WRONG: user-story-1.test.ts and user-story-2.test.ts both use:
+   const email = 'admin@test.com';  // ❌ Conflict when running in parallel!
+
+   // ✅ CORRECT: Make data unique per test file with timestamp + random suffix
+   const email = `admin-user-story-1-${Date.now()}-${Math.random().toString(36).substring(2, 8)}@test.com`;
+
+   // ⚠️ LESS SAFE: Only timestamp
+   const email = `admin-user-story-1-${Date.now()}@test.com`;
+   ```
+
+   **Why:** Tests run in parallel. Same email = duplicate key errors and race conditions. Random suffix prevents collisions within same millisecond.
+
+3. **ONLY Delete What You Created in This Test File**
+   ```typescript
+   // ❌ WRONG: Deletes ALL test users (affects parallel tests)
+   await db.collection('users').deleteMany({ email: /@test\.com$/ });
+
+   // ✅ CORRECT: Only delete tracked entities from THIS test
+   if (createdUserIds.length > 0) {
+     await db.collection('users').deleteMany({
+       _id: { $in: createdUserIds.map(id => new ObjectId(id)) }
+     });
+   }
+   ```
+
+   **Why:** Deleting too much breaks parallel tests that are still running.
+
+4. **ALL Created Entities Must Be Cleaned Up**
+   ```typescript
+   // ✅ Track EVERY entity created
+   let createdUserIds: string[] = [];
+   let createdProductIds: string[] = [];
+   let createdOrderIds: string[] = [];
+
+   // ✅ Clean up ALL in afterAll
+   afterAll(async () => {
+     if (createdOrderIds.length > 0) {
+       await db.collection('orders').deleteMany({
+         _id: { $in: createdOrderIds.map(id => new ObjectId(id)) }
+       });
+     }
+     // ... clean up products, users, etc.
+   });
+   ```
+
+   **Why:** Leftover data causes side effects in future test runs.
+
+5. **NEVER Use Fixed Port Numbers**
+   ```typescript
+   // ❌ WRONG: Fixed port causes conflicts in parallel tests
+   await app.listen(3000);
+   const response = await fetch('http://localhost:3000/api/users');
+
+   // ✅ CORRECT: NestJS assigns random ports automatically
+   await app.init();  // No port specified
+   // Use TestHelper - it handles ports automatically
+   const result = await testHelper.rest('/api/users', { ... });
+   ```
+
+   **Why:** Parallel tests need different ports. NestJS assigns random available ports automatically. TestHelper abstracts this away.
+
+**Cleanup Strategy:**
+
+1. **Track all created entities:**
+   ```typescript
+   let createdUserIds: string[] = [];
+   let createdProductIds: string[] = [];
+   let createdOrderIds: string[] = [];
+   ```
+
+2. **Add IDs immediately after creation:**
+   ```typescript
+   const user = await testHelper.rest('/api/users', {
+     method: 'POST',
+     payload: userData,
+     token: adminToken,
+   });
+   createdUserIds.push(user.id); // ✅ Track for cleanup
+   ```
+
+3. **Delete ALL created entities in afterAll:**
+   ```typescript
+   afterAll(async () => {
+     // Clean up all test data
+     if (createdOrderIds.length > 0) {
+       await db.collection('orders').deleteMany({
+         _id: { $in: createdOrderIds.map(id => new ObjectId(id)) }
+       });
+     }
+     if (createdProductIds.length > 0) {
+       await db.collection('products').deleteMany({
+         _id: { $in: createdProductIds.map(id => new ObjectId(id)) }
+       });
+     }
+     if (createdUserIds.length > 0) {
+       await db.collection('users').deleteMany({
+         _id: { $in: createdUserIds.map(id => new ObjectId(id)) }
+       });
+     }
+
+     await connection.close();
+     await app.close();
+   });
+   ```
+
+4. **Clean up in correct order:**
+   - Delete child entities first (e.g., Orders before Products)
+   - Delete parent entities last (e.g., Users last)
+   - Consider foreign key relationships
+
+5. **Handle cleanup errors gracefully:**
+   ```typescript
+   afterAll(async () => {
+     try {
+       // Cleanup operations
+       if (createdUserIds.length > 0) {
+         await db.collection('users').deleteMany({
+           _id: { $in: createdUserIds.map(id => new ObjectId(id)) }
+         });
+       }
+     } catch (error) {
+       console.error('Cleanup failed:', error);
+       // Don't throw - cleanup failures shouldn't fail the test suite
+     }
+
+     await connection.close();
+     await app.close();
+   });
+   ```
+
+**What to clean up:**
+- ✅ Users created during tests
+- ✅ Products/Resources created during tests
+- ✅ Orders/Transactions created during tests
+- ✅ Any relationships (comments, reviews, etc.)
+- ✅ Files uploaded during tests
+- ✅ Any other test data that persists
+
+**What NOT to clean up:**
+- ❌ Global test users created in `beforeAll` that are reused (clean these once at the end)
+- ❌ Database connections (close these separately)
+- ❌ The app instance (close this separately)
+
+**Step 2 Checklist:**
+- [ ] Test file created in tests/stories/
+- [ ] Endpoints verified before writing tests
+- [ ] ALL tests use TestHelper (rest() or graphQl())
+- [ ] NO direct Service or DB access in test logic
+- [ ] Existing test patterns studied and followed
+- [ ] All acceptance criteria covered
+- [ ] Cleanup implemented in afterAll
+- [ ] All test entities tracked for cleanup
+- [ ] Ready for Step 3
+
+## Step 3: Run Tests & Analyze Failures
+
+**Execute all tests:**
+```bash
+npm test
+```
+
+**Or run specific story test:**
+```bash
+npm test -- tests/stories/your-story.story.test.ts
+```
+
+**Analyze results:**
+1. Record which tests fail and why
+2. Identify if failures are due to:
+   - Missing implementation (expected)
+   - Test errors/bugs (needs fixing)
+   - Misunderstood requirements (needs clarification)
+
+**Decision point:**
+- If test has bugs/errors → Go to Step 3a
+- If API implementation is missing/incomplete → Go to Step 4
+
+**Debugging Test Failures:**
+
+If test failures are unclear, enable debugging tools:
+- **TestHelper:** Add `log: true, logError: true` to test options for detailed output
+- **Server logging:** Set `logExceptions: true` in `src/config.env.ts`
+- **Validation debugging:** Set `DEBUG_VALIDATION=true` environment variable
+
+See **reference.md** for detailed debugging instructions and examples.
+
+## Step 3a: Fix Test Errors (if needed)
+
+**Only fix tests if:**
+- Test logic is incorrect
+- Test has programming errors
+- Test makes nonsensical demands
+- Test doesn't match actual requirements
+
+**Do NOT "fix" tests by:**
+- Removing security checks to make them pass
+- Lowering expectations to match incomplete implementation
+- Skipping test cases that should work
+
+**After fixing tests:**
+- Return to Step 3 (run tests again)
+
+## Step 4: Implement/Extend API Code
+
+**Use the `nest-server-generator` skill for implementation:**
+
+1. **Analyze what's needed:**
+   - New modules? → Use `nest-server-generator`
+   - New objects? → Use `nest-server-generator`
+   - New properties? → Use `nest-server-generator`
+   - Code modifications? → Use `nest-server-generator`
+
+2. **🔍 Understand existing codebase first - VERIFY before using:**
+   - **Read actual Service files** before calling methods:
+     - Verify method names and signatures
+     - Check required parameters and types
+     - Confirm return types
+     - Example: Read `user.service.ts` to verify `findById(id: string): Promise<User>` exists
+   - **Read actual Model files** to understand data structures:
+     - Verify field names and types
+     - Check validation rules
+     - Confirm relationships
+   - **Study @lenne.tech/nest-server patterns** (in `node_modules/@lenne.tech/nest-server/src`):
+     - Check CrudService base class for available methods (in `node_modules/@lenne.tech/nest-server/src/core/common/services/crud.service.ts`)
+     - Check RoleEnum (in the project or `node_modules/@lenne.tech/nest-server/src/core/common/enums/role.enum.ts`)
+     - Understand decorators: @Roles, @Restricted, @UnifiedField
+     - Study MapAndValidatePipe for validation logic (automatically activated via CoreModule - see `node_modules/@lenne.tech/nest-server/src/core/common/pipes/map-and-validate.pipe.ts`)
+   - **Review existing similar implementations** - don't assume, verify!
+
+   **⚠️ CRITICAL:** Don't assume methods or properties exist - READ THE CODE to verify!
+
+2a. **🚨 CRITICAL: Property Descriptions with German Comments**
+
+   **When user provides German comments/descriptions for properties, you MUST preserve them correctly!**
+
+   **Rule: `ENGLISH (GERMAN)` format**
+   - German: `// Produktname` → Description: `'Product name (Produktname)'`
+   - German: `// Straße` → Description: `'Street (Straße)'`
+   - English: `// Product name` → Description: `'Product name'` (no translation)
+
+   **Process:**
+   1. ✅ Extract ALL comments from user requirements (after `//`)
+   2. ✅ Translate German to English, keep German in parentheses
+   3. ✅ Fix spelling errors but preserve exact wording
+   4. ✅ Apply SAME description to: Model, CreateInput, UpdateInput, @ObjectType, @InputType
+   5. ❌ NEVER change wording (e.g., `Straße` → `Straßenname` is WRONG!)
+   6. ❌ NEVER skip German original in parentheses
+
+   **Example from user requirements:**
+   ```
+   Module: Product
+   - name: string // Produktname
+   - price: number // Price
+   ```
+
+   **Correct implementation in ALL locations:**
+   ```typescript
+   // In product.model.ts:
+   @UnifiedField({ description: 'Product name (Produktname)' })
+   name: string;
+
+   @UnifiedField({ description: 'Price' })
+   price: number;
+
+   // In product.input.ts (CreateInput, UpdateInput):
+   @UnifiedField({ description: 'Product name (Produktname)' })
+   name: string;
+
+   @UnifiedField({ description: 'Price' })
+   price: number;
+   ```
+
+   **See `nest-server-generator` skill → `description-management.md` for complete details.**
+
+3. **🚨 CRITICAL: ServiceOptions when calling other Services:**
+
+   **NEVER blindly pass all ServiceOptions when one Service calls another!**
+
+   When implementing Service methods that call other Services, analyze which options to pass:
+
+   **❌ WRONG:**
+   ```typescript
+   // ❌ BAD: Blindly passing all serviceOptions
+   const product = await this.productService.findOne({ id: input.productId }, serviceOptions);
+   ```
+
+   **✅ CORRECT:**
+   ```typescript
+   // ✅ GOOD: Only pass what's needed (usually just currentUser)
+   const product = await this.productService.findOne(
+     { id: input.productId },
+     { currentUser: serviceOptions.currentUser }
+   );
+
+   // ✅ GOOD: Only set inputType if different Input class is needed
+   const user = await this.userService.findOne(
+     { id: input.userId },
+     {
+       currentUser: serviceOptions.currentUser,
+       inputType: UserInput // Only if specific Input class needed (e.g., UserInput, UserInputCreate)
+     }
+   );
+   ```
+
+   **Why this matters:**
+   - **inputType** specifies which Input class (DTO) to use for validation (e.g., `UserInput`, `UserInputCreate`)
+   - The inputType from outer service might be wrong for inner service
+   - **roles** might need to be different
+   - Other options (limit, skip, etc.) might not apply
+   - Can cause incorrect permission checks or wrong validation
+
+   **Before passing options:**
+   - Analyze what's in serviceOptions (currentUser, inputType, roles, etc.)
+   - Determine what the target Service actually needs
+   - Only pass required options (usually just currentUser)
+   - Only set inputType if a specific Input class (DTO) is needed (e.g., UserInput, UserInputCreate)
+
+4. **Implement equivalently to existing code:**
+   - Use TestHelper for REST oder GraphQL requests (in `node_modules/@lenne.tech/nest-server/src/test/test.helper.ts`)
+   - Use `getStringIds()` and `getObjectIds()` from `@lenne.tech/nest-server` for ObjectId conversions
+   - Match coding style and patterns
+   - Use same architectural approaches
+   - Follow established conventions
+   - Reuse existing utilities
+
+4a. **🔐 IMPORTANT: Guards in Controllers**
+
+   **DO NOT manually add `@UseGuards(AuthGuard(AuthGuardStrategy.JWT))` - it's automatically activated by `@Roles()`!**
+
+   ```typescript
+   // ✅ CORRECT: @Roles automatically activates JWT guard
+   @Roles(RoleEnum.ADMIN)
+   @Get()
+   async findAll() {
+     return this.service.find();
+   }
+
+   // ✅ CORRECT: @Restricted also activates guards automatically
+   @Restricted()
+   @Post()
+   async create(@Body() input: CreateDto) {
+     return this.service.create(input);
+   }
+
+   // ❌ WRONG: Redundant manual guard (already included by @Roles)
+   @UseGuards(AuthGuard(AuthGuardStrategy.JWT))
+   @Roles(RoleEnum.ADMIN)
+   @Get()
+   async findAll() {
+     return this.service.find();
+   }
+   ```
+
+   **Why this matters:**
+   - `@Roles()` decorator automatically applies `@UseGuards(RolesGuard)`
+   - `RolesGuard` internally uses JWT authentication
+   - Adding `@UseGuards(AuthGuard(...))` manually is redundant and creates duplicate guards
+   - Existing controllers don't use manual guards - follow this pattern
+
+5. **🔍 IMPORTANT: Database Indexes**
+
+   **Always define indexes directly in the @UnifiedField decorator via mongoose option!**
+
+   **Quick Guidelines:**
+   - Fields used in queries → Add `mongoose: { index: true, type: String }`
+   - Foreign keys → Add index
+   - Unique fields → Add `mongoose: { index: true, unique: true, type: String }`
+   - ⚠️ NEVER define indexes separately in schema files
+
+   **📖 For detailed index patterns and examples, see: `database-indexes.md`**
+
+6. **Prefer existing packages:**
+   - Check if @lenne.tech/nest-server provides needed functionality
+   - Only add new npm packages as last resort
+   - If new package needed, verify:
+     - High quality and well-maintained
+     - Frequently used (npm downloads)
+     - Active maintenance
+     - Free license (preferably MIT)
+     - Long-term viability
+
+## Step 5: Validate & Iterate
+
+**Run ALL tests:**
+```bash
+npm test
+```
+
+**Check results:**
+
+✅ **All tests pass?**
+- Continue to Step 5a (Code Quality Check)
+
+❌ **Some tests still fail?**
+- Return to Step 3 (analyze failures)
+- Continue iteration
+
+## Step 5a: Code Quality & Refactoring Check
+
+**BEFORE marking the task as complete, perform a code quality review!**
+
+Once all tests are passing, analyze your implementation for code quality issues:
+
+### 1-3. Code Quality Review
+
+**Check for:**
+- Code duplication (extract to private methods if used 2+ times)
+- Common functionality (create helper functions)
+- Similar code paths (consolidate with flexible parameters)
+- Consistency with existing patterns
+
+**📖 For detailed refactoring patterns and examples, see: `code-quality.md`**
+
+### 4. Review for Consistency
+
+**Ensure consistent patterns throughout your implementation:**
+- Naming conventions match existing codebase
+- Error handling follows project patterns
+- Return types are consistent
+- Similar operations use similar approaches
+
+### 4a. Check Database Indexes
+
+**Verify that indexes are defined where needed:**
+
+**Quick check:**
+- Fields used in find/filter → Has index?
+- Foreign keys (userId, productId, etc.) → Has index?
+- Unique fields (email, username) → Has unique: true?
+- Fields used in sorting → Has index?
+
+**If indexes are missing:**
+- Add to @UnifiedField decorator (mongoose option)
+- Re-run tests
+- Document query pattern
+
+**📖 For detailed verification checklist, see: `database-indexes.md`**
+
+### 4b. Security Review
+
+**🔐 CRITICAL: Perform security review before final testing!**
+
+**ALWAYS review all code changes for security vulnerabilities.**
+
+**Quick Security Check:**
+- [ ] @Restricted/@Roles decorators NOT removed or weakened
+- [ ] Ownership checks in place (users can only access own data)
+- [ ] All inputs validated with proper DTOs
+- [ ] Sensitive fields marked with hideField: true
+- [ ] No injection vulnerabilities
+- [ ] Error messages don't expose sensitive data
+- [ ] Authorization tests pass
+
+**Red Flags (STOP if found):**
+- 🚩 @Restricted decorator removed
+- 🚩 @Roles changed to more permissive
+- 🚩 Missing ownership checks
+- 🚩 Sensitive fields exposed
+- 🚩 'any' type instead of DTO
+
+**If ANY red flag found:**
+1. STOP implementation
+2. Fix security issue immediately
+3. Re-run security checklist
+4. Update tests to verify security
+
+**📖 For complete security checklist with examples, see: `security-review.md`**
+
+### 5. Refactoring Decision Tree
+
+```
+Code duplication detected?
+    │
+    ├─► Used in 2+ places?
+    │   │
+    │   ├─► YES: Extract to private method
+    │   │   │
+    │   │   └─► Used across multiple services?
+    │   │       │
+    │   │       ├─► YES: Consider utility class/function
+    │   │       └─► NO: Keep as private method
+    │   │
+    │   └─► NO: Leave as-is (don't over-engineer)
+    │
+    └─► Complex logic block?
+        │
+        ├─► Hard to understand?
+        │   └─► Extract to well-named method
+        │
+        └─► Simple and clear?
+            └─► Leave as-is
+```
+
+### 6. Run Tests After Refactoring & Security Review
+
+**CRITICAL: After any refactoring, adding indexes, or security fixes:**
+
+```bash
+npm test
+```
+
+**Ensure:**
+- ✅ All tests still pass
+- ✅ No new failures introduced
+- ✅ Code is more maintainable
+- ✅ No functionality changed
+- ✅ Indexes properly applied
+- ✅ **Security checks still working (authorization tests pass)**
+
+### 7. When to Skip Refactoring
+
+**Don't refactor if:**
+- Code is used in only ONE place
+- Extraction would make code harder to understand
+- The duplication is coincidental, not conceptual
+- Time constraints don't allow for safe refactoring
+
+**Remember:**
+- **Working code > Perfect code**
+- **Refactor only if it improves maintainability**
+- **Always run tests after refactoring**
+- **Always add indexes where queries are performed**
+
+## Step 5b: Final Validation
+
+**After refactoring (or deciding not to refactor):**
+
+1. **Run ALL tests one final time:**
+   ```bash
+   npm test
+   ```
+
+2. **Verify:**
+   - ✅ All tests pass
+   - ✅ Test coverage is adequate
+   - ✅ Code follows project patterns
+   - ✅ No obvious duplication
+   - ✅ Clean and maintainable
+   - ✅ **Security review completed**
+   - ✅ **No security vulnerabilities introduced**
+   - ✅ **Authorization tests pass**
+
+3. **Generate final report for developer**
+
+4. **YOU'RE DONE!** 🎉