Initial commit

skills/ln-311-task-creator/references/refactoring_task_template.md

@@ -0,0 +1,515 @@
+# Task Title: Refactor [Component/Feature Name]
+
+**Epic:** [Epic N - Epic Name](link) *(optional)*
+**User Story:** [USXXX Story Name](link) *(parent task - this task will have parentId=USXXX)*
+**Related:** TEAM-XX, TEAM-YY
+
+---
+
+## Context
+
+**Story:** [Story ID] [Story Title]
+
+**Problems Found During Code Review:**
+
+Review conducted in ln-340-story-quality-gate Pass 1 identified the following code quality issues requiring refactoring.
+
+**Current State:**
+- Code has quality issues (DRY/KISS/YAGNI/Architecture violations)
+- Functionality works but maintainability/readability/performance affected
+- Technical debt accumulating
+
+**Desired State:**
+- Same functionality preserved (HARD RULE: no behavior changes)
+- Code quality improved (DRY/KISS/YAGNI principles applied)
+- Architecture clean (proper layer boundaries)
+- All existing tests pass (regression verification)
+
+---
+
+## Code Quality Issues
+
+### Issue 1: [Category] - [Short Description]
+
+**Category:** [DRY Violation / KISS Violation / YAGNI Violation / Architecture Issue / Guide Violation]
+**Severity:** [HIGH / MEDIUM / LOW]
+
+**Files Affected:**
+- `path/to/file1.py:45-60` - [Brief description of issue location]
+- `path/to/file2.py:120-135` - [Brief description of issue location]
+
+**Problem:**
+[Detailed description of what's wrong with current implementation]
+
+**Before (Current Code):**
+```language
+// Example of problematic code
+// Show actual code from codebase
+```
+
+**After (Proposed Fix):**
+```language
+// Example of refactored code
+// Show how it should look after refactoring
+```
+
+**Benefits:**
+- [Benefit 1: e.g., "DRY: 45 lines → 21 lines (53% reduction)"]
+- [Benefit 2: e.g., "Maintainability: Fix bugs once, not 3 times"]
+- [Benefit 3: e.g., "Testability: Unit test validator separately"]
+
+**Why This Violates [Principle]:**
+[Explain which principle violated and why it matters]
+
+### Issue 2: [Category] - [Short Description]
+
+**Category:** [DRY / KISS / YAGNI / Architecture / Guide Violation]
+**Severity:** [HIGH / MEDIUM / LOW]
+
+**Files Affected:**
+- [List files and line numbers]
+
+**Problem:**
+[Description]
+
+**Before:**
+```language
+[Current problematic code]
+```
+
+**After (Proposed):**
+```language
+[Refactored code]
+```
+
+**Benefits:**
+- [Benefits list]
+
+### Issue 3: [Category] - [Short Description]
+
+**Category:** [DRY / KISS / YAGNI / Architecture / Guide Violation]
+**Severity:** [HIGH / MEDIUM / LOW]
+
+**Files Affected:**
+- [List files]
+
+**Problem:**
+[Description]
+
+**Verification (for YAGNI violations):**
+```bash
+# Command to verify code is unused
+rg "function_name" --type language
+# Output: No matches found (confirms dead code)
+```
+
+**Action:** [Delete / Simplify / Consolidate]
+
+**Benefits:**
+- [Benefits]
+
+---
+
+## Refactoring Goal
+
+**Primary Goal:**
+Resolve all identified code quality issues while preserving 100% of existing functionality.
+
+**Specific Objectives:**
+- [ ] Fix all DRY violations (eliminate code duplication)
+- [ ] Fix all KISS violations (simplify over-engineered solutions)
+- [ ] Fix all YAGNI violations (remove unused/premature features)
+- [ ] Fix all architecture issues (restore proper layer boundaries)
+- [ ] Fix all guide violations (align with project patterns)
+
+**Success Criteria:**
+- All issues from Code Quality Issues section resolved
+- All existing tests pass (regression verification)
+- Functionality unchanged (verified through manual testing)
+- Code quality metrics improved (measurable reduction in complexity/duplication)
+
+---
+
+## Refactoring Plan (3 Phases)
+
+### Phase 1: Analysis & Preparation
+
+**Baseline Capture:**
+- [ ] Run existing test suite → Record pass/fail count (baseline for Phase 3)
+- [ ] Document current behavior:
+  - Take screenshots of key UI states (if UI changes)
+  - Capture API responses for key endpoints (if backend changes)
+  - Record timing benchmarks (if performance-sensitive)
+- [ ] Identify all affected tests:
+  - `rg "ClassName|functionName" tests/` → Find tests that exercise refactored code
+  - Review test files to understand test coverage
+- [ ] Create backup branch (git branch backup/refactor-[feature-name])
+
+**Best Practices Research:**
+- [ ] Research DRY patterns (MCP Ref, Context7, WebSearch)
+  - Query: "DRY principle [language] best practices 2024"
+  - Find established patterns for consolidating duplicated code
+- [ ] Research KISS simplification (if applicable)
+  - Query: "simplify [over-engineered pattern] [language]"
+  - Find simpler alternatives to current implementation
+- [ ] Review project guides (CLAUDE.md, docs/guides/)
+  - Verify patterns referenced in Story Technical Notes
+  - Ensure refactoring aligns with project standards
+
+**Risk Assessment:**
+- [ ] Identify high-risk refactorings (core business logic, critical paths)
+- [ ] Plan incremental approach (small changes, test after each)
+- [ ] Document rollback plan (if refactoring fails)
+
+### Phase 2: Refactoring Execution
+
+**Execute refactorings in priority order (HIGH → MEDIUM → LOW):**
+
+**Issue 1: [HIGH Priority]**
+- [ ] [Step 1: Specific action - e.g., "Create shared utility function in utils/validators.py"]
+- [ ] [Step 2: Specific action - e.g., "Replace 3 duplicates in api/routes/*.py"]
+- [ ] [Step 3: Specific action - e.g., "Add unit tests for new utility function"]
+- [ ] Run tests after Issue 1 fix (verify no regression)
+
+**Issue 2: [MEDIUM Priority]**
+- [ ] [Step 1: Specific action]
+- [ ] [Step 2: Specific action]
+- [ ] Run tests after Issue 2 fix
+
+**Issue 3: [LOW Priority]**
+- [ ] [Step 1: Specific action]
+- [ ] [Step 2: Specific action]
+- [ ] Run tests after Issue 3 fix
+
+**Incremental Approach:**
+- Fix one issue at a time
+- Run tests after each fix (catch regressions immediately)
+- Commit after each successful fix (git commit -m "refactor: fix [issue]")
+- If any test fails → STOP, analyze, fix refactoring (not test)
+
+### Phase 3: Regression Verification
+
+**Verify functionality unchanged:**
+
+- [ ] **Run test suite again:**
+  - Compare with Phase 1 baseline
+  - MUST match exactly (same pass/fail count, same test names)
+  - If ANY test fails → Refactoring introduced bug, MUST fix
+
+- [ ] **Compare behavior with baseline:**
+  - API responses MUST be identical (diff outputs)
+  - UI screenshots MUST match (visual regression)
+  - Timing within 5% of baseline (performance not degraded)
+
+- [ ] **Manual smoke testing:**
+  - Test main user flows (verify no behavior change)
+  - Use `scripts/tmp_[story_id].sh` if exists (from manual testing)
+  - Document any unexpected behavior
+
+- [ ] **Quality gates:**
+  - Type checking passes (mypy/TypeScript)
+  - Linting passes (ruff/ESLint)
+  - No new warnings introduced
+
+**If verification fails:**
+- [ ] Analyze failure root cause (refactoring bug vs test bug)
+- [ ] Fix refactoring (preferred) OR update test (only if test was wrong)
+- [ ] Re-run Phase 3 verification
+
+---
+
+## Regression Testing Strategy
+
+> [!WARNING]
+
+> Refactoring NEVER changes functionality. If tests fail after refactoring → Implementation error.
+
+### Baseline Capture (Phase 1)
+
+**Test Suite Baseline:**
+```bash
+# Run full test suite, capture output
+pytest -v > baseline_tests.txt  # or npm test, etc.
+
+# Record metrics
+Total tests: [X]
+Passed: [X]
+Failed: [X]
+Skipped: [X]
+```
+
+**Behavior Baseline (for critical functionality):**
+```bash
+# Capture API responses
+curl -X GET $BASE_URL/api/endpoint > baseline_api_response.json
+
+# Capture UI state (if applicable)
+# Screenshot key pages, record element states
+```
+
+**Performance Baseline (if performance-sensitive):**
+```bash
+# Record timing benchmarks
+pytest --benchmark-only > baseline_benchmarks.txt
+```
+
+### Verification Protocol (Phase 3)
+
+**Step 1: Test Suite Comparison**
+- Run test suite again → Compare with baseline
+- **Expected:** Exact match (same tests pass/fail)
+- **If mismatch:** STOP, analyze failure, fix refactoring
+
+**Step 2: Behavior Comparison**
+- Capture API responses again → Diff with baseline
+- **Expected:** Identical responses (diff shows no changes)
+- **If different:** STOP, analyze, fix refactoring
+
+**Step 3: Performance Comparison**
+- Run benchmarks again → Compare with baseline
+- **Expected:** Within 5% of baseline timing
+- **If degraded >5%:** Analyze, optimize refactoring
+
+### Failure Handling
+
+**If ANY test fails after refactoring:**
+
+1. **STOP immediately** - Do NOT proceed with additional refactorings
+2. **Analyze root cause:**
+   - Read test failure message
+   - Identify which refactoring caused failure
+   - Determine if refactoring introduced bug OR test needs update
+3. **Fix refactoring (preferred approach):**
+   - Revert last change: `git revert HEAD`
+   - Re-analyze issue, apply safer refactoring
+   - Run tests again
+4. **Update test (only if test was wrong):**
+   - Verify test expectation was incorrect (not refactoring bug)
+   - Update test assertions/mocks
+   - Document why test update needed (in commit message)
+5. **Re-run Phase 3 verification**
+
+**Tools:**
+- Test framework: pytest/jest/vitest (auto-detected in Phase 1)
+- Diff tools: `diff`, `jq` (for JSON), screenshot comparison
+- Performance: pytest-benchmark, Lighthouse (if UI)
+
+---
+
+## Code Simplification Principles
+
+Apply these principles during Phase 2 refactoring (from Claude Code PR Toolkit `code-simplifier` agent):
+
+### 1. Preserve Functionality (HARD RULE)
+
+**Rule:** NEVER change what code does - only HOW it does it.
+
+- ❌ **Forbidden:** Change outputs, modify behavior, alter features
+- ✅ **Allowed:** Change structure, consolidate logic, rename variables
+- ✅ **Verification:** All existing tests MUST pass after refactoring
+
+**Example:**
+```python
+# WRONG: Changed behavior
+def validate_email(email):
+    # Before: allowed @gmail.com and @yahoo.com
+    # After: ONLY allows @gmail.com (BEHAVIOR CHANGED - FORBIDDEN!)
+    return email.endswith('@gmail.com')
+
+# CORRECT: Same behavior, refactored
+def validate_email(email):
+    # Before: inline validation in 3 places
+    # After: extracted to shared function (SAME BEHAVIOR - ALLOWED!)
+    allowed_domains = ('@gmail.com', '@yahoo.com')
+    return email.endswith(allowed_domains)
+```
+
+### 2. Apply Project Standards
+
+**Follow CLAUDE.md coding standards:**
+- ES modules with proper imports
+- Explicit type annotations
+- Proper error handling (avoid try/catch when possible)
+- Consistent naming conventions
+
+**Example:**
+```typescript
+// Before: Non-standard
+const getUser = (id) => { ... }
+
+// After: Project standard (explicit types, function keyword)
+function getUser(id: string): User | null { ... }
+```
+
+### 3. Enhance Clarity
+
+**Reduce complexity, improve readability:**
+- ✅ Reduce nesting (extract nested logic to functions)
+- ✅ Eliminate redundant code (DRY principle)
+- ✅ Clear names (intent-revealing variable/function names)
+- ✅ Consolidate related logic (group cohesive operations)
+- ✅ Remove unnecessary comments (self-documenting code)
+- ✅ Avoid nested ternaries (use switch/if-else for multiple conditions)
+
+**Example:**
+```python
+# Before: Nested and unclear
+if user:
+    if user.active:
+        if user.verified:
+            return user.data
+return None
+
+# After: Clear and flat
+if not user or not user.active or not user.verified:
+    return None
+return user.data
+```
+
+### 4. Maintain Balance (DON'T Over-Simplify)
+
+**Avoid extreme simplification:**
+- ❌ Don't reduce clarity for brevity (explicit > compact)
+- ❌ Don't combine too many concerns (single responsibility)
+- ❌ Don't remove helpful abstractions
+- ❌ Don't prioritize "fewer lines" over readability
+
+**Example:**
+```javascript
+// WRONG: Over-simplified (hard to understand)
+const r = u?.a && u?.v ? u?.d : null;
+
+// CORRECT: Clear and explicit
+if (!user || !user.active || !user.verified) {
+    return null;
+}
+return user.data;
+```
+
+### 5. Focus Scope
+
+**Only refactor what's in scope:**
+- ✅ Refactor code identified in Code Quality Issues section
+- ✅ Refactor closely related code (within same module/class)
+- ❌ Don't expand scope beyond identified issues
+- ❌ Don't refactor unrelated files
+
+**Example:**
+```
+Issue: Duplicate validation in api/routes/users.py and api/routes/auth.py
+✅ Refactor: Extract validation to utils/validators.py
+✅ Refactor: Update imports in both route files
+❌ Don't refactor: Other unrelated routes (outside scope)
+```
+
+---
+
+## Acceptance Criteria
+
+**Given** current implementation has code quality issues
+**When** refactoring is applied according to Refactoring Plan
+**Then** all issues are resolved AND functionality is preserved
+
+**Specific Checks:**
+
+- [ ] **DRY:** No code duplication remains (verified with grep/rg for repeated patterns)
+- [ ] **KISS:** Solutions simplified where possible (removed over-engineering)
+- [ ] **YAGNI:** No unused features remain (verified with grep/rg, dead code eliminated)
+- [ ] **Architecture:** Clean layer boundaries (no violations of project patterns)
+- [ ] **Guides:** Implementation aligns with project guides (CLAUDE.md, docs/guides/)
+- [ ] **Regression:** All existing tests pass (Phase 3 verification successful)
+- [ ] **Behavior:** Functionality unchanged (manual testing confirms same behavior)
+- [ ] **Quality Gates:** Type checking + linting pass (no new warnings)
+
+---
+
+## Affected Components
+
+### Implementation Files to Refactor
+- `path/to/component1` - [What will be refactored: e.g., "Extract duplicate validation logic"]
+- `path/to/component2` - [What will be refactored: e.g., "Simplify state management"]
+- `path/to/component3` - [What will be refactored: e.g., "Remove unused OAuth 1.0 implementation"]
+
+### Tests to Update (ONLY if refactoring breaks them)
+- `tests/path/test_file1` - [Why update needed: e.g., "Mock signatures changed"]
+- `tests/path/test_file2` - [Why update needed: e.g., "Assertions need adjustment"]
+
+### Documentation to Update
+- `README.md` - [What to update: e.g., "Remove references to old pattern"]
+- `ARCHITECTURE.md` - [What to update: e.g., "Update component diagram"]
+- `docs/guides/[guide].md` - [What to update: e.g., "Update code examples"]
+
+---
+
+## Existing Code Impact
+
+### Refactoring Required
+
+**Component 1: [Component Name]**
+- **File:** `path/to/file`
+- **What:** [Specific refactoring action - e.g., "Extract duplicate validation to shared utility"]
+- **Why:** [Reason - e.g., "DRY violation: same logic in 3 places"]
+- **Risk:** [HIGH/MEDIUM/LOW] - [Risk explanation]
+
+**Component 2: [Component Name]**
+- **File:** `path/to/file`
+- **What:** [Refactoring action]
+- **Why:** [Reason]
+- **Risk:** [Level]
+
+### Tests to Update (ONLY Existing Tests Affected)
+
+**SCOPE:** ONLY list existing tests that may break due to refactoring (signature changes, mock updates, etc.).
+DO NOT create new tests here. New tests were created in Story's final test task by ln-350-story-test-planner.
+
+**Examples of valid test updates:**
+- Mock/stub updates when function signatures change
+- Assertion updates when internal structure changes
+- Import path updates when files moved
+
+**Test Suite 1:**
+- **File:** `tests/path/test_file`
+- **Why Affected:** [Reason - e.g., "Function signature changed from (a, b) to (config)"]
+- **Update Needed:** [Specific change - e.g., "Update mock to use new signature"]
+
+### Documentation to Update
+- `docs/file.md` - [Existing docs to update - e.g., "Update architecture diagram"]
+- `README.md` - [What to update - e.g., "Remove references to deprecated pattern"]
+
+---
+
+## Definition of Done
+
+### Refactoring Completion
+- [ ] All problems from Code Quality Issues section resolved
+- [ ] All refactorings from Phase 2 executed successfully
+- [ ] Code follows DRY/KISS/YAGNI/SOLID principles
+- [ ] Architecture clean (proper layer boundaries)
+- [ ] Guides followed (project patterns applied)
+
+### Regression Verification
+- [ ] **All existing tests pass** (Phase 3 verification successful)
+- [ ] Test suite matches Phase 1 baseline (same pass/fail count)
+- [ ] Functionality unchanged (manual testing confirms)
+- [ ] Behavior matches baseline (API responses, UI states identical)
+- [ ] Performance within 5% of baseline (no degradation)
+
+### Quality Gates
+- [ ] Type checking passes (mypy/TypeScript)
+- [ ] Linting passes (ruff/ESLint)
+- [ ] No new warnings introduced
+
+### Documentation
+- [ ] Code changes documented (commit messages describe refactorings)
+- [ ] README.md updated (if public API/patterns changed)
+- [ ] ARCHITECTURE.md updated (if component structure changed)
+- [ ] Guides updated (if refactoring changes recommended patterns)
+
+### Review
+- [ ] Code reviewed by team member (if applicable)
+- [ ] Refactoring approach approved (architecture alignment)
+
+---
+
+**Template Version:** 2.0.0 (Expanded with Code Quality Issues, Refactoring Plan, Regression Testing Strategy, Code Simplification Principles)
+**Last Updated:** 2025-11-13

skills/ln-311-task-creator/references/task_template_implementation.md

@@ -0,0 +1,146 @@
+# Task Title
+<!-- Task Size Guideline: Optimal 3-5 hours development time (atomic, testable unit). Too small < 3h → combine with related work. Too large > 8h → decompose further. -->
+<!-- SCOPE: Implementation tasks ONLY. DO NOT create new tests in this task.
+     New tests (E2E/Integration/Unit) are created separately by ln-350-story-test-planner after manual testing passes.
+     This task may update existing tests if implementation changes break them. -->
+
+**Epic:** [Epic N - Epic Name](link) *(optional)*
+**User Story:** [USXXX Story Name](link) *(parent task - this task will have parentId=USXXX)*
+**Related:** TEAM-XX, TEAM-YY
+
+---
+
+## Context
+
+### Current State
+- What exists now?
+- What's the problem or limitation?
+
+### Desired State
+- What should exist after completion?
+- What benefits will this bring?
+
+---
+
+## Implementation Plan
+
+### Phase 1: [Description]
+- [ ] Step 1
+- [ ] Step 2
+
+### Phase 2: [Description]
+- [ ] Step 1
+- [ ] Step 2
+
+### Phase 3: [Description]
+- [ ] Step 1
+- [ ] Step 2
+
+---
+
+## Technical Approach
+
+### Recommended Solution
+**Library/Framework:** [name] v[version] ([stability: LTS/stable/beta])
+**Documentation:** [official docs URL]
+
+**Standards compliance:** [RFC/spec if applicable, e.g., RFC 6749 for OAuth 2.0]
+
+### Key APIs
+**Primary methods:**
+- `[method_signature]` - [purpose and when to use]
+- `[method_signature]` - [purpose and when to use]
+- `[method_signature]` - [purpose and when to use]
+
+**Configuration:**
+- `[parameter]`: [value/type] - [purpose and impact]
+- `[parameter]`: [value/type] - [purpose and impact]
+
+### Implementation Pattern
+**Core logic:**
+```pseudocode
+[High-level pseudocode showing main integration flow]
+[Focus on HOW to integrate library/API, not full business logic]
+[5-10 lines maximum - this is a guide, not implementation]
+```
+
+**Integration points:**
+- **Where:** [file/module path where integration happens]
+- **How:** [dependency injection / direct import / middleware / decorator / etc.]
+- **When:** [startup / request handler / background task / etc.]
+
+### Why This Approach
+- [Reason 1: Standards compliance or industry best practice reference]
+- [Reason 2: Performance/Security/Maintainability/Team familiarity benefit]
+
+### Patterns Used
+- [Pattern 1] - [purpose in this context]
+- [Pattern 2] - [purpose in this context]
+
+### Known Limitations
+- [Limitation 1: e.g., no async support, memory constraints] - [workaround or mitigation if any]
+- [Limitation 2: e.g., compatibility issue, deprecated feature] - [impact on implementation]
+
+### Alternatives Considered
+- **Alternative 1:** [name] - [why rejected: outdated/over-engineered/non-standard/lacking feature]
+- **Alternative 2:** [name] - [why rejected: performance/complexity/compatibility]
+
+---
+
+**SCOPE NOTE:** This Technical Approach should be 200-300 words max. Focus on KEY APIs (2-5 methods) and integration points, NOT exhaustive API documentation. This specification guides implementation without prescribing every detail. Executor discovers full implementation specifics during execution.
+
+---
+
+## Acceptance Criteria
+
+- [ ] **Given** [context] **When** [action] **Then** [result]
+- [ ] **Given** [context] **When** [action] **Then** [result]
+- [ ] **Given** [context] **When** [action] **Then** [result]
+
+---
+
+## Affected Components
+
+### Implementation
+- `path/to/file` - Changes
+
+### Documentation (REQUIRED in this task)
+- `README.md` - Feature documentation
+- `docs/api.md` - API updates
+
+---
+
+## Existing Code Impact
+
+### Refactoring Required
+- `path/to/file` - What needs refactoring and why
+
+### Tests to Update (ONLY Existing Tests Affected by This Task)
+**SCOPE:** ONLY list existing tests that break due to implementation changes (refactoring, logic updates).
+DO NOT create new tests here. New tests are created by ln-350-story-test-planner after manual testing.
+
+**Examples of valid updates:**
+- Mock/stub changes when function signatures change
+- Assertion updates when return values change
+- Test data updates when validation logic changes
+
+- `tests/path/test_file` - Why this existing test needs updates
+
+### Documentation to Update
+- `docs/file.md` - Existing docs to update
+
+---
+
+## Definition of Done
+
+- [ ] All acceptance criteria met
+- [ ] All existing code refactored (no backward compatibility / legacy code left)
+- [ ] All existing tests updated (if any were affected by implementation changes)
+- [ ] NO new tests created (new tests are in Story's final test task by ln-350-story-test-planner)
+- [ ] Documentation updated
+- [ ] Code reviewed
+
+---
+
+**Template Version:** 6.0.1 (Renamed from task_template_universal.md to clarify scope: implementation tasks only)
+**Last Updated:** 2025-11-13

skills/ln-311-task-creator/references/test_task_template.md

@@ -0,0 +1,542 @@
+# Tests for Story: [Story Title]
+
+**User Story:** [USXXX Story Name](link) *(parent task - this is the FINAL task of Story)*
+**Epic:** [Epic N - Epic Name](link)
+
+---
+
+## Context
+
+### Story Goal
+[Story statement from parent: As a... I want... So that...]
+
+### Implemented Features
+List of completed implementation tasks in this Story:
+- [API-XX: Task Name](link) - What was implemented
+- [API-YY: Task Name](link) - What was implemented
+
+### What to Test
+All business logic implemented across Story Tasks:
+- Components/modules added or modified
+- Integration points established
+- Business flows enabled
+
+---
+
+## Risk Priority Matrix
+
+**Reference:** See `risk_based_testing_guide.md` for detailed methodology
+
+**Priority Formula:** Priority = Business Impact (1-5) × Probability of Failure (1-5)
+
+| Scenario | Business Impact | Probability | Priority | Test Type | Notes |
+|----------|----------------|-------------|----------|-----------|-------|
+| [Scenario from manual testing] | [1-5] | [1-5] | [1-25] | E2E/Integration/Unit/SKIP | [Reason for decision] |
+| [Scenario from manual testing] | [1-5] | [1-5] | [1-25] | E2E/Integration/Unit/SKIP | [Reason for decision] |
+
+**Test Limits:** 2-5 E2E (baseline 2), 0-8 Integration, 0-15 Unit per Story (**realistic goal: 2-7 total**, hard limit: 28)
+
+**Minimum Viable Testing Philosophy:**
+- Start with 2 baseline E2E tests per endpoint (positive + negative)
+- Add tests #3+ ONLY with critical justification: "Why does this test OUR business logic (not framework/library/database)?"
+- Auto-trim to 7 tests if plan exceeds realistic goal (keep 2 baseline E2E + top 5 Priority)
+
+**Principles:**
+- ✅ Prioritize by business risk (money, security, data corruption) over coverage metrics
+- ✅ Test OUR code ONLY (not frameworks/libraries/external systems/database queries)
+- ✅ Anti-Duplication: If 2 baseline E2E cover logic, SKIP unit test
+- ✅ Anti-Framework: If testing Prisma/Express/bcrypt behavior → SKIP
+- ✅ Fast feedback: Unit (ms) → Integration (seconds) → E2E (tens of seconds)
+- ✅ Focus on critical paths (Priority ≥15), not blanket coverage
+
+**Decision Criteria:**
+- Priority ≥15 → MUST test (if tests OUR logic)
+- Priority 9-14 → SHOULD test if not already covered AND tests OUR logic
+- Priority ≤8 → SKIP (manual testing sufficient)
+
+---
+
+## E2E Tests (2-5 max)
+
+**BASELINE (ALWAYS): 2 E2E tests per endpoint**
+- Test 1: Positive scenario (happy path validating main AC)
+- Test 2: Negative scenario (critical error handling)
+
+**ADDITIONAL (Tests 3-5): ONLY if Priority ≥15 AND critical justification provided**
+
+Test complete user journeys through the system. Each test beyond baseline 2 MUST justify: "Why does this test OUR business logic (not framework/library/database)?"
+
+**Type:** [API E2E / UI E2E] *(depending on application type)*
+
+### [Critical Scenario 1]: [User Journey Name] (Priority [XX])
+
+**From Manual Testing:** [Link to AC or edge case in manual test results]
+
+**Business Impact:** [1-5] - [Why critical: money/security/core flow]
+**Probability of Failure:** [1-5] - [Why risky: complexity/external API/new tech]
+**Priority:** [Business Impact × Probability] = [Result]
+
+**Test Flow (copied from manual testing):**
+1. **Setup:** [Initial state/preconditions from manual testing]
+2. **Step 1:** [User action from curl/puppeteer] → **Verify:** [Expected result verified manually]
+3. **Step 2:** [User action] → **Verify:** [Expected result]
+4. **Step 3:** [User action] → **Verify:** [Final outcome]
+5. **Cleanup:** [Teardown actions]
+
+**Test:**
+- [ ] `test_e2e_[scenario_name]` - Full journey from start to finish
+
+**Anti-Duplication Check:**
+- ✅ This E2E test is necessary because: [Unique business value not covered by other tests]
+
+### [Critical Scenario 2]: [User Journey Name] (Priority [XX])
+
+**From Manual Testing:** [Link to AC or edge case]
+
+**Business Impact:** [1-5]
+**Probability of Failure:** [1-5]
+**Priority:** [Result]
+
+**Test Flow:**
+1. **Setup:** [Initial state]
+2. **Actions & Verifications:** [Step-by-step user journey]
+3. **Cleanup:** [Teardown]
+
+**Test:**
+- [ ] `test_e2e_[scenario_name]` - Description
+
+**Anti-Duplication Check:**
+- ✅ This E2E test is necessary because: [Reason]
+
+### Standards
+- [ ] **BASELINE: 2 E2E tests per endpoint (positive + negative) - ALWAYS**
+- [ ] **ADDITIONAL: Tests 3-5 ONLY with critical justification**
+- [ ] Maximum 5 E2E tests per Story (hard limit)
+- [ ] All scenarios Priority ≥15
+- [ ] **Each test beyond baseline 2 has documented justification: "Why does this test OUR business logic?"**
+- [ ] E2E tests run in < 2 minutes total
+- [ ] Test against stable environment (staging/test)
+- [ ] Based on ACTUAL manual testing results (not theoretical scenarios)
+- [ ] Clean up test data after execution
+- [ ] **No tests for framework/library/database behavior** (trust Prisma/Express/PostgreSQL)
+
+---
+
+## Integration Tests (0-8 max)
+
+**DEFAULT: 0 Integration tests** (2 baseline E2E tests cover full stack by default)
+
+**ADD ONLY if:** E2E doesn't cover interaction completely AND Priority ≥15 AND critical justification provided
+
+Test OUR business logic with REAL internal dependencies. **ONLY Priority ≥15 interactions NOT fully covered by 2 baseline E2E.** Each integration test MUST justify: "Why does this test OUR integration logic (not framework/library behavior)?"
+
+### [Integration Point 1]: [Layer Interaction] (Priority [XX])
+
+**Scope:** [Layer A] → [Layer B] → [Layer C] (e.g., API → Service → Repository → DB)
+
+**Why Integration Test Needed:**
+- E2E test covers happy path, but need to verify: [Transaction rollback / Error handling / Concurrency]
+- Business Impact: [1-5] - [Reason]
+- Probability: [1-5] - [Reason]
+- Priority: [Result]
+
+**Tests:**
+- [ ] `test_[flow]_integration` - Verifies complete data flow through layers
+  - **Given:** [Setup: real DB with test data]
+  - **When:** [Action: call Layer A]
+  - **Then:** [Verify: data correctly flows and persists in DB]
+
+**Use Real:**
+- Database (test instance)
+- Filesystem (temp directory)
+- Internal services
+
+**Use Mocks:**
+- External API calls
+- Email/SMS services
+- Payment gateways
+
+**Anti-Duplication Check:**
+- ✅ This integration test adds value because: [E2E doesn't test error scenario / E2E doesn't test concurrent requests]
+
+### [Integration Point 2]: [Description] (Priority [XX])
+
+**Scope:** [Description of integration]
+
+**Why Integration Test Needed:**
+- [Reason E2E insufficient]
+- Priority: [Result]
+
+**Tests:**
+- [ ] `test_[integration_scenario]` - What interaction this verifies
+
+**Anti-Duplication Check:**
+- ✅ Adds value because: [Reason]
+
+### Standards
+- [ ] **DEFAULT: 0 Integration tests** (2 baseline E2E cover full stack)
+- [ ] Maximum 8 integration tests per Story (hard limit)
+- [ ] All scenarios Priority ≥15
+- [ ] **Each integration test has documented justification: "Why does this test OUR integration logic?"**
+- [ ] Use test database (not production)
+- [ ] Clean up after each test (rollback/truncate)
+- [ ] All integration tests run in < 30 seconds total
+- [ ] Skip if 2 baseline E2E already validate end-to-end
+- [ ] **No tests for framework/library integrations** (Prisma client, TypeORM, Express app behavior)
+
+---
+
+## Unit Tests (0-15 max)
+
+**DEFAULT: 0 Unit tests** (2 baseline E2E tests cover simple logic by default)
+
+**ADD ONLY for:** Complex business logic with Priority ≥15 AND critical justification provided
+
+Test individual components in isolation with all dependencies mocked. **ONLY complex business logic with Priority ≥15.** Each unit test MUST justify: "Why does this test OUR complex business logic (not library/framework/database behavior)?"
+
+**MANDATORY SKIP - DO NOT create unit tests for:**
+- ❌ Simple CRUD operations (already covered by 2 baseline E2E)
+- ❌ Framework code (Express middleware, React hooks, FastAPI dependencies)
+- ❌ Library functions (bcrypt hashing, jsonwebtoken signing, axios requests)
+- ❌ Database queries (Prisma findMany, TypeORM query builder, SQL joins)
+- ❌ Getters/setters or simple property access
+- ❌ Trivial conditionals (`if (user) return user.name`, `status === 'active'`)
+- ❌ Pass-through functions (wrappers without logic)
+- ❌ Performance/load testing (throughput, latency, stress tests, scalability)
+
+### [Component/Module Name 1]: [Complex Business Logic Function] (Priority [XX])
+
+**File:** `path/to/component`
+
+**Why Unit Test Needed:**
+- Function: [Financial calculation / Security logic / Complex algorithm]
+- Business Impact: [1-5] - [Money/Security/Data]
+- Probability: [1-5] - [Complexity/Edge cases]
+- Priority: [Result]
+
+**Business scenarios to test:**
+- [ ] `test_[function]_happy_path` - Main business scenario
+- [ ] `test_[function]_edge_case_[discovered_in_manual_testing]` - Edge case from manual testing (Priority ≥9)
+- [ ] `test_[function]_error_handling_[business_impact_4_or_5]` - Error with high business impact
+
+**Mocks needed:**
+- [Dependency 1]: Mock behavior
+- [Dependency 2]: Mock behavior
+
+**Anti-Duplication Check:**
+- ✅ E2E doesn't fully exercise: [Edge case X / Error condition Y]
+
+### [Component/Module Name 2]: [Another Complex Function] (Priority [XX])
+
+**File:** `path/to/component`
+
+**Why Unit Test Needed:**
+- [Reason - complexity/business impact]
+- Priority: [Result]
+
+**Business scenarios to test:**
+- [ ] `test_[scenario]` - Description of what this test verifies and WHY (business value)
+
+**Mocks needed:**
+- [Dependency]: Mock behavior
+
+**Anti-Duplication Check:**
+- ✅ Not covered by E2E because: [Reason]
+
+### Standards
+- [ ] **DEFAULT: 0 Unit tests** (2 baseline E2E cover simple logic)
+- [ ] Maximum 15 unit tests per Story (hard limit)
+- [ ] **Each unit test has documented justification: "Why does this test OUR complex business logic?"**
+- [ ] All tests run in < 5 seconds total
+- [ ] No external dependencies (DB, filesystem, network)
+- [ ] Each test independent (can run in any order)
+- [ ] Only test complex business logic (Priority ≥15): financial calculations, security algorithms, complex business rules
+- [ ] Skip if 2 baseline E2E already exercise all branches
+- [ ] **No tests for library/framework/database behavior** (bcrypt, jwt, Prisma, axios)
+
+## Critical Path Coverage
+
+**Focus:** All Priority ≥15 scenarios tested, NOT blanket coverage percentage
+
+**What MUST be tested (Priority ≥15):**
+- [ ] All Acceptance Criteria from Story (verified in manual testing)
+- [ ] Money-related scenarios (payments, refunds, pricing calculations)
+- [ ] Security-critical flows (authentication, authorization, data access)
+- [ ] Data integrity scenarios (transactions, rollbacks, concurrent updates)
+- [ ] Core business flows (user cannot complete primary use case)
+- [ ] High-risk edge cases discovered in manual testing (Priority ≥15)
+
+**What SHOULD be tested (Priority 9-14) if not covered by E2E:**
+- [ ] Medium-risk edge cases from manual testing
+- [ ] Secondary business flows
+- [ ] Error scenarios with Business Impact 3-4
+
+**What to SKIP (Priority ≤8):**
+- ❌ Simple CRUD operations (E2E covers these)
+- ❌ Framework code (Express, React, Prisma)
+- ❌ Third-party libraries (not our code)
+- ❌ Trivial getters/setters
+- ❌ Cosmetic bugs (color, spacing)
+- ❌ Minor UX issues (button state)
+- ❌ Scenarios already validated by manual testing with low business impact
+- ❌ Performance/load testing (requires separate infrastructure and specialized tools)
+
+**Coverage Expectations:**
+- Coverage % is a metric, NOT a goal
+- 40% coverage with 2 baseline E2E + Priority ≥15 scenarios tested → **ACCEPTABLE**
+- 60% coverage with all Priority ≥15 scenarios tested → **EXCELLENT**
+- 90% coverage but includes framework/library tests → **UNACCEPTABLE** (remove framework tests)
+- 90% coverage but payment flow not tested → **UNACCEPTABLE**
+
+**Acceptance Criteria:**
+- [ ] **Given** All Priority ≥15 scenarios identified **When** tests executed **Then** all scenarios PASS
+- [ ] **Given** Test limits (2-5 E2E, 0-8 Integration, 0-15 Unit) **When** validation **Then** within realistic goal 2-7 (hard limit: 28)
+- [ ] **Given** Tests duplicate logic **When** review **Then** consolidate or remove duplication
+- [ ] **Given** Scenario has Priority ≤14 **When** review **Then** skip test (manual testing sufficient)
+- [ ] **Given** Test validates framework/library/database **When** review **Then** remove test (not OUR code)
+
+---
+
+## Definition of Done
+
+- [ ] **2 baseline E2E tests implemented and passing (positive + negative) - ALWAYS**
+- [ ] All additional E2E tests implemented and passing (0-3 additional, all Priority ≥15 with justification)
+- [ ] All integration tests implemented and passing (0-8 max, all Priority ≥15 with justification)
+- [ ] All unit tests implemented and passing (0-15 max, all Priority ≥15 with justification)
+- [ ] **Total tests: 2-7 (realistic goal) or 2-28 (hard limit)**
+- [ ] **Each test beyond baseline 2 has documented justification: "Why does this test OUR business logic?"**
+- [ ] All Priority ≥15 scenarios from manual testing covered
+- [ ] No flaky tests (all tests pass consistently on multiple runs)
+- [ ] Test execution time acceptable (Unit <5s, Integration <30s, E2E <2min)
+- [ ] **All tests validate OUR code ONLY (not frameworks/libraries/database queries)**
+- [ ] **No tests for Prisma/Express/bcrypt/jwt/axios/PostgreSQL behavior**
+- [ ] Anti-duplication verified: each test adds unique business value
+- [ ] Skipped scenarios documented with Priority justification (Priority ≤14 or framework/library behavior)
+- [ ] Documentation updated (tests/README.md if needed)
+
+---
+
+## Existing Tests to Fix/Update
+
+**Tests affected by changes:**
+
+Before adding new tests, update existing tests that might have broken due to logic changes in this Story.
+
+### [Test File/Suite 1]: [Test Name or Path]
+
+**File:** `path/to/test/file`
+
+**Why Affected:**
+- [Explain how Story implementation changed behavior tested by this test]
+- [E.g., "Changed validation logic in API endpoint requires updated mock responses"]
+
+**Required Fixes:**
+- [ ] Update test setup/fixtures
+- [ ] Update expected values/assertions
+- [ ] Update mocked dependencies
+- [ ] Verify test passes after fix
+
+### [Test File/Suite 2]: [Test Name or Path]
+
+**File:** `path/to/test/file`
+
+**Why Affected:**
+- [Reason this existing test needs updates]
+
+**Required Fixes:**
+- [ ] [Specific fix needed]
+
+### Standards
+- [ ] All existing tests identified and reviewed
+- [ ] All affected tests fixed BEFORE adding new tests
+- [ ] Entire existing test suite passes
+- [ ] No tests temporarily disabled/skipped without justification
+- [ ] Changes documented in commit message
+
+---
+
+## Infrastructure Changes
+
+**Package Updates:**
+
+### Testing Dependencies
+
+**Packages to Add/Update:**
+- `[package-name]@[version]` - [Why needed: new test framework feature / testing library for new component]
+- `[package-name]@[version]` - [Why needed]
+
+**package.json changes:**
+```json
+{
+  "devDependencies": {
+    "[package-name]": "[version]"
+  },
+  "scripts": {
+    "[test-script]": "[command]"
+  }
+}
+```
+
+### Docker/Compose Updates
+
+**Dockerfile changes (if needed):**
+- [ ] Add test dependencies layer
+- [ ] Update base image for test environment
+- [ ] Add environment variables for testing
+
+**docker-compose.yml changes (if needed):**
+- [ ] Add test database service
+- [ ] Add test environment configuration
+- [ ] Add test volumes/networks
+
+### Test Configuration
+
+**Configuration files to update:**
+- [ ] `jest.config.js` / `vitest.config.ts` / `pytest.ini` - [What to configure]
+- [ ] `.env.test` - [Environment variables for testing]
+- [ ] Test database setup scripts
+- [ ] CI/CD pipeline configuration
+
+### Standards
+- [ ] All package versions specified (no `^` or `~` for test deps)
+- [ ] Packages compatible with existing stack
+- [ ] Docker changes tested locally
+- [ ] Test configuration committed to repository
+
+---
+
+## Documentation Updates
+
+**Files requiring documentation updates:**
+
+### tests/README.md
+
+**Updates needed:**
+- [ ] Document new test commands (`npm test`, `npm run test:e2e`, etc.)
+- [ ] Explain test structure changes (if any)
+- [ ] Document test data setup/teardown
+- [ ] Add troubleshooting section for common test failures
+- [ ] Update test coverage expectations
+
+### README.md (Main)
+
+**Updates needed:**
+- [ ] Feature documentation (what was tested and how)
+- [ ] Setup instructions (if new dependencies added)
+- [ ] Testing section (how to run tests for this feature)
+- [ ] Known limitations (if any scenarios skipped with Priority ≤8)
+
+### CHANGELOG.md
+
+**Entry to add:**
+```markdown
+## [Version] - 2025-11-03
+
+### Tested
+- [Feature/Story tested]
+- Test coverage: [X] E2E, [Y] Integration, [Z] Unit tests
+- All Priority ≥15 scenarios covered
+```
+
+### Other Documentation
+
+**Additional docs to update (if applicable):**
+- [ ] API documentation (if endpoints tested)
+- [ ] Architecture documentation (if test patterns changed)
+- [ ] Deployment guide (if test infrastructure changed)
+
+### Standards
+- [ ] All documentation in English
+- [ ] Code examples tested and working
+- [ ] Links to relevant files/resources
+- [ ] No outdated information remains
+
+---
+
+## Legacy Code Cleanup
+
+**Workarounds/Hacks to Remove:**
+
+### [File/Module 1]: [Legacy Code Item]
+
+**File:** `path/to/file`
+
+**What to Remove:**
+```
+// Lines or code blocks to remove
+[old code here]
+```
+
+**Why Safe to Remove:**
+- [Justification: functionality now covered by new implementation]
+- [Verification: tests confirm new code provides same behavior]
+- [Risk assessment: Low - deprecated since [date/version]]
+
+**Verification:**
+- [ ] All tests pass after removal
+- [ ] No references remain in codebase (grep check)
+- [ ] Feature functionality preserved
+
+### [File/Module 2]: [Backward Compatibility Code]
+
+**File:** `path/to/file`
+
+**What to Remove:**
+- [Backward compatibility shims no longer needed]
+- [Deprecated patterns replaced by new approach]
+
+**Why Safe to Remove:**
+- [Reason: all clients migrated to new API]
+- [Verification: usage analytics show zero calls]
+
+**Verification:**
+- [ ] Tests confirm removal safe
+- [ ] Documentation updated (no references to old pattern)
+
+### Deprecated Patterns
+
+**Patterns to Replace:**
+
+**Old Pattern:**
+```
+[Example of old pattern in codebase]
+```
+
+**New Pattern (implemented in this Story):**
+```
+[Example of new pattern]
+```
+
+**Files Using Old Pattern:**
+- [ ] `path/to/file1` - Replace with new pattern
+- [ ] `path/to/file2` - Replace with new pattern
+
+**Verification:**
+- [ ] All instances found (grep/search)
+- [ ] All replaced with new pattern
+- [ ] Tests updated to use new pattern
+- [ ] Old pattern documented as deprecated (if can't remove immediately)
+
+### Dead Code
+
+**Code to Remove:**
+- [ ] Unused functions/classes: [List]
+- [ ] Commented-out code blocks: [Where]
+- [ ] Unreachable code paths: [Where]
+
+**Verification Method:**
+- [ ] Static analysis (unused imports, unused variables)
+- [ ] Test coverage (uncovered code blocks)
+- [ ] Code review (manual inspection)
+
+### Standards
+- [ ] All removals justified with clear reasoning
+- [ ] Tests confirm functionality preserved
+- [ ] No references remain (grep verification)
+- [ ] Removals documented in commit message
+- [ ] High-risk removals discussed with team before execution
+
+---
+
+**Template Version:** 3.0.0 (Added sections 8-11: Test Fixes + Infrastructure + Documentation + Cleanup)
+**Last Updated:** 2025-11-03