universal-dev-standards 3.5.1-beta.1 → 3.5.1-beta.11

package/bundled/skills/claude-code/refactoring-assistant/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: refactoring-assistant
+description: |
+  Guide refactoring decisions and large-scale code improvements.
+  Use when: refactoring code, legacy modernization, technical debt, rewrite decisions.
+  Keywords: refactor, rewrite, legacy, strangler, technical debt, 重構, 重寫, 技術債.
+---
+
+# Refactoring Assistant
+
+> **Language**: English | [繁體中文](../../../locales/zh-TW/skills/claude-code/refactoring-assistant/SKILL.md)
+
+**Version**: 1.0.0
+**Last Updated**: 2026-01-12
+**Applicability**: Claude Code Skills
+
+---
+
+## Purpose
+
+This skill provides decision frameworks for refactoring vs rewriting, large-scale refactoring patterns, and technical debt management.
+
+---
+
+## Quick Reference (YAML Compressed)
+
+```yaml
+# === DECISION: Refactor vs Rewrite ===
+decision_tree:
+  - q: "Code in production?"
+    n: "→ Consider rewrite (lower risk)"
+    y: next
+  - q: "Understand what code does?"
+    n: "→ Characterization tests first"
+    y: next
+  - q: "Test coverage >60%?"
+    n: "→ Add tests first"
+    y: next
+  - q: "Core architecture salvageable?"
+    n: "→ Strangler Fig pattern"
+    y: "→ Incremental Refactoring ✓"
+
+comparison_matrix:
+  favor_refactor: [large_codebase, good_tests, business_critical, team_knows_code, sound_arch, tight_deadline, low_risk]
+  favor_rewrite: [small_isolated, no_tests, can_tolerate_downtime, no_knowledge, flawed_arch, flexible_time, higher_risk]
+
+# === WARNING: Second-System Effect ===
+rewrite_antipatterns:
+  - "Adding features not in original"
+  - "Over-abstracting for future flexibility"
+  - "Ignoring lessons from existing system"
+quote: "The second system is the most dangerous system a person ever designs. — Fred Brooks"
+
+# === SCALE: Refactoring Strategies ===
+scales:
+  small:
+    duration: "5-15 min"
+    scope: "single method/class"
+    techniques: [extract_method, rename, inline_var, replace_magic_number]
+  medium:
+    duration: "hours-days"
+    scope: "one feature/module"
+    checklist: [define_scope, identify_entry_points, "coverage>80%", incremental_commits, communicate]
+  large:
+    duration: "weeks-months"
+    scope: "multiple modules/system"
+    patterns: [strangler_fig, branch_by_abstraction, parallel_change]
+
+# === PATTERNS: Large-Scale Refactoring ===
+strangler_fig:
+  phases:
+    1_intercept: "Request → Facade → Legacy(100%)"
+    2_migrate: "Request → Facade → [New(FeatureA), Legacy(Rest)]"
+    3_complete: "Request → New(100%) [Legacy decommissioned]"
+  checklist: [identify_interception_point, create_event_capture, implement_first_feature, route_incrementally, monitor_compare, decommission]
+
+branch_by_abstraction:
+  steps:
+    1: "Client → Abstraction(interface) → OldImpl"
+    2: "Client → Abstraction → [OldImpl, NewImpl(toggled)]"
+    3: "Client → NewImpl [OldImpl removed]"
+  principles: [all_changes_on_trunk, feature_toggles, coexist_during_transition]
+
+expand_migrate_contract:
+  phases:
+    expand: "Add new alongside old, new code uses new, old still works"
+    migrate: "Update all clients to new, verify, data migration"
+    contract: "Remove old, clean up, update docs"
+
+# === LEGACY CODE: Strategies ===
+legacy:
+  definition: "Code without tests (regardless of age)"
+  dilemma: "Need tests to change safely → Need to change to add tests"
+  solution: "Safe techniques to add tests first"
+
+characterization_tests:
+  purpose: "Capture existing behavior (not verify correctness)"
+  process:
+    1: "Call code to understand"
+    2: "Write assertion expected to FAIL"
+    3: "Run, see actual result"
+    4: "Update assertion to match actual"
+    5: "Repeat until behavior covered"
+
+seams:
+  object: "Override via polymorphism (inject test double)"
+  preprocessing: "Compile-time substitution (macros)"
+  link: "Replace at link time (DI, module replacement)"
+
+sprout_wrap:
+  sprout_method: "New logic → create new method, call from old"
+  sprout_class: "New logic evolves independently → new class"
+  wrap_method: "Add before/after → rename original, create wrapper"
+  wrap_class: "Decorate existing → decorator pattern"
+principle: "New code uses TDD; legacy untouched until tested"
+
+# === DATABASE: Refactoring ===
+db_expand_contract:
+  expand: "Add new column/table, app writes BOTH, safe to rollback"
+  migrate: "Copy data, verify consistency, app reads from new"
+  contract: "Confirm old unused, remove old, cleanup dual-write"
+
+db_scenarios:
+  rename_column: {strategy: "add→migrate→drop", risk: medium}
+  split_table: {strategy: "new+FK→migrate→adjust", risk: high}
+  merge_tables: {strategy: "new→merge→switch", risk: high}
+  change_datatype: {strategy: "new_col→convert→switch", risk: medium}
+  add_not_null: {strategy: "fill_defaults→add_constraint", risk: low}
+
+# === WORKFLOW: Safe Refactoring ===
+before: [define_success_criteria, "coverage>80%", clean_working_dir, create_branch, communicate]
+during: [one_small_change, test_after_every_change, revert_if_fail, commit_frequently, no_new_functionality]
+after: [all_tests_pass, measurably_better, docs_updated, team_reviewed, no_new_functionality]
+
+# === METRICS ===
+code_quality:
+  cyclomatic_complexity: "<10/function"
+  cognitive_complexity: "lower=better"
+  coupling: "reduce"
+  cohesion: "increase"
+  duplication: "<3%"
+
+test_quality:
+  coverage: "≥80%, don't decrease"
+  speed: "faster after refactoring"
+  flaky_count: "decrease"
+
+# === TECHNICAL DEBT ===
+quadrant: # Martin Fowler
+  prudent_deliberate: "We know this is debt"
+  reckless_deliberate: "No time for design"
+  prudent_inadvertent: "Now we know how we should have done it"
+  reckless_inadvertent: "What's layering?"
+
+priority:
+  high: {criteria: "blocks dev, frequent bugs", action: "address immediately"}
+  medium: {criteria: "slows dev, increases complexity", action: "plan next sprint"}
+  low: {criteria: "minor annoyance, isolated", action: "address opportunistically"}
+
+tracking:
+  fields: [description, impact, estimated_effort, risk_if_ignored, related_code]
+```
+
+---
+
+## Configuration Detection
+
+### Detection Order
+
+1. Check `CONTRIBUTING.md` for "Disabled Skills" section
+2. Check `CONTRIBUTING.md` for "Refactoring Standards" section
+3. If not found, **default to standard refactoring practices**
+
+---
+
+## Detailed Guidelines
+
+For complete standards, see:
+- [Refactoring Standards](../../../core/refactoring-standards.md)
+
+---
+
+## Related Standards
+
+- [Refactoring Standards](../../../core/refactoring-standards.md) - Core standard
+- [Test-Driven Development](../../../core/test-driven-development.md) - TDD refactor phase
+- [Code Review Checklist](../../../core/code-review-checklist.md) - Refactoring PR review
+- [Checkin Standards](../../../core/checkin-standards.md) - Pre-commit requirements
+- [TDD Assistant](../tdd-assistant/SKILL.md) - TDD workflow
+
+---
+
+## Version History
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 1.0.0 | 2026-01-12 | Initial release |
+
+---
+
+## License
+
+This skill is released under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
+
+**Source**: [universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)

package/bundled/skills/claude-code/release-standards/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: release-standards
+description: |
+  Semantic versioning and changelog formatting for software releases.
+  Use when: preparing releases, updating version numbers, writing changelogs.
+  Keywords: version, release, changelog, semver, major, minor, patch, 版本, 發布, 變更日誌.
+---
+
+# Release Standards
+
+> **Language**: English | [繁體中文](../../../locales/zh-TW/skills/claude-code/release-standards/SKILL.md)
+
+**Version**: 1.1.0
+**Last Updated**: 2026-01-02
+**Applicability**: Claude Code Skills
+
+---
+
+## Purpose
+
+This skill provides semantic versioning and changelog formatting standards.
+
+## Quick Reference
+
+### Semantic Versioning Format
+
+```
+MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD]
+
+Examples:
+2.3.1
+1.0.0-alpha.1
+3.2.0-beta.2+20250112
+```
+
+### Version Incrementing Rules
+
+| Component | When to Increment | Example |
+|-----------|-------------------|----------|
+| **MAJOR** | Breaking changes | 1.9.5 → 2.0.0 |
+| **MINOR** | New features (backward-compatible) | 2.3.5 → 2.4.0 |
+| **PATCH** | Bug fixes (backward-compatible) | 3.1.2 → 3.1.3 |
+
+### Pre-release Identifiers
+
+| Identifier | Stability | Audience |
+|------------|-----------|----------|
+| `alpha` | Unstable | Internal team |
+| `beta` | Mostly stable | Early adopters |
+| `rc` | Stable | Beta testers |
+
+### CHANGELOG Categories
+
+| Category | Usage |
+|----------|-------|
+| **Added** | New features |
+| **Changed** | Changes in existing functionality |
+| **Deprecated** | Soon to be removed |
+| **Removed** | Removed features |
+| **Fixed** | Bug fixes |
+| **Security** | Vulnerability fixes |
+
+## Detailed Guidelines
+
+For complete standards, see:
+- [Semantic Versioning Guide](./semantic-versioning.md)
+- [Changelog Format](./changelog-format.md)
+- [Release Workflow Guide](./release-workflow.md) - Complete release process for this project
+
+### AI-Optimized Format (Token-Efficient)
+
+For AI assistants, use the YAML format file for reduced token usage:
+- Changelog: `ai/standards/changelog.ai.yaml`
+
+## CHANGELOG Entry Format
+
+```markdown
+## [VERSION] - YYYY-MM-DD
+
+### Added
+- Add user dashboard with customizable widgets (#123)
+
+### Changed
+- **BREAKING**: Change API response format from XML to JSON
+
+### Fixed
+- Fix memory leak when processing large files (#456)
+
+### Security
+- Fix SQL injection vulnerability (CVE-2025-12345)
+```
+
+## Breaking Changes
+
+Mark breaking changes with **BREAKING** prefix:
+
+```markdown
+### Changed
+- **BREAKING**: Remove deprecated `getUserById()`, use `getUser()` instead
+```
+
+## Git Tagging
+
+```bash
+# Create annotated tag (recommended)
+git tag -a v1.2.0 -m "Release version 1.2.0"
+
+# Push tag to remote
+git push origin v1.2.0
+```
+
+## Version Ordering
+
+```
+1.0.0-alpha.1 < 1.0.0-alpha.2 < 1.0.0-beta.1 < 1.0.0-rc.1 < 1.0.0
+```
+
+---
+
+## Configuration Detection
+
+This skill supports project-specific configuration.
+
+### Detection Order
+
+1. Check `CONTRIBUTING.md` for "Disabled Skills" section
+   - If this skill is listed, it is disabled for this project
+2. Check `CONTRIBUTING.md` for "Release Standards" section
+3. If not found, **default to Semantic Versioning and Keep a Changelog format**
+
+### First-Time Setup
+
+If no configuration found and context is unclear:
+
+1. Ask the user: "This project hasn't configured release standards. Would you like to use Semantic Versioning?"
+2. After user selection, suggest documenting in `CONTRIBUTING.md`:
+
+```markdown
+## Release Standards
+
+### Versioning
+This project uses **Semantic Versioning** (MAJOR.MINOR.PATCH).
+
+### Changelog
+This project follows **Keep a Changelog** format.
+```
+
+### Configuration Example
+
+In project's `CONTRIBUTING.md`:
+
+```markdown
+## Release Standards
+
+### Versioning
+This project uses **Semantic Versioning** (MAJOR.MINOR.PATCH).
+
+### Changelog
+This project follows **Keep a Changelog** format.
+
+### Release Process
+1. Update version in package.json
+2. Update CHANGELOG.md
+3. Create git tag with `v` prefix (e.g., v1.2.0)
+4. Push tag to trigger release workflow
+```
+
+---
+
+## Related Standards
+
+- [Versioning](../../core/versioning.md)
+- [Changelog Standards](../../core/changelog-standards.md)
+- [Git Workflow](../../core/git-workflow.md)
+
+---
+
+## Version History
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 1.1.0 | 2026-01-02 | Added: Release Workflow Guide with complete release process |
+| 1.0.0 | 2025-12-24 | Added: Standard sections (Purpose, Related Standards, Version History, License) |
+
+---
+
+## License
+
+This skill is released under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
+
+**Source**: [universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)

package/bundled/skills/claude-code/release-standards/changelog-format.md

@@ -0,0 +1,239 @@
+# Changelog Format Guide
+
+> **Language**: English | [繁體中文](../../../locales/zh-TW/skills/claude-code/release-standards/changelog-format.md)
+
+**Version**: 1.0.0
+**Last Updated**: 2025-12-24
+**Applicability**: Claude Code Skills
+
+---
+
+## Purpose
+
+This document provides guidelines for writing and formatting changelog files.
+
+This standard follows [Keep a Changelog](https://keepachangelog.com/) format.
+
+## File Structure
+
+```markdown
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+### Added
+- New features not yet released
+
+## [1.2.0] - 2025-12-15
+
+### Added
+- Feature description
+
+### Changed
+- Change description
+
+### Fixed
+- Bug fix description
+
+[Unreleased]: https://github.com/user/repo/compare/v1.2.0...HEAD
+[1.2.0]: https://github.com/user/repo/compare/v1.1.0...v1.2.0
+```
+
+---
+
+## Categories
+
+| Category | Usage | When to Use |
+|----------|-------|-------------|
+| **Added** | New features | New functionality for users |
+| **Changed** | Modifications | Changes in existing functionality |
+| **Deprecated** | Soon to be removed | Features to be removed |
+| **Removed** | Removed features | Features removed in this version |
+| **Fixed** | Bug fixes | Any bug fixes |
+| **Security** | Security patches | Vulnerability fixes |
+
+---
+
+## Version Header Format
+
+```markdown
+## [VERSION] - YYYY-MM-DD
+```
+
+**Examples**:
+```markdown
+## [2.0.0] - 2025-12-15
+## [1.5.0-beta.1] - 2025-12-01
+## [Unreleased]
+```
+
+---
+
+## Entry Format
+
+```markdown
+- [Action verb] [what changed] ([reference])
+```
+
+**Examples**:
+```markdown
+### Added
+- Add user dashboard with customizable widgets (#123)
+- Add support for PostgreSQL 15 (PR #456)
+
+### Changed
+- **BREAKING**: Change API response format from XML to JSON (#789)
+- Update minimum Node.js version to 18.0 (#101)
+
+### Fixed
+- Fix memory leak when processing large files (#112)
+- Fix incorrect date formatting in reports (#134)
+```
+
+---
+
+## Breaking Changes
+
+Mark breaking changes clearly with **BREAKING** prefix:
+
+```markdown
+### Changed
+- **BREAKING**: Remove deprecated `getUserById()` method, use `getUser()` instead
+- **BREAKING**: Change configuration file format from YAML to TOML
+
+### Removed
+- **BREAKING**: Remove support for Node.js 14
+```
+
+---
+
+## Security Advisories
+
+Include severity and CVE if available:
+
+```markdown
+### Security
+- Fix SQL injection vulnerability in search endpoint (HIGH, CVE-2025-12345)
+- Fix XSS vulnerability in comment rendering (MEDIUM)
+- Update dependency `lodash` to patch prototype pollution (LOW)
+```
+
+---
+
+## Commit to Changelog Mapping
+
+| Commit Type | CHANGELOG Category | Notes |
+|-------------|-------------------|-------|
+| `feat` | **Added** | New features |
+| `fix` | **Fixed** | Bug fixes |
+| `perf` | **Changed** | Performance improvements |
+| `refactor` | *(usually omit)* | Internal changes |
+| `docs` | *(usually omit)* | Documentation only |
+| `test` | *(usually omit)* | Test only |
+| `chore` | *(usually omit)* | Maintenance |
+| `BREAKING CHANGE` | **Changed** or **Removed** | With **BREAKING** prefix |
+| `security` | **Security** | Security patches |
+| `deprecate` | **Deprecated** | Deprecation notices |
+
+---
+
+## Exclusion Rules
+
+The following should **NOT** be recorded in CHANGELOG:
+
+| Category | Examples | Reason |
+|----------|----------|--------|
+| Build outputs | `dist/`, `build/`, `bin/` | Generated files |
+| Dependencies | `node_modules/`, lock files | Auto-managed |
+| Local config | `.env`, `*.local.json` | Environment-specific |
+| IDE settings | `.vscode/`, `.idea/` | Developer preference |
+| Internal refactoring | Code style, variable names | No user impact |
+
+---
+
+## Writing Tips
+
+### Write for Users, Not Developers
+
+| Good | Bad |
+|------|-----|
+| Add dark mode theme option | Implement ThemeProvider with context |
+| Fix login timeout on slow networks | Fix race condition in AuthService |
+| Improve page load speed by 40% | Optimize SQL queries with indexes |
+
+---
+
+## Multi-Language Support
+
+### Bilingual Entries
+
+```markdown
+## [1.2.0] - 2025-12-15
+
+### Added | 新增
+- Add dark mode support
+  新增深色模式支援
+- Add CSV export feature
+  新增 CSV 匯出功能
+
+### Fixed | 修復
+- Fix login timeout issue
+  修復登入逾時問題
+```
+
+---
+
+## Automation
+
+### conventional-changelog
+
+```bash
+# Install
+npm install -g conventional-changelog-cli
+
+# Generate (append to existing)
+conventional-changelog -p angular -i CHANGELOG.md -s
+```
+
+### semantic-release
+
+```json
+// .releaserc.json
+{
+  "branches": ["main"],
+  "plugins": [
+    "@semantic-release/commit-analyzer",
+    "@semantic-release/release-notes-generator",
+    "@semantic-release/changelog",
+    "@semantic-release/git"
+  ]
+}
+```
+
+---
+
+## Related Standards
+
+- [Changelog Standards](../../../core/changelog-standards.md)
+- [Semantic Versioning Guide](./semantic-versioning.md)
+
+---
+
+## Version History
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 1.0.0 | 2025-12-24 | Added: Standard sections (Purpose, Related Standards, Version History, License) |
+
+---
+
+## License
+
+This document is released under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
+
+**Source**: [universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)