vault backup: 2026-02-26 21:10:47
This commit is contained in:
windyboy
@@ -54,16 +54,6 @@ Create a comprehensive synthesis of the week's work.
|
||||
|
||||
Best for: Weekly reviews, pattern recognition
|
||||
|
||||
### 💬 git-commit-msg
|
||||
|
||||
AI-generated conventional commit messages from staged changes.
|
||||
|
||||
```
|
||||
/git-commit-msg
|
||||
```
|
||||
|
||||
Best for: Creating meaningful commit messages, maintaining clean git history
|
||||
|
||||
## Creating Custom Commands
|
||||
|
||||
1. Create a new `.md` file in this directory
|
||||
|
||||
@@ -0,0 +1,367 @@
|
||||
---
|
||||
name: pragmatic-review
|
||||
description:
|
||||
'Interactive pragmatic code review focusing on YAGNI and KISS principles'
|
||||
version: 1.0.0
|
||||
argument-hint:
|
||||
'[--auto] [--ci] [--deep (6-pass)] [--branch branch-name] [--base base-branch]'
|
||||
allowed-tools:
|
||||
[
|
||||
Read,
|
||||
Grep,
|
||||
Glob,
|
||||
Bash(test:*),
|
||||
Bash(git:*),
|
||||
Bash(echo:*),
|
||||
Bash(head:*),
|
||||
Bash(wc:*),
|
||||
Bash(tr:*),
|
||||
]
|
||||
---
|
||||
|
||||
# Pragmatic Code Review: YAGNI & KISS Focus
|
||||
|
||||
You will perform an interactive code review with laser focus on **YAGNI** (You
|
||||
Aren't Gonna Need It) and **KISS** (Keep It Simple, Stupid) principles.
|
||||
|
||||
## Review Modes
|
||||
|
||||
**Default mode**: Fast YAGNI/KISS-focused review
|
||||
|
||||
- Scans for over-engineering, unused abstractions, unnecessary complexity
|
||||
- Quick security and performance checks (OWASP basics, obvious N+1 queries)
|
||||
- Self-reflection to validate findings with evidence
|
||||
|
||||
**Deep mode** (`--deep` flag): Multi-pass comprehensive review
|
||||
|
||||
- Pass 1: Security (OWASP Top 10, input validation, auth issues)
|
||||
- Pass 2: Architecture (SOLID principles, separation of concerns)
|
||||
- Pass 3: Logic (edge cases, error handling, correctness)
|
||||
- Pass 4: Performance (algorithm complexity, resource leaks)
|
||||
- Pass 5: YAGNI/KISS (over-engineering, unnecessary abstractions)
|
||||
- Pass 6: Maintainability (readability, tests, documentation)
|
||||
- Self-reflection after all passes
|
||||
|
||||
Use `--deep` when:
|
||||
|
||||
- Security-critical changes (auth, payment, data handling)
|
||||
- Core architecture modifications
|
||||
- Complex logic changes with many edge cases
|
||||
- Performance-sensitive code paths
|
||||
|
||||
Use default mode when:
|
||||
|
||||
- Feature additions
|
||||
- Bug fixes
|
||||
- Refactoring
|
||||
- Documentation changes
|
||||
|
||||
**CI mode** (`--ci` flag): Non-interactive mode for GitHub Actions
|
||||
|
||||
- Skips ALL interactive prompts
|
||||
- Auto-selects: all branch changes vs base branch
|
||||
- Uses `$GITHUB_BASE_REF` environment variable if available
|
||||
- Outputs all findings at once as markdown (summary view)
|
||||
|
||||
## Step 1: Determine Review Scope
|
||||
|
||||
### Check Current Git State
|
||||
|
||||
First, verify we're in a git repository by running:
|
||||
|
||||
- `test -d .git` to check if .git directory exists
|
||||
|
||||
If not in a git repository, ask the user to specify files to review manually.
|
||||
|
||||
If in a git repository, gather information:
|
||||
|
||||
#### Current branch:
|
||||
Run: `git rev-parse --abbrev-ref HEAD`
|
||||
|
||||
#### Default branch detection:
|
||||
1. Try: `git rev-parse --verify main`
|
||||
2. If that fails, try: `git rev-parse --verify master`
|
||||
3. If that fails, try: `git rev-parse --verify develop`
|
||||
|
||||
If user specified `--base [branch]` in arguments, use that instead.
|
||||
|
||||
#### Working directory status:
|
||||
Run: `git status --short | head -20`
|
||||
|
||||
### Present Options to User
|
||||
|
||||
**If `--ci` flag is present:** Skip all interactive prompts and auto-select
|
||||
option 2: Review all changes on current branch vs base.
|
||||
|
||||
Unless `--auto` or `--ci` flag is present, ask the user:
|
||||
|
||||
```
|
||||
📋 CODE REVIEW SCOPE SELECTION
|
||||
════════════════════════════════
|
||||
|
||||
What would you like to review?
|
||||
|
||||
1️⃣ Current uncommitted changes
|
||||
2️⃣ All changes on current branch (compared to [detected default branch])
|
||||
3️⃣ Specific files or directory
|
||||
4️⃣ Last N commits
|
||||
5️⃣ Staged changes only
|
||||
|
||||
Please enter your choice (1-5):
|
||||
```
|
||||
|
||||
## Step 2: YAGNI/KISS Analysis Framework
|
||||
|
||||
For each file identified, analyze for these patterns:
|
||||
|
||||
### YAGNI Detection Patterns
|
||||
|
||||
1. **Unused abstractions**
|
||||
- Interfaces/protocols with single implementations
|
||||
- Abstract base classes with one concrete subclass
|
||||
- Generic types that are always the same
|
||||
|
||||
2. **Premature flexibility**
|
||||
- Configuration for things that never change
|
||||
- Plugin systems with no plugins
|
||||
- Feature flags that are always on/off
|
||||
|
||||
3. **Over-engineering indicators**
|
||||
- Factory classes for simple objects
|
||||
- Builder patterns for objects with 2-3 fields
|
||||
- Event systems with single listeners
|
||||
|
||||
4. **Speculative code**
|
||||
- "TODO: might need this" comments
|
||||
- Commented-out code "just in case"
|
||||
- Unreachable code paths
|
||||
- Methods that are never called
|
||||
|
||||
5. **The GenericButton Anti-Pattern**
|
||||
- Components with 8+ optional parameters serving different use cases
|
||||
- So many props that using it is as complex as writing from scratch
|
||||
|
||||
6. **Premature Abstraction - Rule of Three**
|
||||
- Abstraction created at 1st or 2nd duplication (wait for 3rd!)
|
||||
- Reference: Martin Fowler - "Tolerate duplication twice, refactor on the third"
|
||||
|
||||
### KISS Violation Patterns
|
||||
|
||||
1. **Verbose implementations**
|
||||
- Can be reduced by >50% lines
|
||||
- Reimplements standard library functions
|
||||
- Complex regex when simple string operations work
|
||||
|
||||
2. **Abstraction addiction**
|
||||
- More than 3 levels of inheritance/wrapping
|
||||
- Interfaces between every layer
|
||||
|
||||
3. **Clever code**
|
||||
- Needs extensive comments to explain
|
||||
- Uses obscure language features unnecessarily
|
||||
- One-liners that should be 5 clear lines
|
||||
|
||||
4. **Catch-Log-Exit Anti-Pattern**
|
||||
- Catching exceptions just to log and exit
|
||||
- Replaces actual error with a guess about what went wrong
|
||||
|
||||
```typescript
|
||||
// TERRIBLE: replaces actual error with a guess
|
||||
try {
|
||||
await createNewBranch({ branchName, cwd })
|
||||
} catch (error) {
|
||||
console.error('Error: Not in a git repository') // Maybe wrong!
|
||||
process.exit(1)
|
||||
}
|
||||
|
||||
// CORRECT: let it throw naturally
|
||||
await createNewBranch({ branchName, cwd })
|
||||
```
|
||||
|
||||
### Security Patterns to Check
|
||||
|
||||
Even in a YAGNI/KISS review, flag critical security issues:
|
||||
|
||||
1. **SQL Injection**
|
||||
- String concatenation in SQL queries
|
||||
- Missing parameterized queries
|
||||
|
||||
2. **Authentication/Authorization**
|
||||
- Hardcoded secrets
|
||||
- Weak defaults: `SECRET = os.getenv('KEY', 'default')`
|
||||
- JWT without expiration
|
||||
|
||||
3. **Unvalidated External Inputs**
|
||||
- URL parameters used directly without validation
|
||||
- API response data trusted without schema validation
|
||||
|
||||
### Performance Patterns to Check
|
||||
|
||||
Flag obvious performance issues:
|
||||
|
||||
1. **N+1 Query Problems**
|
||||
- Loops that make database calls
|
||||
- Missing eager loading
|
||||
|
||||
2. **Inefficient Algorithms**
|
||||
- O(n²) where O(n) or O(n log n) would work
|
||||
- Unnecessary nested loops
|
||||
|
||||
## Step 3: Perform Analysis
|
||||
|
||||
**Check for `--deep` flag**: If present, use Multi-Pass Deep Mode with 6
|
||||
sequential passes. Otherwise, use Fast YAGNI/KISS Mode.
|
||||
|
||||
**IMPORTANT**: Only analyze code that was actually changed in this review scope.
|
||||
Do not flag pre-existing issues.
|
||||
|
||||
## Step 3.5: Self-Review Pass
|
||||
|
||||
**Before presenting findings, validate each issue:**
|
||||
|
||||
1. **Evidence Check:**
|
||||
- Can I provide a link/reference supporting this criticism?
|
||||
- Have I explained WHY this matters?
|
||||
|
||||
2. **Severity Validation:**
|
||||
- Is this rating accurate (High/Medium/Low)?
|
||||
- Would this issue actually cause problems?
|
||||
|
||||
3. **YAGNI-Specific Checks:**
|
||||
- If flagging duplication: Is this the 3rd+ occurrence?
|
||||
- Can this be refactored later when we have more information?
|
||||
|
||||
**Remove or downgrade any issues that fail these checks.**
|
||||
|
||||
## Step 4: Interactive Review Process
|
||||
|
||||
### Issue Severity Prefixes
|
||||
|
||||
Use these prefixes to communicate priority:
|
||||
|
||||
| Prefix | Meaning | Action Required |
|
||||
| ------------- | ---------------------------------- | --------------------- |
|
||||
| `issue:` | Bug, correctness problem | Must fix before merge |
|
||||
| `nit:` | Minor improvement, style | Optional, don't block |
|
||||
| `thought:` | Design consideration | Discuss, may defer |
|
||||
| `suggestion:` | Specific improvement with code | Consider seriously |
|
||||
|
||||
### Interactive Walkthrough
|
||||
|
||||
For each issue, present:
|
||||
|
||||
```
|
||||
═══════════════════════════════════════
|
||||
Issue [current] of [total]
|
||||
═══════════════════════════════════════
|
||||
|
||||
📁 File: [filename]
|
||||
📍 Lines: [start-end]
|
||||
🏷️ Type: [YAGNI | KISS | Both]
|
||||
🎯 Severity: [High | Medium | Low]
|
||||
|
||||
CURRENT CODE:
|
||||
[show actual code snippet]
|
||||
|
||||
ISSUE DETECTED: [Specific description]
|
||||
|
||||
WHY THIS MATTERS: [Explain the real cost/problem]
|
||||
|
||||
SUGGESTED SIMPLIFICATION:
|
||||
[Show the simpler alternative code]
|
||||
|
||||
═══════════════════════════════════════
|
||||
|
||||
What would you like to do?
|
||||
1. ✅ Accept - Add to fix list
|
||||
2. ❌ Skip - Keep current code
|
||||
3. 💬 Discuss - Mark for team review
|
||||
4. 👀 Context - See more surrounding code
|
||||
5. ⏹️ Stop - End review here
|
||||
```
|
||||
|
||||
## Step 5: Core Review Rules
|
||||
|
||||
### ALWAYS Flag These YAGNI Issues:
|
||||
|
||||
1. **Interfaces with single implementation**
|
||||
2. **Unused code** - functions/methods with zero callers
|
||||
3. **Speculative database fields** - columns always NULL
|
||||
4. **Premature optimization** - caching before measuring
|
||||
|
||||
### ALWAYS Flag These KISS Violations:
|
||||
|
||||
1. **Standard library reimplementation**
|
||||
2. **Excessive abstraction layers**
|
||||
3. **Configuration over convention** - 100 lines config for 50 lines code
|
||||
|
||||
### DON'T Flag These:
|
||||
|
||||
1. **Necessary complexity** - error handling, security measures
|
||||
2. **Domain complexity** - business rules that ARE complex
|
||||
3. **Team conventions** - agreed-upon patterns
|
||||
|
||||
## Step 6: Final Summary
|
||||
|
||||
```
|
||||
📝 PRAGMATIC REVIEW COMPLETE
|
||||
═══════════════════════════════
|
||||
|
||||
Review Statistics:
|
||||
• Files reviewed: [X]
|
||||
• Lines changed: [Y]
|
||||
|
||||
Issues Found: [Y total]
|
||||
• Critical (blocking): [count]
|
||||
• High priority: [count]
|
||||
• Medium: [count]
|
||||
• Low: [count]
|
||||
|
||||
COMPLEXITY REDUCTION POTENTIAL:
|
||||
• Lines removable: ~[total] (-X%)
|
||||
• Unnecessary abstractions: [count]
|
||||
|
||||
TOP 3 QUICK WINS:
|
||||
1. [Biggest impact, easiest change]
|
||||
2. [Second biggest impact]
|
||||
3. [Third biggest impact]
|
||||
|
||||
RECOMMENDATION: [Clear ship/don't ship with reasoning]
|
||||
|
||||
═══════════════════════════════
|
||||
```
|
||||
|
||||
## Command Parameters Reference
|
||||
|
||||
- `--auto` : Skip interactive prompts, use defaults (uncommitted changes)
|
||||
- `--ci` : CI mode - skip ALL prompts, review branch vs base
|
||||
- `--deep` : Enable 6-pass comprehensive review
|
||||
- `--branch [name]` : Review specific branch
|
||||
- `--base [branch]` : Compare against this base branch
|
||||
|
||||
Examples:
|
||||
|
||||
- `/pragmatic-review` - Interactive mode
|
||||
- `/pragmatic-review --auto` - Review current changes automatically
|
||||
- `/pragmatic-review --ci` - CI mode for GitHub Actions
|
||||
- `/pragmatic-review --deep` - Comprehensive 6-pass review
|
||||
|
||||
## Core Philosophy
|
||||
|
||||
When in doubt, remember:
|
||||
|
||||
1. **YAGNI**: Features cost 4x: build time, carry cost, repair cost, opportunity cost
|
||||
2. **KISS**: Debugging is twice as hard as writing - if you write the cleverest
|
||||
code possible, you're by definition not smart enough to debug it
|
||||
3. **Rule of Three**: Tolerate duplication twice, refactor on the third
|
||||
4. **Pragmatic**: Ship working software today, perfect it tomorrow
|
||||
|
||||
Your role is to be the champion of simplicity. Every line deleted is a victory.
|
||||
|
||||
## References
|
||||
|
||||
- Martin Fowler - YAGNI: https://martinfowler.com/bliki/Yagni.html
|
||||
- KISS principle: https://en.wikipedia.org/wiki/KISS_principle
|
||||
- OWASP Top 10: https://owasp.org/www-project-top-ten/
|
||||
- Addy Osmani - "Avoid Large Pull Requests"
|
||||
- Jeff Atwood - "Curly's Law: Do One Thing"
|
||||
@@ -32,8 +32,9 @@ capabilities.
|
||||
- Check if already on latest version:
|
||||
|
||||
```bash
|
||||
CURRENT=$(grep '"version"' package.json | sed 's/.*: "\(.*\)".*/\1/')
|
||||
LATEST=$(curl -s https://raw.githubusercontent.com/heyitsnoah/claudesidian/main/package.json | grep '"version"' | sed 's/.*: "\(.*\)".*/\1/')
|
||||
# Use cut instead of sed to avoid zsh parentheses escaping issues
|
||||
CURRENT=$(grep '"version"' package.json | head -1 | cut -d'"' -f4)
|
||||
LATEST=$(curl -s https://raw.githubusercontent.com/heyitsnoah/claudesidian/main/package.json | grep '"version"' | head -1 | cut -d'"' -f4)
|
||||
|
||||
if [ "$CURRENT" = "$LATEST" ]; then
|
||||
echo "✅ You're already on the latest version ($CURRENT)"
|
||||
|
||||
Reference in New Issue
Block a user