Update skill

.claude/skills/rubycritic/SKILL.md

@@ -3,72 +3,156 @@ name: rubycritic
 description: Integrate RubyCritic to analyze Ruby code quality and maintain high standards throughout development. Use when working on Ruby projects to check code smells, complexity, and duplication. Triggers include creating/editing Ruby files, refactoring code, reviewing code quality, or when user requests code analysis or quality checks.
 ---
 
-# RubyCritic Code Quality Integration
+<objective>
+Maintain high code quality standards in Ruby projects by integrating RubyCritic analysis into the development workflow. Automatically detect code smells, complexity issues, and duplication, providing actionable guidance for improvements.
+</objective>
 
-This skill integrates RubyCritic to maintain high code quality standards in Ruby projects during Claude Code sessions.
-
-## Quick Start
-
-When working on Ruby code, periodically run RubyCritic to check code quality:
+<quick_start>
+Run quality check on Ruby files:
 
 ```bash
 scripts/check_quality.sh [path/to/ruby/files]
 ```
 
-If no path is provided, it analyzes the current directory.
+If no path is provided, analyzes the current directory. The script automatically installs RubyCritic if missing.
 
-## Workflow Integration
+**Immediate feedback**:
 
-### When to Run RubyCritic
+- Overall score (0-100)
+- File ratings (A-F)
+- Specific code smells detected
+</quick_start>
 
-Run quality checks:
+<workflow>
+<automated_quality_checks>
+**Proactive analysis**: Run RubyCritic automatically after significant code changes:
 
 - After creating new Ruby files or classes
-- After significant refactoring
+- After implementing complex methods (>10 lines)
+- After refactoring existing code
+- Before marking tasks as complete
 - Before committing code
-- When user explicitly requests code quality analysis
-- After implementing complex methods or logic
 
-### Interpreting Results
+**Integration pattern**:
 
-RubyCritic provides:
+1. Make code changes
+2. Run `scripts/check_quality.sh [changed_files]`
+3. Review output for issues
+4. Address critical smells (if any)
+5. Re-run to verify improvements
+6. Proceed with next task
 
-- **Overall Score**: Project-wide quality rating (0-100)
-- **File Ratings**: A-F letter grades per file
-- **Code Smells**: Specific issues detected by Reek
-- **Complexity**: Flog scores indicating method complexity
-- **Duplication**: Flay scores showing code duplication
+**When to skip**: Simple variable renames, comment changes, or minor formatting adjustments don't require quality checks.
+</automated_quality_checks>
 
-### Quality Thresholds
+<interpreting_results>
+**Overall Score**:
 
-Aim for:
+- 95+ (excellent) - Maintain this standard
+- 90-94 (good) - Minor improvements possible
+- 80-89 (acceptable) - Consider refactoring
+- Below 80 - Prioritize improvements
 
-- **Overall Score**: 95+ (excellent), 90+ (good), 80+ (acceptable)
-- **File Ratings**: A or B ratings for all files
-- **No Critical Smells**: Address any high-priority issues immediately
+**File Ratings**:
 
-### Responding to Issues
+- A/B - Acceptable quality
+- C - Needs attention
+- D/F - Requires refactoring
 
-When RubyCritic identifies problems:
+**Issue Types**:
 
-1. **Review the console output** for specific issues
-2. **Prioritize critical smells** (complexity, duplication, unclear naming)
-3. **Refactor incrementally** - fix issues one at a time
-4. **Re-run analysis** after each fix to verify improvement
-5. **Explain changes** to the user if quality improves significantly
+- **Code Smells** (Reek) - Design and readability issues
+- **Complexity** (Flog) - Overly complex methods
+- **Duplication** (Flay) - Repeated code patterns
+</interpreting_results>
 
-## Installation Handling
+<responding_to_issues>
+**Priority order**:
 
-The check_quality.sh script automatically:
+1. **Critical smells** - Long parameter lists, high complexity, feature envy
+2. **Duplication** - Extract shared methods or modules
+3. **Minor smells** - Unused parameters, duplicate method calls
+4. **Style issues** - Naming, organization
 
-- Detects if RubyCritic is installed
-- Installs it if missing (with user awareness)
-- Uses bundler if Gemfile is present
-- Falls back to system gem installation
+**Incremental fixing**:
+
+- Fix one issue at a time
+- Run analysis after each fix
+- Verify score improves
+- Explain significant improvements to user
+
+**When scores drop**:
+
+- Identify which file/method caused the drop
+- Review recent changes in that area
+- Fix immediately before continuing
+- Don't accumulate technical debt
+</responding_to_issues>
+
+<error_handling>
+**Common errors and solutions**:
+
+**"RubyCritic not found"**: Script auto-installs, but if it fails:
+
+- Check Ruby is installed: `ruby --version`
+- Manually install: `gem install rubycritic`
+- Or add to Gemfile: `gem 'rubycritic', require: false`
+
+**"No files to analyze"**: Verify path contains `.rb` files
+
+- Check path is correct
+- Use explicit path: `scripts/check_quality.sh app/models`
+
+**"Bundler error"**: Gemfile.lock conflict
+
+- Run `bundle install` first
+- Or use system gem: `gem install rubycritic && rubycritic [path]`
+
+**Analysis hangs**: Large codebase
 
-## Configuration
+- Analyze specific directories instead of entire project
+- Use `--no-browser` flag to skip HTML generation
+- Consider `.rubycritic.yml` to exclude paths
 
-RubyCritic respects `.rubycritic.yml` if present in the project. For custom configuration, create this file with options like:
+For additional error scenarios, see [references/error-handling.md](references/error-handling.md)
+</error_handling>
+</workflow>
+
+<git_hooks_integration>
+**Pre-commit quality checks**: Automatically run RubyCritic before commits:
+
+```bash
+# .git/hooks/pre-commit
+#!/bin/bash
+# Get staged Ruby files
+RUBY_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep '\.rb$')
+
+if [ -n "$RUBY_FILES" ]; then
+  echo "Running RubyCritic on staged files..."
+  scripts/check_quality.sh $RUBY_FILES
+
+  if [ $? -ne 0 ]; then
+    echo "Quality check failed. Fix issues or use --no-verify to skip."
+    exit 1
+  fi
+fi
+```
+
+**CI integration**: Add to GitHub Actions, GitLab CI, or other CI systems:
+
+```yaml
+# .github/workflows/quality.yml
+- name: Run RubyCritic
+  run: |
+    gem install rubycritic
+    rubycritic --format json --minimum-score 90
+```
+
+For complete git hooks setup and CI examples, see [references/git-hooks.md](references/git-hooks.md)
+</git_hooks_integration>
+
+<configuration>
+**Basic configuration** (`.rubycritic.yml`):
 
 ```yaml
 minimum_score: 95
@@ -80,21 +164,102 @@ paths:
 no_browser: true
 ```
 
-## Output Formats
+**Common options**:
+
+- `minimum_score`: Fail if score below this threshold
+- `formats`: Output formats (console, html, json)
+- `paths`: Directories to analyze
+- `no_browser`: Don't auto-open HTML report
+
+For advanced configuration and custom thresholds, see [references/configuration.md](references/configuration.md)
+</configuration>
+
+<common_patterns>
+**Quick quality check during development**:
+
+```bash
+# Check recently modified files
+scripts/check_quality.sh $(git diff --name-only | grep '\.rb$')
+```
+
+**Generate detailed HTML report**:
+
+```bash
+bundle exec rubycritic --format html app/
+# Opens browser with detailed analysis
+```
+
+**Compare with main branch** (CI mode):
+
+```bash
+rubycritic --mode-ci --branch main app/
+# Shows only changes from main branch
+```
+
+**Check specific file types**:
+
+```bash
+scripts/check_quality.sh app/models/*.rb
+scripts/check_quality.sh app/services/**/*.rb
+```
+
+</common_patterns>
 
-The script uses console format by default for inline feedback. For detailed reports:
+<code_smell_reference>
+For detailed examples of common code smells and how to fix them, see [references/code_smells.md](references/code_smells.md)
+
+**Quick reference**:
+
+- **Control Parameter** - Replace boolean params with separate methods
+- **Feature Envy** - Move method to the class it uses most
+- **Long Parameter List** - Use parameter objects or hashes
+- **High Complexity** - Extract methods, use early returns
+- **Duplication** - Extract to shared methods or modules
+</code_smell_reference>
+
+<installation>
+**Automatic installation**: The `check_quality.sh` script handles installation automatically:
+
+- Detects if RubyCritic is installed
+- Uses bundler if Gemfile present
+- Falls back to system gem installation
+- Adds to Gemfile development group if needed
+
+**Manual installation**:
+
+With Bundler:
+
+```ruby
+# Gemfile
+group :development do
+  gem 'rubycritic', require: false
+end
+```
+
+System-wide:
+
+```bash
+gem install rubycritic
+```
 
-- HTML report: `rubycritic --format html [paths]`
-- JSON output: `rubycritic --format json [paths]`
+</installation>
 
-## Best Practices
+<success_criteria>
+RubyCritic is successfully integrated when:
 
-1. **Run early and often** - Catch issues before they multiply
-2. **Address issues immediately** - Don't let technical debt accumulate
-3. **Explain to users** - When fixing quality issues, briefly explain what was improved
-4. **Set baselines** - On new projects, establish quality standards early
-5. **CI mode** - For comparing branches: `--mode-ci --branch main`
+- Quality checks run automatically after significant code changes
+- Overall score maintained at 90+ (or project-defined threshold)
+- Critical code smells addressed immediately
+- Quality improvements explained to user when significant
+- No quality regressions introduced by changes
+- Files maintain A or B ratings
+</success_criteria>
 
-## Bundled Resources
+<reference_guides>
+**Detailed references**:
 
-- **scripts/check_quality.sh**: Automated quality check with installation handling
+- [references/code_smells.md](references/code_smells.md) - Common smells and fixes with examples
+- [references/configuration.md](references/configuration.md) - Advanced RubyCritic configuration
+- [references/git-hooks.md](references/git-hooks.md) - Pre-commit hooks and CI integration
+- [references/error-handling.md](references/error-handling.md) - Troubleshooting common errors
+</reference_guides>