claude_memory 0.13.1 → 0.13.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (41) hide show
  1. checksums.yaml +4 -4
  2. data/.claude-plugin/marketplace.json +1 -1
  3. data/.claude-plugin/plugin.json +1 -1
  4. data/CHANGELOG.md +15 -0
  5. data/docs/improvements.md +4 -0
  6. data/lib/claude_memory/commands/checks/fts_rank_check.rb +60 -0
  7. data/lib/claude_memory/commands/doctor_command.rb +2 -0
  8. data/lib/claude_memory/commands/index_command.rb +22 -4
  9. data/lib/claude_memory/commands/setup_vectors_command.rb +9 -3
  10. data/lib/claude_memory/index/lexical_fts.rb +47 -23
  11. data/lib/claude_memory/index/vector_index.rb +27 -0
  12. data/lib/claude_memory/mcp/server.rb +33 -1
  13. data/lib/claude_memory/sweep/maintenance.rb +22 -0
  14. data/lib/claude_memory/sweep/sweeper.rb +1 -0
  15. data/lib/claude_memory/version.rb +1 -1
  16. data/lib/claude_memory.rb +1 -0
  17. metadata +2 -25
  18. data/.claude/CLAUDE.md +0 -4
  19. data/.claude/memory.sqlite3 +0 -0
  20. data/.claude/output-styles/memory-aware.md +0 -1
  21. data/.claude/rules/claude_memory.generated.md +0 -87
  22. data/.claude/settings.json +0 -113
  23. data/.claude/settings.local.json +0 -59
  24. data/.claude/skills/check-memory/DEPRECATED.md +0 -29
  25. data/.claude/skills/check-memory/SKILL.md +0 -87
  26. data/.claude/skills/dashboard/SKILL.md +0 -42
  27. data/.claude/skills/debug-memory +0 -1
  28. data/.claude/skills/improve/SKILL.md +0 -631
  29. data/.claude/skills/improve/feature-patterns.md +0 -1221
  30. data/.claude/skills/memory-first-workflow +0 -1
  31. data/.claude/skills/quality-update/SKILL.md +0 -229
  32. data/.claude/skills/quality-update/implementation-guide.md +0 -346
  33. data/.claude/skills/release/SKILL.md +0 -206
  34. data/.claude/skills/review-commit/SKILL.md +0 -199
  35. data/.claude/skills/review-for-quality/SKILL.md +0 -154
  36. data/.claude/skills/review-for-quality/expert-checklists.md +0 -79
  37. data/.claude/skills/setup-memory +0 -1
  38. data/.claude/skills/study-repo/SKILL.md +0 -322
  39. data/.claude/skills/study-repo/analysis-template.md +0 -323
  40. data/.claude/skills/study-repo/focus-examples.md +0 -327
  41. data/.claude/skills/upgrade-dependencies/SKILL.md +0 -154
@@ -1,206 +0,0 @@
1
- ---
2
- name: release
3
- description: Prepare and publish a new gem release — bumps version across all required files, validates tests/linting/MCP server, commits, and creates the GitHub release. Use this skill when the user says "release", "publish a new version", "bump the version", "cut a release", "prepare for release", "ship it", or any variation of wanting to publish a new gem version. Also use when the user asks about the release process or what steps are needed to release.
4
- agent: general-purpose
5
- allowed-tools: Read, Grep, Edit, Write, Bash
6
- arguments:
7
- - name: version
8
- description: "The new version number (e.g., '0.10.0'). If omitted, you'll be asked."
9
- required: false
10
- ---
11
-
12
- # Release Workflow
13
-
14
- Automate the full release lifecycle for the ClaudeMemory gem. This workflow was codified from the actual 0.9.0 release process.
15
-
16
- The release has three phases: **prepare** (automated), **publish** (user-driven), and **announce** (automated). The middle phase requires user action because it pushes to a shared remote and publishes to RubyGems — destructive operations that must never happen without explicit confirmation.
17
-
18
- ## Phase 1: Prepare
19
-
20
- ### Step 1: Determine the new version
21
-
22
- If a version was passed as an argument, use it. Otherwise, read the current version from `lib/claude_memory/version.rb` and ask the user what the new version should be.
23
-
24
- ### Step 2: Find and update all version references
25
-
26
- The version lives in exactly three files. Grep to confirm there are no others:
27
-
28
- ```bash
29
- grep -rn "CURRENT_VERSION" --include="*.rb" --include="*.json" --include="*.gemspec" . | grep -v "CHANGELOG\|node_modules\|vendor\|\.git/"
30
- ```
31
-
32
- Update all three:
33
-
34
- 1. **`lib/claude_memory/version.rb`** — the `VERSION` constant (canonical source)
35
- 2. **`.claude-plugin/plugin.json`** — the `"version"` field
36
- 3. **`.claude-plugin/marketplace.json`** — the `"version"` field inside the plugins array
37
-
38
- If grep reveals any additional hardcoded references, update those too and flag them to the user as something that should be DRYed up.
39
-
40
- ### Step 3: Update Gemfile.lock
41
-
42
- ```bash
43
- bundle install
44
- ```
45
-
46
- Verify both `claude_memory (X.Y.Z)` entries in Gemfile.lock match the new version.
47
-
48
- ### Step 4: Verify MCP server reports the new version
49
-
50
- The MCP server reads `ClaudeMemory::VERSION` dynamically. Confirm it picks up the change:
51
-
52
- ```bash
53
- echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | bundle exec claude-memory serve-mcp 2>/dev/null | grep -o '"version":"[^"]*"'
54
- ```
55
-
56
- Expected output: `"version":"X.Y.Z"` matching the new version. If it doesn't match, something is wrong with the require chain — investigate before proceeding.
57
-
58
- ### Step 5: Run the full test suite
59
-
60
- ```bash
61
- bundle exec rspec
62
- ```
63
-
64
- All tests must pass. Do not proceed with any failures. Fix them first.
65
-
66
- ### Step 6: Run the pre-release hook smoke gate
67
-
68
- ```bash
69
- bin/pre-release-smoke
70
- ```
71
-
72
- This script:
73
-
74
- 1. Re-runs `bundle exec rake install` so the PATH-resolved `claude-memory` binary matches the working tree.
75
- 2. Triggers each gem-managed hook against a temp DB.
76
- 3. Verifies every field listed in `spec/smoke/expected_fields.yml` is populated on the resulting `activity_events.detail_json`.
77
- 4. Exits non-zero with the missing field name(s) and `since_version` if any expected field is null/absent.
78
-
79
- **This catches the class of bug specs cannot:** a code change that adds a new `detail_json` field but forgets `rake install`, leaving the installed gem stale and production hooks silently missing the field. Sprung that trap on 2026-04-16 (ActivityLog) and again on 2026-04-30 (#47 token-budget) — the gate is here so it can't happen a third time.
80
-
81
- If the gate fails, **stop the release**, address the missing field (usually `bundle exec rake install` followed by re-running the gate), and only proceed when it exits 0.
82
-
83
- ### Step 7: Run the benchmark scoreboard diff
84
-
85
- ```bash
86
- bin/run-evals --benchmarks
87
- bin/bench-diff
88
- ```
89
-
90
- `bin/run-evals --benchmarks` writes `spec/benchmarks/results/<version>.json` — the diff-friendly snapshot of the current release's pass rates by category and per-scenario. `bin/bench-diff` then compares that snapshot against the most recent prior tagged version's scoreboard and exits non-zero if any tracked pass-rate dropped beyond the threshold (default -5%; configurable via `--threshold`).
91
-
92
- The first release with this gate (0.12.0) has no prior scoreboard to compare against — `bench-diff` exits 0 with a "No baseline scoreboard available" note. From 0.13.0 onward it actively gates.
93
-
94
- If the diff reports a regression, **stop the release**, investigate (the regressed metric path is named in stderr — e.g. `metrics.evals.by_scenario.tech_stack_recall.pass_rate`), and only proceed once you've either (a) fixed the regression or (b) made a deliberate decision that the lower pass rate is acceptable. If (b), document the new baseline in CHANGELOG so future-you isn't surprised.
95
-
96
- For real-mode E2E coverage (~$2-8 per run), pass `EVAL_MODE=real`:
97
-
98
- ```bash
99
- EVAL_MODE=real bin/run-evals --all && bin/bench-diff
100
- ```
101
-
102
- ### Step 8: Run the linter
103
-
104
- ```bash
105
- bundle exec rake standard:fix
106
- ```
107
-
108
- Ensure no remaining violations.
109
-
110
- ### Step 9: Verify CHANGELOG.md
111
-
112
- The CHANGELOG should already have a release section written during development (via `/improve`, manual commits, or other workflow). **Do not auto-generate release notes** — they should reflect the actual development narrative.
113
-
114
- Check that:
115
- - The `## [X.Y.Z] - YYYY-MM-DD` section exists with today's date
116
- - It has Added, Changed, Fixed subsections as appropriate
117
- - Upgrade Notes are included if there are breaking changes or manual migration steps
118
- - The `## [Unreleased]` section above it is empty or ready for the next cycle
119
-
120
- If the CHANGELOG section is missing or incomplete, **stop and ask the user**. Do not fabricate release notes.
121
-
122
- ### Step 10: Commit the version bump
123
-
124
- ```bash
125
- git add lib/claude_memory/version.rb .claude-plugin/plugin.json .claude-plugin/marketplace.json Gemfile.lock
126
- git commit -m "[Release] Bump version to X.Y.Z"
127
- ```
128
-
129
- Do NOT push yet. Report what was committed and proceed to Phase 2.
130
-
131
- ## Phase 2: Publish (User-Driven)
132
-
133
- This phase involves pushing to a shared remote and publishing to RubyGems. These are **irreversible shared-state operations** — never execute them automatically.
134
-
135
- Tell the user:
136
-
137
- > Version X.Y.Z is prepared and committed locally. To publish:
138
- >
139
- > ```bash
140
- > git push origin main
141
- > rake release
142
- > ```
143
- >
144
- > `rake release` will create the git tag, build the gem, and push to RubyGems. Let me know when that's done and I'll create the GitHub release.
145
-
146
- Wait for the user to confirm before proceeding to Phase 3.
147
-
148
- ## Phase 3: Announce
149
-
150
- ### Step 11: Fix any stale "Latest" flags on GitHub releases
151
-
152
- Check current release state:
153
-
154
- ```bash
155
- gh release list --limit 5
156
- ```
157
-
158
- If an older release is incorrectly marked "Latest" (this happens when releases are created out of order or with `--latest` set manually):
159
-
160
- ```bash
161
- gh release edit v<old-version> --latest=false
162
- ```
163
-
164
- ### Step 12: Create the GitHub release
165
-
166
- Extract the release notes from CHANGELOG.md — everything between `## [X.Y.Z]` and the next `## [` heading. Write to a temp file:
167
-
168
- ```bash
169
- # Extract the section between the new version header and the next version header
170
- sed -n '/^## \[X\.Y\.Z\]/,/^## \[/{ /^## \[X\.Y\.Z\]/d; /^## \[/d; p; }' CHANGELOG.md > /tmp/release-notes.md
171
- ```
172
-
173
- Create the release:
174
-
175
- ```bash
176
- gh release create vX.Y.Z \
177
- --title "vX.Y.Z — Short descriptive title" \
178
- --latest \
179
- --verify-tag \
180
- --notes-file /tmp/release-notes.md
181
- ```
182
-
183
- The title should capture the theme of the release in a few words (e.g., "Predicate Design Overhaul, Reject/Restore, Telemetry"). Read the CHANGELOG to derive this — don't ask the user unless the theme isn't obvious.
184
-
185
- ### Step 13: Verify the release
186
-
187
- ```bash
188
- gh release list --limit 5
189
- ```
190
-
191
- Confirm:
192
- - The new release appears at the top
193
- - It's marked "Latest"
194
- - No older release is incorrectly marked "Latest"
195
-
196
- Report the release URL to the user.
197
-
198
- ## Error Handling
199
-
200
- - **Smoke gate fails (`bin/pre-release-smoke` exits non-zero)**: The script names the missing `detail_json` field and `since_version` in stderr. Most common cause: code that adds a new field landed without a follow-up `bundle exec rake install`, so the installed gem is stale. Re-run `rake install`, then re-run the gate. If the field was newly added but no `rake install` was run, that's the bug the gate is designed to catch — don't bypass it. If the manifest needs updating because a field was intentionally removed, edit `spec/smoke/expected_fields.yml` AND add a CHANGELOG breaking-change note (removing a `detail_json` field is a public API change per `docs/api_stability.md` §4).
201
- - **Bench-diff fails (`bin/bench-diff` exits 1)**: Stderr names the metric path that regressed (e.g. `metrics.evals.by_scenario.tech_stack_recall.pass_rate`). Investigate the regression — is it a real correctness issue, or a measurement-noise issue (e.g. real-mode flake)? If real, fix before releasing. If a deliberate baseline change (we knowingly traded N% in metric X for some other gain), update CHANGELOG with the new baseline and re-run with a temporarily looser `--threshold` to ship; the next release picks up the new floor automatically. **Don't bypass the gate without an explicit baseline-change note** — that defeats the entire scoreboard.
202
- - **Tests fail**: Fix first. Never release with failing tests.
203
- - **CHANGELOG missing**: Ask the user. Never fabricate release notes.
204
- - **Version already tagged**: The tag may exist from a prior attempt. Ask the user whether to delete and recreate, or use a different version.
205
- - **`gh` not available**: Tell the user to create the GitHub release manually, providing the release notes content.
206
- - **`rake release` fails**: Common causes: not logged into RubyGems, tag already exists, uncommitted changes. Help the user diagnose but don't retry automatically.
@@ -1,199 +0,0 @@
1
- ---
2
- name: review-commit
3
- description: Quick quality review of staged changes for pre-commit validation. Checks Ruby best practices and flags critical issues.
4
- agent: general-purpose
5
- allowed-tools: Bash, Read, Grep, Glob
6
- ---
7
-
8
- # Pre-Commit Quality Review
9
-
10
- Review the staged changes in this commit for code quality issues before committing.
11
-
12
- ## Objectives
13
-
14
- - **Fast**: Complete review in < 30 seconds
15
- - **Focused**: Only review staged Ruby files
16
- - **Actionable**: Clear pass/fail with specific fixes
17
- - **Non-interactive**: Works in headless mode
18
- - **Expert-driven**: Apply Ruby best practices from industry experts
19
-
20
- ## Expert Panel
21
-
22
- Apply principles from these Ruby/software design experts:
23
-
24
- 1. **Sandi Metz** - POODR principles, small methods/classes, SRP, DRY
25
- 2. **Jeremy Evans** - Sequel best practices, transaction safety, performance
26
- 3. **Kent Beck** - Simple design, revealing names, Command-Query Separation
27
- 4. **Avdi Grimm** - Confident Ruby, null objects, tell-don't-ask, meaningful returns
28
- 5. **Gary Bernhardt** - Functional core/imperative shell, fast tests, immutability
29
-
30
- ## Review Process
31
-
32
- 1. **Get staged files:**
33
- ```bash
34
- git diff --cached --name-only --diff-filter=ACM | grep '\.rb$'
35
- ```
36
-
37
- 2. **For each staged Ruby file, check:**
38
- - Get the full diff: `git diff --cached <file>`
39
- - Review only the added/modified lines (lines starting with `+`)
40
-
41
- 3. **Look for critical issues (❌ BLOCK):**
42
-
43
- **Sandi Metz violations:**
44
- - ❌ Missing `frozen_string_literal: true` in new files
45
- - ❌ Methods > 15 lines (SRP violation, too complex)
46
- - ❌ Classes > 200 lines (god object)
47
- - ❌ Obvious code duplication (DRY violation)
48
-
49
- **Jeremy Evans (Sequel) violations:**
50
- - ❌ Raw SQL strings instead of Sequel dataset methods
51
- - ❌ Database writes without transaction wrapper
52
- - ❌ N+1 queries (multiple queries in loops)
53
-
54
- **Kent Beck violations:**
55
- - ❌ Overly complex solutions (nested conditionals > 3 levels)
56
- - ❌ Command-Query Separation violation (methods that both mutate and return calculated values)
57
-
58
- **Avdi Grimm violations:**
59
- - ❌ Defensive nil checks everywhere (should use null objects)
60
- - ❌ Implicit nil returns in public methods
61
- - ❌ Bare `raise` or `rescue` without exception class
62
-
63
- **Gary Bernhardt violations:**
64
- - ❌ I/O operations mixed with business logic (should separate)
65
- - ❌ Mutable state in value objects
66
- - ❌ Database/file I/O in unit tests (makes tests slow)
67
-
68
- **Testing:**
69
- - ❌ New public methods without corresponding tests
70
-
71
- 4. **Look for medium issues (⚠️ WARNING):**
72
-
73
- **Sandi Metz:**
74
- - ⚠️ Methods 10-15 lines (consider extracting)
75
- - ⚠️ Classes 100-200 lines (approaching god object)
76
- - ⚠️ Method parameters > 3 (use parameter object)
77
-
78
- **Jeremy Evans:**
79
- - ⚠️ Missing indexes on foreign keys
80
- - ⚠️ Connection not properly managed
81
-
82
- **Kent Beck:**
83
- - ⚠️ Poor naming (unclear variable/method names, abbreviations)
84
- - ⚠️ Methods doing multiple things (and/or in method name)
85
-
86
- **Avdi Grimm:**
87
- - ⚠️ Law of Demeter violations (chained method calls like `foo.bar.baz.qux`)
88
- - ⚠️ Asking instead of telling (lots of getters instead of sending commands)
89
-
90
- **Gary Bernhardt:**
91
- - ⚠️ Business logic scattered in imperative shell
92
- - ⚠️ Missing value objects (primitives passed around)
93
-
94
- **General:**
95
- - ⚠️ Missing documentation for public APIs
96
- - ⚠️ Tight coupling between modules
97
-
98
- ## Output Format
99
-
100
- Provide a clear summary with expert attributions:
101
-
102
- ```
103
- # Pre-Commit Quality Review
104
-
105
- ## Files Reviewed
106
- - file1.rb (23 lines changed)
107
- - file2.rb (8 lines changed)
108
-
109
- ## Status: ❌ BLOCK / ✅ PASS / ⚠️ WARNING
110
-
111
- ### Critical Issues ❌ (must fix before commit)
112
-
113
- **Sandi Metz violations:**
114
- - file1.rb:1 - Missing frozen_string_literal: true
115
- - file2.rb:15-38 - Method too long (24 lines, max 15)
116
-
117
- **Jeremy Evans violations:**
118
- - file1.rb:42 - Raw SQL string instead of Sequel dataset method
119
- - file1.rb:50 - Database write without transaction wrapper
120
-
121
- **Avdi Grimm violations:**
122
- - file2.rb:10 - Implicit nil return in public method
123
-
124
- ### Medium Issues ⚠️ (consider fixing)
125
-
126
- **Sandi Metz:**
127
- - file3.rb:20-32 - Method is 13 lines (consider extracting)
128
-
129
- **Kent Beck:**
130
- - file2.rb:5 - Variable name `x` is unclear (revealing intent)
131
-
132
- **Avdi Grimm:**
133
- - file3.rb:45 - Law of Demeter violation: user.account.settings.theme
134
-
135
- ### Recommendations
136
-
137
- 1. Add `frozen_string_literal: true` to file1.rb (Sandi Metz)
138
- 2. Convert raw SQL at file1.rb:42 to Sequel dataset (Jeremy Evans)
139
- 3. Wrap database write at file1.rb:50 in transaction (Jeremy Evans)
140
- 4. Extract file2.rb:15-38 into smaller methods (Sandi Metz)
141
- 5. Return explicit value instead of nil at file2.rb:10 (Avdi Grimm)
142
- 6. Rename `x` to describe what it contains (Kent Beck)
143
- 7. Extract file3.rb:20-32 for better readability (Sandi Metz)
144
- 8. Use tell-don't-ask at file3.rb:45 (Avdi Grimm)
145
-
146
- ## Suggested Actions
147
-
148
- [If BLOCK] Run: git reset HEAD <files> && fix issues && git add <files>
149
- [If WARNING] Consider fixing before commit or create a follow-up task
150
- [If PASS] Commit looks good! 🚀
151
- ```
152
-
153
- ## Exit Behavior
154
-
155
- - **Return clear judgment**: BLOCK, WARNING, or PASS
156
- - **Be specific**: Include file:line references for all issues
157
- - **Be helpful**: Suggest concrete fixes
158
- - **Be fast**: Don't over-analyze, focus on obvious problems
159
-
160
- ## Quick Reference Checklist
161
-
162
- For each added/modified line in the diff, scan for:
163
-
164
- **Sandi Metz:**
165
- - [ ] frozen_string_literal at top?
166
- - [ ] Methods < 15 lines? (warn at 10+)
167
- - [ ] Classes < 200 lines? (warn at 100+)
168
- - [ ] No duplicate code?
169
- - [ ] Parameters <= 3? (warn if more)
170
-
171
- **Jeremy Evans:**
172
- - [ ] Sequel datasets not raw SQL?
173
- - [ ] DB writes in transactions?
174
- - [ ] No N+1 queries in loops?
175
-
176
- **Kent Beck:**
177
- - [ ] Nested conditionals <= 3?
178
- - [ ] Clear, revealing names?
179
- - [ ] Methods do one thing?
180
- - [ ] Command-Query Separation?
181
-
182
- **Avdi Grimm:**
183
- - [ ] Null objects instead of nil checks?
184
- - [ ] Explicit returns (not implicit nil)?
185
- - [ ] Specific exception classes?
186
- - [ ] Law of Demeter (max 2 dots)?
187
-
188
- **Gary Bernhardt:**
189
- - [ ] Business logic separate from I/O?
190
- - [ ] Value objects immutable?
191
- - [ ] Tests avoid I/O?
192
-
193
- ## Success Criteria
194
-
195
- The review is complete when:
196
- - All staged Ruby files have been checked
197
- - Clear BLOCK/WARNING/PASS verdict is given
198
- - All critical issues have file:line references with expert attribution
199
- - Concrete fix suggestions are provided with expert rationale
@@ -1,154 +0,0 @@
1
- ---
2
- name: review-for-quality
3
- description: Comprehensive code quality review through expert perspectives (Sandi Metz, Jeremy Evans, Kent Beck, Avdi Grimm, Gary Bernhardt). Updates docs/quality_review.md with findings.
4
- agent: Plan
5
- allowed-tools: Read, Grep, Glob
6
- ---
7
-
8
- # Code Quality Review
9
-
10
- Critically review this Ruby codebase for best-practices, idiom use, and overall quality through the eyes of Ruby experts.
11
-
12
- ## Expert Perspectives
13
-
14
- Analyze the codebase through these 5 perspectives:
15
-
16
- 1. **Sandi Metz** (POODR principles)
17
- - Single Responsibility Principle
18
- - Small, focused methods (< 5 lines ideal)
19
- - Classes with single purpose
20
- - DRY principle
21
- - Clear dependencies
22
- - High test coverage
23
-
24
- 2. **Jeremy Evans** (Sequel maintainer)
25
- - Proper Sequel usage patterns (datasets over raw SQL)
26
- - Database performance optimization
27
- - Schema design best practices
28
- - Connection management
29
- - Transaction safety
30
- - Sequel plugins and extensions
31
-
32
- 3. **Kent Beck** (TDD, Simple Design)
33
- - Test-first design
34
- - Simple solutions over complex ones
35
- - Revealing intent through naming
36
- - Clear boundaries between components
37
- - Testability without mocks
38
- - Command-Query Separation
39
-
40
- 4. **Avdi Grimm** (Confident Ruby)
41
- - Confident code (no defensive nil checks everywhere)
42
- - Tell, don't ask principle
43
- - Null object pattern
44
- - Meaningful return values (not nil)
45
- - Duck typing
46
- - Result objects over exceptions
47
-
48
- 5. **Gary Bernhardt** (Boundaries, Fast Tests)
49
- - Functional core, imperative shell
50
- - Fast unit tests (no I/O in logic)
51
- - Clear boundaries between layers
52
- - Separation of I/O and pure logic
53
- - Value objects
54
- - Immutable data structures
55
-
56
- ## Review Process
57
-
58
- 1. **Explore the codebase systematically:**
59
- - `lib/claude_memory/` (all subdirectories)
60
- - Identify the largest files (> 500 lines)
61
- - Find code duplication patterns
62
- - Check architecture and design patterns
63
-
64
- 2. **Document EVERY issue found** with:
65
- - Priority: 🔴 Critical / High / 🟡 Medium / Low
66
- - Specific file:line references
67
- - Which expert's principle is violated
68
- - Concrete improvement suggestions with code examples
69
- - Estimated effort to fix
70
-
71
- 3. **Track progress:**
72
- - Compare with previous review date
73
- - Show metrics (lines of code, god objects, etc.)
74
- - Identify what's been fixed since last review
75
- - Highlight new issues that have emerged
76
-
77
- 4. **Provide actionable recommendations:**
78
- - High priority items (this week)
79
- - Medium priority items (next week)
80
- - Low priority items (later)
81
- - Quick wins (can do today)
82
-
83
- ## Output Format
84
-
85
- Update `docs/quality_review.md` with:
86
-
87
- ### Structure:
88
- ```
89
- # Code Quality Review - Ruby Best Practices
90
-
91
- **Review Date:** [YYYY-MM-DD]
92
- **Previous Review:** [YYYY-MM-DD]
93
-
94
- ## Executive Summary
95
- [Progress since last review + new critical issues]
96
-
97
- ## 1. Sandi Metz Perspective
98
- ### What's Been Fixed ✅
99
- ### Critical Issues 🔴
100
- ### Medium Issues 🟡
101
-
102
- ## 2. Jeremy Evans Perspective
103
- [Same structure]
104
-
105
- ## 3. Kent Beck Perspective
106
- [Same structure]
107
-
108
- ## 4. Avdi Grimm Perspective
109
- [Same structure]
110
-
111
- ## 5. Gary Bernhardt Perspective
112
- [Same structure]
113
-
114
- ## 6. General Ruby Idioms
115
- [Style and convention issues]
116
-
117
- ## 7. Positive Observations
118
- [What's working well]
119
-
120
- ## 8. Priority Refactoring Recommendations
121
- ### High Priority (This Week)
122
- ### Medium Priority (Next Week)
123
- ### Low Priority (Later)
124
-
125
- ## 9. Conclusion
126
- [Summary + risk assessment + next steps]
127
-
128
- ## Appendix A: Metrics Comparison
129
- [Table showing progress]
130
-
131
- ## Appendix B: Quick Wins
132
- [Things that can be done immediately]
133
-
134
- ## Appendix C: File Size Report
135
- [Largest files identified]
136
- ```
137
-
138
- ## Important Notes
139
-
140
- - Be thorough and critical - find real issues to improve
141
- - Every issue needs a specific file:line reference
142
- - Provide code examples for suggested fixes
143
- - Don't just praise - identify concrete problems
144
- - Compare metrics with previous review date
145
- - Estimate effort for each recommendation (days)
146
-
147
- ## Success Criteria
148
-
149
- The review is complete when:
150
- - `docs/quality_review.md` is updated with dated findings
151
- - Every issue has file:line references
152
- - Concrete code examples are provided
153
- - Metrics comparison table is included
154
- - Actionable priorities are listed with time estimates
@@ -1,79 +0,0 @@
1
- # Expert Review Checklists
2
-
3
- ## Sandi Metz (POODR) Checklist
4
-
5
- - [ ] Classes under 100 lines
6
- - [ ] Methods under 5 lines
7
- - [ ] Method parameters limited (< 4)
8
- - [ ] Single Responsibility Principle followed
9
- - [ ] No god objects (classes > 500 lines)
10
- - [ ] DRY violations eliminated
11
- - [ ] Dependencies injected, not created
12
- - [ ] Public interface is minimal
13
- - [ ] Private methods grouped at bottom
14
- - [ ] attr_reader used appropriately
15
-
16
- ## Jeremy Evans (Sequel) Checklist
17
-
18
- - [ ] Using Sequel datasets, not raw SQL
19
- - [ ] Transactions wrap multi-step operations
20
- - [ ] DateTime columns instead of String timestamps
21
- - [ ] Sequel migrations used (not manual)
22
- - [ ] Connection pooling configured
23
- - [ ] Sequel plugins utilized (timestamps, validation_helpers)
24
- - [ ] No N+1 query patterns
25
- - [ ] Batch queries used for multiple records
26
- - [ ] Foreign keys defined properly
27
- - [ ] Indexes created for common queries
28
-
29
- ## Kent Beck (TDD, Simple Design) Checklist
30
-
31
- - [ ] Dependencies can be injected for testing
32
- - [ ] No side effects in constructors
33
- - [ ] Methods reveal intent through naming
34
- - [ ] Complex boolean logic is extracted and named
35
- - [ ] No large case statements (use polymorphism)
36
- - [ ] Tests exist for failure modes
37
- - [ ] Command-Query Separation followed
38
- - [ ] Simple solutions chosen over complex ones
39
- - [ ] Test coverage for edge cases
40
- - [ ] Clear boundaries between components
41
-
42
- ## Avdi Grimm (Confident Ruby) Checklist
43
-
44
- - [ ] Null Object pattern used instead of nil checks
45
- - [ ] Consistent return values (not mixed types)
46
- - [ ] Result objects for success/failure
47
- - [ ] Tell, don't ask (no ask-then-do patterns)
48
- - [ ] Early returns minimized (use guard clauses)
49
- - [ ] Primitive obsession eliminated (use value objects)
50
- - [ ] Domain objects instead of hashes
51
- - [ ] Duck typing enables polymorphism
52
- - [ ] Meaningful default values
53
- - [ ] Confident code (no defensive programming everywhere)
54
-
55
- ## Gary Bernhardt (Boundaries) Checklist
56
-
57
- - [ ] I/O separated from business logic
58
- - [ ] Core logic is pure (no side effects)
59
- - [ ] Fast unit tests (no database/filesystem)
60
- - [ ] Value objects used for domain concepts
61
- - [ ] State passed as parameters, not stored in instance variables
62
- - [ ] Clear layer boundaries (presentation → application → domain → infrastructure)
63
- - [ ] File I/O abstracted (dependency injection)
64
- - [ ] Database access abstracted (repository pattern)
65
- - [ ] Functional core, imperative shell pattern
66
- - [ ] Immutable data structures preferred
67
-
68
- ## General Ruby Idioms Checklist
69
-
70
- - [ ] frozen_string_literal: true in all files
71
- - [ ] Consistent method parentheses style
72
- - [ ] Keyword arguments for methods with > 2 params
73
- - [ ] Parameter objects for long parameter lists
74
- - [ ] Consistent hash access (symbols vs strings)
75
- - [ ] Specific exception rescues (not bare rescue)
76
- - [ ] ENV access centralized
77
- - [ ] Boolean traps eliminated (use explicit values)
78
- - [ ] Ruby 3 features used where appropriate
79
- - [ ] Standard Ruby linter passing
@@ -1 +0,0 @@
1
- ../../skills/setup-memory