zhongwei/gh-levnikolaevich-claude-code-skills-full-development-workflow-skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:37:27 +08:00
commit 37774aa937
131 changed files with 31137 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

69
skills/ln-311-task-creator/SKILL.md Normal file
View File

@@ -0,0 +1,69 @@
---
name: ln-311-task-creator
description: Creates ALL task types (implementation, refactoring, test). Generates task documents from templates, validates type rules, creates in Linear, updates kanban. Invoked by orchestrators.
---
# Universal Task Creator
Worker that generates task documents and creates Linear issues for implementation, refactoring, or test tasks as instructed by orchestrators.
## Purpose & Scope
- Owns all task templates and creation logic (Linear + kanban updates)
- Generates full task documents per type (implementation/refactoring/test)
- Enforces type-specific hard rules (no new tests in impl, regression strategy for refactoring, risk matrix and limits for test)
- Drops NFR bullets if supplied; only functional scope becomes tasks
- Never decides scope itself; uses orchestrator input (plans/results)
## Invocation (who/when)
- **ln-310-story-decomposer:** CREATE (no tasks) or ADD (appendMode) for implementation tasks.
- **ln-340-story-quality-gate:** Create refactoring task when issues found.
- **ln-350-story-test-planner:** Create final test task after manual testing.
- Never called directly by users.
## Inputs
- Common: `taskType`, teamId, Story data (id/title/description with AC, Technical Notes, Context).
- Implementation CREATE: idealPlan (1-6 tasks), guideLinks.
- Implementation ADD: appendMode=true, newTaskDescription, guideLinks.
- Refactoring: codeQualityIssues, refactoringPlan, affectedComponents.
- Test: manualTestResults, testPlan (E2E 2-5, Integration 0-8, Unit 0-15, Priority ≤15), infra/doc/cleanup items.
## Workflow (concise)
1) **Context check:** For implementation (or ADD) review existing code/db/deps/docs to avoid duplicating components or columns; reuse instead of recreate.
2) **Template select:** Read template from `references/` based on taskType.
3) **Generate docs:** Fill sections for each task in plan/request using provided data and guide links.
4) **Validate type rules:** Stop with error if violation (see table below).
5) **Preview:** Show titles/goals/estimates/AC/components and totals.
6) **Confirmation required:** Proceed only after explicit confirm.
7) **Create issues:** Call Linear create_issue with parentId=Story, state=Backlog; capture URLs.
8) **Update kanban:** Add under Story in Backlog with correct Epic/indent.
9) **Return summary:** URLs, counts, hours, guide link count; next steps (validator/executor).
## Type Rules (must pass)
| taskType | Hard rule | What to verify |
|----------|-----------|----------------|
| implementation | No new test creation | Scan text for "write/create/add tests" etc.; allow only updating existing tests |
| refactoring | Regression strategy required | Issues listed with severity; plan in 3 phases; regression strategy (Baseline/Verify/Failure); preserve functionality |
| test | Risk-based plan required | Priority ≤15 scenarios; E2E 2-5, Integration 0-8, Unit 0-15, Total 10-28; no framework/library/DB tests |
## Critical Notes
- Foundation-First order for implementation is preserved from orchestrator; do not reorder.
- No code snippets; keep to approach, APIs, and pseudocode only.
- Documentation updates must be included in Affected Components/Docs sections.
- Language preservation: keep Story language (EN/RU) in generated tasks.
## Definition of Done
- Context check complete (existing components/schema/deps/docs reviewed; conflicts flagged).
- Documents generated with correct template and full sections.
- Type validation passed (no test creation for impl; regression strategy for refactor; risk matrix/limits for test).
- Preview shown and user confirmed.
- Linear issues created with parentId and URLs captured; state=Backlog.
- kanban_board.md updated under correct Epic/Story with indentation.
- Summary returned with URLs, totals, and next steps.
## Reference Files
- Templates (owned here): `references/task_template_implementation.md`, `references/refactoring_task_template.md`, `references/test_task_template.md`
- Kanban format: `docs/tasks/kanban_board.md`
---
Version: 5.0.0 (Condensed workflow, tabled type rules)
Last Updated: 2025-11-26

94
skills/ln-311-task-creator/diagram.html Normal file
View File

@@ -0,0 +1,94 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>ln-311-task-creator - Universal Factory</title>
<script src="https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"></script>
<link rel="stylesheet" href="../shared/css/diagram.css">
</head>
<body>
<div class="container">
<header>
<h1>ln-311-task-creator</h1>
<p class="subtitle">Universal Factory - Worker v1.0.0</p>
</header>
<div class="info-box">
<h2>Overview</h2>
<ul>
<li><strong>Purpose:</strong> Universal factory worker for creating ALL 3 task types (implementation, refactoring, test)</li>
<li><strong>Pattern:</strong> Worker v1.0.0 - Invoked by orchestrator (x-task-manager) via Skill tool with taskType parameter</li>
<li><strong>Templates:</strong>
<ul>
<li><code>implementation</code> → task_template_implementation.md (7 sections)</li>
<li><code>refactoring</code> → refactoring_task_template.md (7 sections)</li>
<li><code>test</code> → test_task_template.md (11 sections)</li>
</ul>
</li>
<li><strong>Type-Specific Validation:</strong>
<ul>
<li><code>implementation</code>: NO tests (tests in final Story task)</li>
<li><code>refactoring</code>: Regression Strategy required</li>
<li><code>test</code>: Priority ≥15 scenarios + Limits (2-5 E2E, 3-8 Integration, 5-15 Unit)</li>
</ul>
</li>
<li><strong>Input:</strong> IDEAL plan + guide links from orchestrator</li>
<li><strong>Output:</strong> Task URLs + summary → return to orchestrator</li>
</ul>
</div>
<div class="diagram-container">
<div class="mermaid">
graph TD
Start([Invoked by orchestrator<br/>taskType parameter]) --> SelectTemplate{Select Template<br/>by taskType}
SelectTemplate -->|implementation| T1[task_template_implementation.md<br/>7 sections]
SelectTemplate -->|refactoring| T2[refactoring_task_template.md<br/>7 sections]
SelectTemplate -->|test| T3[test_task_template.md<br/>11 sections]
T1 --> Phase1
T2 --> Phase1
T3 --> Phase1
Phase1[Phase 1: Generate Task Documents<br/>From IDEAL plan<br/>Fill template sections]
Phase1 --> Phase2{Phase 2: Type-Specific Validation<br/>implementation: NO tests<br/>refactoring: Regression Strategy<br/>test: Priority ≥15 + Limits}
Phase2 -->|Validation failed| Error([ERROR: Stop execution<br/>Report to orchestrator])
Phase2 -->|Validation passed| Phase3[Phase 3: Show Preview<br/>Task summaries<br/>Total count & hours]
Phase3 --> Phase4{Phase 4: User Confirmation}
Phase4 -->|"confirm"| Phase5[Phase 5: Create in Linear<br/>+ Update kanban_board.md]
Phase4 -->|Other input| Abort([Abort: Return to orchestrator])
Phase5 --> Success([SUCCESS<br/>Return task URLs + summary])
style Start fill:#e1f5fe
style Success fill:#c8e6c9
style Error fill:#ffcdd2
style Abort fill:#fff9c4
style SelectTemplate fill:#e1bee7
style T1 fill:#c8e6c9
style T2 fill:#fff3e0
style T3 fill:#ffcdd2
style Phase2 fill:#fff3e0
style Phase4 fill:#fff3e0
</div>
</div>
<footer>
<p>ln-311-task-creator v1.0.0 | Universal Factory Pattern | Mermaid.js</p>
</footer>
</div>
<script>
mermaid.initialize({
startOnLoad: true,
theme: 'default',
flowchart: {
useMaxWidth: true,
htmlLabels: true,
curve: 'basis'
}
});
</script>
</body>
</html>

515
skills/ln-311-task-creator/references/refactoring_task_template.md Normal file
View File

@@ -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

146
skills/ln-311-task-creator/references/task_template_implementation.md Normal file
View File

@@ -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

542
skills/ln-311-task-creator/references/test_task_template.md Normal file
View File

@@ -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