Initial commit

2025-11-30 08:48:32 +08:00
commit b0bc2cf2e3
11 changed files with 2373 additions and 0 deletions
--- a/skills/update-pr/EXAMPLES.md
+++ b/skills/update-pr/EXAMPLES.md
@@ -0,0 +1,271 @@
+# PR Description Examples
+
+Examples of comprehensive vs incomplete PR descriptions.
+
+## Good Example: Complete Coverage
+
+This example shows a PR that properly documents multiple categories of changes:
+
+```markdown
+## Summary
+
+Refactors UserService to eliminate 600 lines of duplication by extracting common
+validation logic. Additionally includes critical bug fixes for session handling,
+EF Core query optimization, and test infrastructure improvements.
+
+## User Impact
+
+**User Management:**
+- More consistent validation behavior across all user operations
+- Better error messages when validation fails
+
+**Reliability:**
+- Bug fix: Sessions no longer expire prematurely during long operations
+- Bug fix: Race condition in concurrent user updates resolved
+
+**Performance:**
+- 40% faster user lookup queries through optimized includes
+
+## Technical Notes
+
+### 1. UserService Refactoring
+
+Extracted common validation logic into `UserValidationService`:
+
+- **Before**: 3 nearly-identical validation methods across `Create`, `Update`, `Import`
+- **After**: Single `ValidateUser()` method with operation-specific extensions
+- **Files**: `UserService.cs`, `UserValidationService.cs` (new)
+
+### 2. Bug Fixes
+
+**Session Expiration (Critical)**
+- **Location**: `SessionManager.cs:125`
+- **Problem**: Timeout calculated from session start, not last activity
+- **Impact**: Users logged out during long form submissions
+- **Fix**: Track last activity timestamp, reset on each request
+
+**Concurrent Update Race Condition**
+- **Location**: `UserRepository.cs:89`
+- **Problem**: No optimistic concurrency on user updates
+- **Impact**: Last write wins, potentially losing data
+- **Fix**: Added `RowVersion` column with EF Core concurrency token
+
+### 3. Query Optimization
+
+- **Location**: `UserRepository.cs:45`
+- **Problem**: N+1 query pattern when loading users with roles
+- **Fix**: Added explicit `.Include(u => u.Roles)` with split query
+- **Measured**: 40% reduction in query time for user list endpoint
+
+### 4. Test Infrastructure
+
+- New `UserTestFixture` base class for consistent test setup
+- Extracted common assertions to `UserAssertions` helper
+- Added integration test for concurrent update scenario
+
+### 5. Configuration
+
+- Added `SessionTimeoutMinutes` to `appsettings.json` (default: 30)
+- New `ConcurrencyRetryCount` setting for optimistic concurrency retries
+
+## Testing
+
+```
+Total: 127 tests
+Passed: 127
+Failed: 0
+New tests: 8
+```
+
+- Unit tests for validation extraction
+- Integration test for session timeout behavior
+- Concurrency test for race condition fix
+
+## Implementation Approach
+
+1. **feat: extract user validation service** - Core refactoring work
+2. **fix: session timeout calculation** - Critical bug fix
+3. **fix: add optimistic concurrency to user updates** - Race condition fix
+4. **perf: optimize user query includes** - Query performance
+5. **test: add user service test fixtures** - Test infrastructure
+6. **chore: add session configuration** - Configuration changes
+
+---
+
+Generated with [Claude Code](https://claude.com/claude-code)
+```
+
+### Why This Is Good
+
+- Documents ALL commits, not just the main feature
+- Bug fixes are prominently highlighted with impact
+- Performance improvement is measured and documented
+- Test coverage is quantified
+- Configuration changes are noted
+- Each section has specific file references
+
+---
+
+## Bad Example: Incomplete Coverage
+
+This example shows what to avoid:
+
+```markdown
+## Summary
+
+Refactors UserService to eliminate duplication.
+
+## Technical Notes
+
+- New base class
+- Moved duplicate code
+- Tests passing
+
+## Testing
+
+All tests pass.
+```
+
+### Why This Is Bad
+
+- **Missing bug fixes**: The session and concurrency fixes aren't mentioned
+- **No impact context**: Doesn't explain WHY the refactoring matters
+- **Vague descriptions**: "Moved duplicate code" tells reviewers nothing
+- **Missing commits**: Only describes 1 of 6 commits
+- **No configuration changes**: Settings changes completely omitted
+- **No performance details**: Query optimization not mentioned
+- **No file references**: Reviewers don't know where to look
+
+---
+
+## Example: Feature with Multiple Side Effects
+
+When a feature PR includes necessary side effects:
+
+### Good
+
+```markdown
+## Summary
+
+Adds export-to-CSV functionality for reports. Also fixes date formatting
+inconsistency discovered during development and adds missing null checks
+in the report generator.
+
+## User Impact
+
+**New Feature:**
+- Users can now export any report to CSV format
+- Supports all report types (daily, weekly, monthly)
+
+**Bug Fixes:**
+- Dates now display consistently in user's timezone across all reports
+- Reports no longer fail when optional fields are null
+
+## Technical Notes
+
+### 1. CSV Export Feature
+[Details of main feature]
+
+### 2. Date Formatting Fix
+- **Location**: `DateFormatter.cs:45`
+- **Problem**: Some dates used UTC, others used local time
+- **Fix**: Standardized on user's configured timezone
+
+### 3. Null Safety
+- **Location**: `ReportGenerator.cs:112, 156, 203`
+- **Problem**: Null reference exceptions on optional fields
+- **Fix**: Added null-conditional operators and default values
+```
+
+### Bad
+
+```markdown
+## Summary
+
+Adds CSV export for reports.
+
+## Changes
+
+- Added ExportService
+- Updated ReportController
+- Fixed some bugs
+```
+
+The bad version:
+- Hides important bug fixes under "Fixed some bugs"
+- Doesn't explain the impact of the bugs that were fixed
+- Reviewers might miss that this PR changes date behavior
+
+---
+
+## Example: Infrastructure-Heavy PR
+
+When the main work is test/infrastructure improvements:
+
+### Good
+
+```markdown
+## Summary
+
+Overhauls test infrastructure to support parallel execution, reducing CI
+time from 12 minutes to 4 minutes. Includes migration of 45 test classes
+to new fixture pattern.
+
+## User Impact
+
+**Developer Experience:**
+- CI feedback 3x faster
+- Local test runs significantly quicker
+- Tests now properly isolated (no more flaky failures)
+
+## Technical Notes
+
+### 1. Parallel Test Execution
+- **Problem**: Tests ran sequentially due to shared database state
+- **Solution**: New `IsolatedDatabaseFixture` creates per-test databases
+- **Result**: Full parallelization across all CPU cores
+
+### 2. Test Migration
+- Migrated 45 test classes to new fixture pattern
+- Removed hardcoded IDs that caused parallel conflicts
+- Added scoped assertions that filter to test-created data
+
+### 3. Performance Results
+| Metric | Before | After |
+|--------|--------|-------|
+| CI Duration | 12:34 | 4:12 |
+| Local (8 cores) | 8:45 | 1:23 |
+| Flaky test rate | 12% | 0% |
+
+## Testing
+
+All 312 tests pass in parallel mode.
+```
+
+### Bad
+
+```markdown
+## Summary
+
+Updated tests.
+
+## Changes
+
+- Changed test base class
+- Updated 45 files
+```
+
+---
+
+## Checklist for Complete Coverage
+
+Before finalizing your PR description, verify:
+
+- [ ] Every commit message is reflected in the description
+- [ ] Bug fixes are prominently documented (not hidden)
+- [ ] Performance improvements include measurements
+- [ ] Configuration changes are listed
+- [ ] Test coverage changes are quantified
+- [ ] File paths are included for key changes
+- [ ] User impact is clearly separated from technical details
+- [ ] "Why" is explained, not just "what"
--- a/skills/update-pr/README.md
+++ b/skills/update-pr/README.md
@@ -0,0 +1,60 @@
+# Update PR Skill
+
+> Creates comprehensive PR descriptions by systematically reviewing all changes
+
+## Overview
+
+This skill helps Claude create thorough PR descriptions that document every meaningful change in a branch - not just the headline feature, but also bug fixes, test improvements, configuration changes, and documentation updates.
+
+**For complete plugin documentation, see the [main README](../../README.md).**
+
+## Quick Reference
+
+**Example prompts:**
+```
+"Update the PR description"
+"Prepare this PR for review"
+"Document the changes in this branch"
+"Write a comprehensive PR summary"
+```
+
+**What it does:**
+- Systematically inventories ALL changed files and commits
+- Categorizes changes (features, fixes, tests, docs, config)
+- Creates structured PR descriptions with user impact section
+- Saves to `/tmp/pr-summary.md` and updates PR via `gh pr edit`
+
+**Allowed tools:** Bash, Read, Write, Edit, Glob, Grep
+
+## How It Works
+
+The skill runs a 5-phase workflow:
+
+1. **Inventory** - Detects base branch (from PR or default), runs git diff/log commands
+2. **Categorization** - Groups files by type (core, fixes, tests, docs, config)
+3. **Analysis** - Reviews each commit to understand what/why/impact
+4. **Documentation** - Creates structured PR description
+5. **Update** - Saves to temp file, optionally updates PR
+
+See [SKILL.md](SKILL.md) for the complete workflow details.
+
+## Tips for Best Results
+
+1. **Let it run all phases** - Don't interrupt the systematic review
+2. **Review before updating** - Claude will show you the summary first
+3. **Provide context** - Mention important context Claude can't see in the code
+4. **Base branch detection** - Uses PR's actual base branch (supports release backports, non-default targets)
+
+## Requirements
+
+- **gh CLI** - GitHub's official CLI, authenticated
+- **Git** - For diff and log commands
+
+## Documentation
+
+- **[SKILL.md](SKILL.md)** - Complete workflow for Claude
+- **[EXAMPLES.md](EXAMPLES.md)** - Good vs bad PR description examples
+
+## License
+
+MIT - See [LICENSE](../../LICENSE)
--- a/skills/update-pr/SKILL.md
+++ b/skills/update-pr/SKILL.md
@@ -0,0 +1,256 @@
+---
+name: update-pr
+description: Creates comprehensive PR descriptions by systematically reviewing ALL changes - features, bug fixes, tests, docs, and infrastructure. Use when user wants to update PR description, prepare PR for review, or document branch changes. Requires gh CLI.
+allowed-tools: [Bash, Read, Write, Edit, Glob, Grep]
+# Note: Glob/Grep are useful for finding files by pattern (e.g., *Test*.cs)
+# and searching code content when categorizing changes.
+---
+
+# Comprehensive PR Description Creator
+
+Create thorough PR descriptions that document EVERY meaningful change, not just the headline feature.
+
+## Critical Rule: Complete Coverage
+
+**NEVER assume you know what's in the PR based on branch name or first glance.**
+
+PRs often contain:
+- Main feature work
+- Bug fixes discovered during development
+- Performance optimizations
+- Test infrastructure improvements
+- Documentation updates
+- Dependency changes
+- Configuration adjustments
+
+You MUST systematically review ALL changes and include them in the summary.
+
+## Phase 1: Complete Change Inventory
+
+First, determine the base branch for comparison:
+
+```bash
+# Get base branch from current PR (if one exists), otherwise fall back to default branch
+BASE_BRANCH=$( \
+  gh pr view --json baseRefName -q '.baseRefName' 2>/dev/null || \
+  git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null || \
+  echo 'refs/remotes/origin/main' \
+)
+BASE_BRANCH="${BASE_BRANCH#refs/remotes/origin/}"
+```
+
+Then gather context (using `$BASE_BRANCH` from above). These commands are independent and can be run as separate tool calls:
+
+**PR and working tree status:**
+```bash
+gh pr status
+```
+
+```bash
+git status --short
+```
+
+**Changed files:**
+```bash
+git diff origin/$BASE_BRANCH...HEAD --stat
+git diff origin/$BASE_BRANCH...HEAD --name-status
+```
+
+**Commit history:**
+```bash
+git log origin/$BASE_BRANCH..HEAD --oneline --no-merges
+```
+
+**Note**: Using the PR's actual base branch ensures accurate diffs for release backports or PRs targeting non-default branches.
+
+## Phase 2: Systematic File Analysis
+
+Using the `--name-status` output, create a categorized inventory of EVERY changed file:
+
+### 2.1 Core Application Changes
+- Check files matching your framework patterns (e.g., `*Service*`, `*Controller*`, `*Component*`)
+- Look for: new methods, refactoring, bug fixes, performance improvements
+- Read key diffs to understand WHAT changed and WHY
+
+### 2.2 Bug Fixes & Corrections
+- Scan commit messages for: "fix", "bug", "correct", "resolve"
+- Read diffs for files mentioned in fix commits
+- Document: what was broken, what was fixed, impact
+
+### 2.3 Infrastructure & Framework
+- Check: interceptors, middleware, base classes, test fixtures
+- Look for: new patterns, performance improvements, testing infrastructure
+- These are often overlooked but important
+
+### 2.4 Configuration Changes
+- Check: config files, constants, environment settings, package files
+- Look for: new constants, dependency changes, configuration adjustments
+- Even small changes here can be significant
+
+### 2.5 Test Files
+- Count new test files vs modified test files
+- Check for: new test patterns, test infrastructure, coverage improvements
+- Document test coverage added
+
+### 2.6 Documentation
+- Check: README files, docs folders, inline documentation
+- Look for: new documentation, removed obsolete content, updated instructions
+
+### 2.7 Build & Tooling
+- Check: package.json, build configs, CI/CD files, scripts
+- Look for: dependency updates, new tooling, build process changes
+
+### 2.8 UI/Frontend Changes
+- Check: components, styles, state management
+- Look for: new components, UI fixes, styling changes
+
+## Phase 3: Commit-by-Commit Review
+
+For EACH commit in `git log`:
+
+1. Read the commit message - it tells you WHAT category of change
+2. Identify which files were changed in that commit
+3. Read diffs for key files to understand the WHY
+4. Note if commit is: feature, bugfix, test, docs, refactor, perf, chore
+
+**Common prefixes:**
+- `fix:` = bug fix (HIGH PRIORITY - always include)
+- `feat:` = feature (main work)
+- `test:` = test infrastructure
+- `docs:` = documentation
+- `perf:` = performance optimization
+- `refactor:` = code organization
+- `chore:` = maintenance tasks
+
+## Phase 4: Verification Checklist
+
+Before writing the summary, confirm you've checked:
+
+- [ ] ALL commits reviewed and categorized
+- [ ] Core application changes documented
+- [ ] Bug fixes identified and explained
+- [ ] Infrastructure/framework changes noted
+- [ ] Configuration changes included
+- [ ] Test coverage quantified
+- [ ] Documentation updates listed
+- [ ] Build/tooling changes noted
+
+**If you cannot check ALL boxes, you are not done gathering data.**
+
+## Phase 5: Write Comprehensive Summary
+
+Structure your summary to cover ALL categories of changes.
+
+### Template Structure
+
+```markdown
+## Summary
+
+[One sentence covering the MAIN change, plus brief mention of other significant improvements]
+
+## User Impact
+
+**[Main Feature Category]:**
+- [Specific user-facing improvements]
+
+**[Secondary Categories if applicable - e.g., Reliability, Performance]:**
+- [Bug fixes with impact]
+- [Performance improvements]
+
+## Technical Notes
+
+### 1. [Main Feature Name]
+[Detailed explanation of main feature with file references]
+
+### 2. [Bug Fixes / Corrections]
+[Each bug fix with location, what was wrong, impact, fix]
+
+### 3. [Infrastructure / Performance]
+[Test improvements, framework changes, optimizations]
+
+### 4. [Configuration & Dependencies]
+[Constants, config changes, dependency updates]
+
+### 5. [Documentation]
+[README updates, new docs, removed obsolete content]
+
+## Testing
+
+[Comprehensive test results with specific numbers]
+
+## Implementation Approach
+
+[List ALL commits with brief explanation of each]
+
+1. **[commit message]** - [what it did]
+2. **[commit message]** - [what it did]
+...
+
+## Next Steps
+
+[Only if applicable]
+
+---
+
+Generated with [Claude Code](https://claude.com/claude-code)
+```
+
+## Quality Checklist
+
+Before finalizing, verify:
+
+- **Completeness**: Every commit is represented in the summary
+- **Accuracy**: All bug fixes are documented with impact
+- **Context**: WHY changes were made, not just WHAT changed
+- **Organization**: Changes grouped logically (features, bugs, infrastructure, etc.)
+- **Specificity**: File paths for critical changes
+- **Impact**: User-facing vs internal changes clearly separated
+- **Testing**: Actual test results reported, not assumptions
+
+## Output Instructions
+
+1. **Save to temporary file**: Write the summary to `/tmp/pr-summary.md` (avoids cluttering repo)
+2. **Self-review**: Read your summary and verify all commits and file categories are covered
+3. **User approval**: Show the summary and ask if they want to update the PR
+4. **Update PR** (only if user approves):
+   ```bash
+   gh pr edit --body-file /tmp/pr-summary.md
+   ```
+
+## Common Mistakes to Avoid
+
+- **Focusing only on main feature** - PRs often contain multiple types of changes
+- **Skipping "small" changes** - Constants, config, and doc changes matter
+- **Ignoring bug fixes** - These are often HIGH PRIORITY to document
+- **Missing test infrastructure** - Test improvements affect development velocity
+- **Incomplete commit review** - Every commit tells part of the story
+- **Vague descriptions** - "Updated files" tells reviewers nothing
+
+## Troubleshooting
+
+**No PR exists yet:**
+```bash
+# Create PR first
+gh pr create --title "Title" --body "WIP"
+# Then run the update process
+```
+
+**Verify base branch:**
+```bash
+# Check what base branch the PR is targeting
+gh pr view --json baseRefName -q '.baseRefName'
+
+# Or detect default branch if no PR exists (with guaranteed fallback)
+BASE=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null || echo 'refs/remotes/origin/main')
+echo "${BASE#refs/remotes/origin/}"
+```
+
+**gh CLI not authenticated:**
+```bash
+gh auth status
+gh auth login
+```
+
+---
+
+**Remember**: The PR may contain a week's worth of work across multiple areas. Your job is to tell the complete story, not just the headline feature.