moicle 2.0.0 → 2.2.0

package/assets/skills/review/pr/SKILL.md

@@ -5,599 +5,208 @@ description: Thorough pull request review workflow with architecture compliance
 
 # Pull Request Review Workflow
 
-Comprehensive workflow for reviewing pull requests with architecture compliance and quality gates.
+Review someone else's PR across 5 dimensions and post structured feedback to GitHub.
 
 ## When to use this skill
 
 - ✅ Reviewing someone else's open PR (`gh pr view <number>` accessible)
 - ✅ Need to post structured feedback (APPROVE / REQUEST CHANGES / COMMENT)
 - ✅ Want a multi-dimensional review (architecture + security + perf + tests)
-- ❌ Self-review of your own branch before push → use `/review:branch`
+- ❌ Self-review of own branch before push → use `/review:branch`
 - ❌ Only checking DDD compliance → use `/review:architect`
 - ❌ Addressing comments on your own PR → use `/fix:pr-comment`
 
 ## Read Architecture First
 
-Read `ddd-architecture.md` + stack-specific doc — review must verify compliance.
+Load `~/.claude/architecture/ddd-architecture.md` + the stack-specific doc. Detect stack via `~/.claude/architecture/_shared/stack-detection.md`.
 
-## Workflow Overview
+---
+
+## Workflow
 
 ```
-┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐
-│ 1. FETCH │──▶│2. ANALYZE│──▶│ 3. REVIEW│──▶│4. FEEDBACK
-└──────────┘   └──────────┘   └──────────┘   └──────────┘
-                                    │
-                                    ▼
-                        ┌───────────────────────┐
-                        │  Quality Gates Check  │
-                        │ ✓ Architecture        │
-                        │ ✓ Security            │
-                        │ ✓ Performance         │
-                        │ ✓ Tests               │
-                        └───────────────────────┘
+FETCH → ANALYZE → REVIEW (5 dims) → FEEDBACK → POST
 ```
 
 ---
 
 ## Phase 1: FETCH
 
-**Goal**: Gather all PR information and context
-
-### Actions
-1. Fetch PR details:
-   ```bash
-   gh pr view [PR_NUMBER] --json number,title,body,author,state,commits,reviews,files
-   ```
-
-2. Get the diff:
-   ```bash
-   gh pr diff [PR_NUMBER]
-   ```
-
-3. List all commits:
-   ```bash
-   gh pr view [PR_NUMBER] --json commits --jq '.commits[] | "\(.oid[:7]) \(.messageHeadline)"'
-   ```
-
-4. Check CI/CD status:
-   ```bash
-   gh pr checks [PR_NUMBER]
-   ```
-
-5. **Identify project stack** from PR files and read architecture doc
+**Goal:** load PR + diff + context in one pass.
 
-### Output
-```markdown
-## PR #[NUMBER]: [TITLE]
-
-### Metadata
-- **Author**: [author]
-- **State**: [open/merged/closed]
-- **Stack**: [Flutter/React/Go/Laravel/Remix]
-- **Architecture Doc**: [path to doc]
-- **Files Changed**: [count]
-- **Additions**: +[count] / **Deletions**: -[count]
-
-### Commits
-1. [commit 1]
-2. [commit 2]
-
-### Description
-[PR body]
-
-### CI/CD Status
-[pass/fail status]
+```bash
+PR={number}
+gh pr view $PR --json number,title,body,author,state,headRefName,baseRefName,commits,files
+gh pr diff $PR
+gh pr checks $PR
+gh pr view $PR --comments
 ```
 
 ### Gate
-- [ ] PR details fetched
-- [ ] Diff obtained
-- [ ] Commits listed
-- [ ] Stack identified
-- [ ] Architecture doc identified
+- [ ] PR metadata + diff + CI status loaded
+- [ ] PR description explains "what / why" — if missing, ask author before deep review
+- [ ] CI status known (don't review red builds — ask author to fix first)
 
 ---
 
 ## Phase 2: ANALYZE
 
-**Goal**: Understand the changes and identify affected areas
+**Goal:** understand scope before going line-by-line.
 
-### Actions
-1. **Read the architecture doc** for this stack
-2. Analyze what changed:
-   - Which layers are affected? (per architecture doc)
-   - What's the scope? (feature/fix/refactor/docs)
-   - Are there breaking changes?
-
-3. Identify impact areas based on architecture:
-   - Frontend/Backend/Database?
-   - Which modules/packages?
-   - Dependencies changed?
-
-4. Check for red flags:
-   - [ ] Large PR (>500 lines)?
-   - [ ] Multiple unrelated changes?
-   - [ ] Conflicts with architecture patterns?
-   - [ ] Missing tests?
-   - [ ] No description?
-
-### Analysis Output
-```markdown
-## Change Analysis
-
-### Architecture Reference
-- Doc: [path to architecture doc]
-- Pattern: [pattern from doc]
-
-### Scope
-- Type: [Feature/Fix/Refactor/Docs/Chore]
-- Breaking Changes: [Yes/No]
-
-### Layers Affected (from architecture doc)
-- Layer 1: [files]
-- Layer 2: [files]
-- Layer 3: [files]
-
-### Impact Areas
-- [Module 1]: [description]
-- [Module 2]: [description]
-
-### Red Flags
-- [ ] Issue 1
-- [ ] Issue 2
-```
+1. **Scope check**: does the diff match the PR title / description? Mixed-scope PRs (e.g., feature + drive-by refactor) → ask author to split.
+2. **Risk profile**: which files? domain logic, infra config, migrations, auth — high risk vs UI tweak — low risk.
+3. **Test delta**: are new tests in the diff? coverage % up or down?
+4. **Reference module**: open 1 existing similar module to compare conventions.
 
 ### Gate
-- [ ] Architecture doc read
-- [ ] Changes understood
-- [ ] Impact areas identified
-- [ ] Red flags noted
+- [ ] PR scope is single-purpose (or split requested)
+- [ ] Risk level identified (low / medium / high)
+- [ ] Test delta noted
 
 ---
 
-## Phase 3: REVIEW
-
-**Goal**: Thorough code review against multiple quality dimensions
-
-### Review Dimensions
-
-#### 1. Architecture Compliance ⚠️ CRITICAL
-
-**Read architecture doc and verify:**
-
-- [ ] **Layer Boundaries**: Dependencies flow correctly per doc?
-- [ ] **Directory Structure**: Files in correct locations per doc?
-- [ ] **Naming Conventions**: Follows conventions from doc?
-- [ ] **Design Patterns**: Uses patterns defined in doc?
-- [ ] **Data Flow**: Follows data flow pattern from doc?
-- [ ] **Dependency Injection**: Follows DI pattern from doc?
-
-**Template:**
-```markdown
-### Architecture Compliance: [✅ PASS / ❌ FAIL]
-
-Reference: [architecture doc path]
-
-**Layer Boundaries**: [Pass/Fail]
-- [Finding 1]
-- [Finding 2]
-
-**Structure**: [Pass/Fail]
-- [Finding 1]
-
-**Patterns**: [Pass/Fail]
-- [Finding 1]
-
-**Violations** (if any):
-- [ ] Critical: [description]
-- [ ] Major: [description]
-- [ ] Minor: [description]
-```
-
-#### 2. Code Quality
-
-- [ ] **Readability**: Code is clear and self-documenting
-- [ ] **Naming**: Variables/functions named meaningfully
-- [ ] **Complexity**: No overly complex functions (McCabe < 10)
-- [ ] **DRY**: No unnecessary code duplication
-- [ ] **Comments**: Complex logic is explained
-- [ ] **Error Handling**: Proper error handling and logging
-- [ ] **Type Safety**: Proper types (TypeScript/Dart/Go/PHP)
-
-**Template:**
-```markdown
-### Code Quality: [Good/Needs Work/Poor]
-
-**Strengths**:
-- [strength 1]
-- [strength 2]
-
-**Issues**:
-- [ ] [file:line] - [issue description]
-- [ ] [file:line] - [issue description]
-```
-
-#### 3. Security 🔒
-
-- [ ] **Input Validation**: All inputs validated/sanitized
-- [ ] **Authentication**: Proper auth checks
-- [ ] **Authorization**: Proper permission checks
-- [ ] **SQL Injection**: Parameterized queries used
-- [ ] **XSS Prevention**: Output properly escaped
-- [ ] **Secrets**: No hardcoded secrets/keys
-- [ ] **Dependencies**: No vulnerable dependencies
-
-**Template:**
-```markdown
-### Security: [✅ SECURE / ⚠️ ISSUES / 🚨 CRITICAL]
-
-**Vulnerabilities**:
-- [ ] 🚨 Critical: [description + location]
-- [ ] ⚠️ High: [description + location]
-- [ ] ℹ️ Low: [description + location]
-
-**Recommendations**:
-- [recommendation 1]
-- [recommendation 2]
-```
-
-#### 4. Performance ⚡
+## Phase 3: REVIEW — 5 dimensions
 
-- [ ] **Database**: Queries optimized, indexes used?
-- [ ] **N+1 Queries**: No N+1 query problems
-- [ ] **Caching**: Appropriate caching used (if in doc)?
-- [ ] **Memory**: No obvious memory leaks
-- [ ] **Algorithms**: Efficient algorithms used
-- [ ] **Network**: Minimal API calls
-- [ ] **Bundle Size**: No large bundle additions (frontend)
+Severity definitions: `~/.claude/architecture/_shared/severity-levels.md` (code severity table).
 
-**Template:**
-```markdown
-### Performance: [✅ OPTIMIZED / ⚠️ CONCERNS / 🐌 ISSUES]
+### 3.1 Architecture (CRITICAL / HIGH)
 
-**Concerns**:
-- [ ] [file:line] - [performance issue]
-- [ ] [file:line] - [performance issue]
+For DDD-aware code, check against architecture doc:
+- Domain has zero framework imports
+- No cross-domain imports
+- Business logic in usecases, not handlers / stores
+- Ports in `ports/` dir (not inline interfaces)
+- Entities raise events on state changes
+- Listeners use background context, not request context
 
-**Suggestions**:
-- [optimization 1]
-- [optimization 2]
-```
+**For deep DDD audit:** call `/review:architect` instead and link result.
 
-#### 5. Testing 🧪
+### 3.2 Security (CRITICAL / HIGH)
 
-- [ ] **Test Existence**: Tests exist for new code
-- [ ] **Test Quality**: Tests follow patterns from architecture doc
-- [ ] **Test Coverage**: Critical paths covered
-- [ ] **Test Types**: Unit + Integration (as per doc)
-- [ ] **Edge Cases**: Edge cases tested
-- [ ] **Mocking**: Proper mocking patterns (from doc)
+- Input validation at trust boundary (handler / DTO)
+- AuthN + AuthZ checked before sensitive ops
+- No secrets / tokens in code or logs
+- SQL via parameterized queries / ORM — no string concatenation
+- File paths / shell commands sanitized
+- Rate limiting + idempotency on state-mutating endpoints
+- Crypto: standard library, no roll-your-own
 
-**Template:**
-```markdown
-### Testing: [✅ WELL TESTED / ⚠️ GAPS / ❌ MISSING]
+### 3.3 Performance (HIGH / MEDIUM)
 
-**Coverage**:
-- Unit Tests: [Good/Partial/Missing]
-- Integration Tests: [Good/Partial/Missing]
-- E2E Tests: [Good/Partial/Missing]
+- No N+1 queries (eager-load relations the handler uses)
+- Indexes match new query patterns (check `EXPLAIN`)
+- Pagination on list endpoints (cursor preferred)
+- Background work for slow operations (don't block request)
+- Caching where appropriate, invalidation thought through
+- Synchronous external API calls have timeouts
 
-**Gaps**:
-- [ ] Missing test for [scenario]
-- [ ] Missing test for [edge case]
+### 3.4 Testing (HIGH / MEDIUM)
 
-**Test Quality** (per architecture doc): [Pass/Fail]
-- [finding]
-```
+- New business logic has unit tests (usecases, entities, value objects)
+- New endpoints have at least 1 integration test (happy + error)
+- Tests assert on behavior, not implementation
+- Tests don't depend on order, time, or env
+- Coverage didn't drop for touched files
 
-### Review Checklist
+### 3.5 Code quality (MEDIUM / LOW)
 
-Use this for every PR:
-
-```markdown
-## Review Checklist
-
-### Architecture (from [doc])
-- [ ] Layer boundaries respected
-- [ ] Structure follows doc
-- [ ] Patterns used correctly
-- [ ] Dependencies flow correctly
-
-### Code Quality
-- [ ] Readable and maintainable
-- [ ] Follows naming conventions
-- [ ] No unnecessary complexity
-- [ ] Proper error handling
-
-### Security
-- [ ] No security vulnerabilities
-- [ ] Input validation present
-- [ ] No secrets in code
-- [ ] Auth/authz correct
-
-### Performance
-- [ ] No obvious bottlenecks
-- [ ] Queries optimized
-- [ ] Caching appropriate
-- [ ] Efficient algorithms
-
-### Testing
-- [ ] Tests present
-- [ ] Tests follow doc patterns
-- [ ] Good coverage
-- [ ] Edge cases covered
-
-### Documentation
-- [ ] PR description clear
-- [ ] Complex code commented
-- [ ] README updated (if needed)
-- [ ] API docs updated (if needed)
-```
-
-### Gate
-- [ ] All 5 dimensions reviewed
-- [ ] Findings documented
-- [ ] Severity assessed
+- Names reveal intent (no `data`, `info`, `manager`, `helper`)
+- Functions do one thing
+- No dead branches or commented-out code
+- DRY only where the duplication is real (not coincidental)
+- Errors handled at boundary, not swallowed mid-flow
 
 ---
 
 ## Phase 4: FEEDBACK
 
-**Goal**: Provide clear, actionable feedback
-
-### Feedback Structure
-
-#### Option A: APPROVE ✅
-
-Use when:
-- Architecture compliance: PASS
-- Security: SECURE
-- No critical issues
-- Minor issues acceptable
-
-```markdown
-## Review: ✅ APPROVED
-
-### Summary
-[Brief summary of changes]
-
-### Architecture Compliance
-✅ Follows [architecture doc name] patterns correctly
-
-### Strengths
-- [strength 1]
-- [strength 2]
-- [strength 3]
-
-### Minor Suggestions (Optional)
-- [ ] [suggestion 1]
-- [ ] [suggestion 2]
-
-### Recommendation
-**APPROVE** - Ready to merge
-```
-
-#### Option B: REQUEST CHANGES ⚠️
-
-Use when:
-- Architecture violations
-- Security issues
-- Critical bugs
-- Missing tests
-
-```markdown
-## Review: ⚠️ CHANGES REQUESTED
-
-### Summary
-[Brief summary of changes]
+**Goal:** turn findings into actionable comments at the right place.
 
-### Critical Issues (Must Fix)
-1. **[Category]** - [file:line]
-   - Issue: [description]
-   - Fix: [how to fix]
-   - Reference: [architecture doc section if applicable]
+### Decision (pick one)
 
-2. **[Category]** - [file:line]
-   - Issue: [description]
-   - Fix: [how to fix]
+| Decision | When |
+|----------|------|
+| **APPROVE** | 0 CRITICAL / HIGH; LOW only |
+| **REQUEST CHANGES** | Any CRITICAL or HIGH; or multiple MEDIUM in same area |
+| **COMMENT** | Only style / nit comments; or asking questions before final review |
 
-### Non-Critical Issues (Should Fix)
-- [ ] [file:line] - [description]
-- [ ] [file:line] - [description]
+### Inline comment format
 
-### Suggestions (Optional)
-- [suggestion 1]
-- [suggestion 2]
+Be specific. File + line + rationale + suggested fix:
 
-### Recommendation
-**REQUEST CHANGES** - Please address critical issues
 ```
-
-#### Option C: COMMENT 💬
-
-Use when:
-- Need clarification
-- Questions about approach
-- Discussion needed
-
-```markdown
-## Review: 💬 COMMENTS
-
-### Questions
-1. [Question about approach/design]
-2. [Question about implementation]
-
-### Discussion Points
-- [Point 1]
-- [Point 2]
-
-### Recommendation
-**COMMENT** - Let's discuss before proceeding
+file: internal/wallet/usecases/withdraw.go:42
+severity: HIGH
+issue: Business logic in handler — `if wallet.Balance < amount` should live in
+the Withdraw usecase, not here. The handler should just call usecase and
+return the error.
+suggest:
+  // handler
+  result, err := s.WithdrawUsecase.Execute(ctx, req)
+
+  // usecase
+  func (u *WithdrawUsecase) Execute(ctx, req) (Result, error) {
+      if !wallet.HasSufficientBalance(amount) { return ErrInsufficient }
+      // ...
+  }
 ```
 
-### Actions
-
-1. Post review on GitHub:
-   ```bash
-   # Approve
-   gh pr review [PR_NUMBER] --approve --body "[feedback]"
-
-   # Request changes
-   gh pr review [PR_NUMBER] --request-changes --body "[feedback]"
-
-   # Comment
-   gh pr review [PR_NUMBER] --comment --body "[feedback]"
-   ```
-
-2. Add inline comments for specific issues:
-   ```bash
-   gh pr comment [PR_NUMBER] --body "[comment]"
-   ```
+### Summary comment (top of PR)
 
-3. Update PR status if needed:
-   ```bash
-   # Add labels
-   gh pr edit [PR_NUMBER] --add-label "needs-changes"
-   gh pr edit [PR_NUMBER] --add-label "security-review"
-   gh pr edit [PR_NUMBER] --add-label "architecture-review"
-   ```
-
-### Feedback Principles
-
-1. **Be Specific**: Point to exact file and line
-2. **Be Constructive**: Suggest solutions, not just problems
-3. **Be Kind**: Assume good intent
-4. **Reference Docs**: Link to architecture docs when relevant
-5. **Prioritize**: Separate critical from optional
-6. **Explain Why**: Help author learn
-
-### Example Inline Comment
 ```markdown
-**[file.ts:123]** - Architecture Violation
+## Review Summary
+**Decision:** REQUEST CHANGES
 
-Issue: Business logic in presentation layer
-Reference: `react-frontend.md` - Section 3.2
+**Must fix (HIGH):**
+- [ ] `withdraw.go:42` — business logic moved out of handler
+- [ ] `withdraw.go:88` — missing input validation on `amount`
 
-This violates the architecture pattern. Business logic should be in:
-- `src/domain/usecases/`
+**Should fix (MEDIUM):**
+- [ ] `withdraw_test.go` — only happy path tested, add insufficient-balance case
+- [ ] `wallet_store.go:120` — N+1 query loading transactions
 
-Suggested fix:
-1. Create `src/domain/usecases/calculateTotal.ts`
-2. Move logic there
-3. Call from component
+**Nits (LOW):**
+- [ ] `helper.go:5` — rename `helper` to something specific
 
-Example:
-\`\`\`typescript
-// Component
-const total = await calculateTotalUseCase.execute(items);
-
-// Usecase
-export class CalculateTotalUseCase {
-  execute(items: Item[]): number {
-    // logic here
-  }
-}
-\`\`\`
+**What looked great:**
+- Clean port interface, good test naming, clear PR description.
 ```
 
 ### Gate
-- [ ] Feedback provided
-- [ ] Decision made (approve/request/comment)
-- [ ] Review posted to GitHub
+- [ ] Decision matches severity rules
+- [ ] Every HIGH+ has file:line + suggested fix
+- [ ] Summary lists must-fix vs should-fix vs nits
+- [ ] Acknowledged what's good (not just criticism)
 
 ---
 
-## Quick Reference
-
-### Architecture Docs
-| Stack | Doc |
-|-------|-----|
-| All | `clean-architecture.md` |
-| Flutter | `flutter-mobile.md` |
-| React | `react-frontend.md` |
-| Go | `go-backend.md` |
-| Laravel | `laravel-backend.md` |
-| Remix | `remix-fullstack.md` |
-| Monorepo | `monorepo.md` |
-
-### Review Dimensions
-| Dimension | Focus |
-|-----------|-------|
-| Architecture | Layer boundaries, patterns, structure per doc |
-| Code Quality | Readability, naming, complexity, DRY |
-| Security | Validation, auth, secrets, vulnerabilities |
-| Performance | Queries, caching, algorithms, memory |
-| Testing | Coverage, quality, edge cases per doc |
-
-### Severity Levels
-
-| Level | Action | Examples |
-|-------|--------|----------|
-| 🚨 **Critical** | Must fix before merge | Security holes, architecture violations, data loss bugs |
-| ⚠️ **High** | Should fix before merge | Missing tests, poor error handling, performance issues |
-| ℹ️ **Medium** | Can fix after merge | Code smells, minor refactoring, missing comments |
-| 💡 **Low** | Optional | Style suggestions, micro-optimizations |
-
-### Common Issues Checklist
-
-**Architecture** (check against doc):
-- [ ] Business logic in UI layer
-- [ ] UI code in domain layer
-- [ ] Direct database access from UI
-- [ ] Circular dependencies
-- [ ] Wrong folder structure
-
-**Security**:
-- [ ] Hardcoded secrets
-- [ ] SQL injection risks
-- [ ] XSS vulnerabilities
-- [ ] Missing auth checks
-- [ ] Sensitive data logged
-
-**Performance**:
-- [ ] N+1 queries
-- [ ] Missing indexes
-- [ ] Inefficient algorithms
-- [ ] Memory leaks
-- [ ] Large bundle sizes
-
-**Testing**:
-- [ ] No tests for new code
-- [ ] Tests not following doc patterns
-- [ ] Missing edge cases
-- [ ] Flaky tests
-
-### GitHub CLI Commands
+## Phase 5: POST
 
 ```bash
-# Fetch PR
-gh pr view [NUMBER]
-gh pr diff [NUMBER]
-gh pr checks [NUMBER]
-
-# Review
-gh pr review [NUMBER] --approve
-gh pr review [NUMBER] --request-changes
-gh pr review [NUMBER] --comment
-
-# Comment
-gh pr comment [NUMBER] --body "comment"
-
-# Labels
-gh pr edit [NUMBER] --add-label "label"
+# Inline comments (one per finding)
+gh pr review $PR --request-changes --body "$(cat summary.md)"
+# or
+gh pr review $PR --approve --body "LGTM, see one nit"
+# or
+gh pr review $PR --comment --body "Questions before final review"
+
+# Optional: label
+gh pr edit $PR --add-label "needs-changes"
 ```
 
+### Gate
+- [ ] Review posted to GitHub
+- [ ] Author has clear next-step list
+
 ---
 
-## Success Criteria
+## Hard Rules
 
-PR review is complete when:
-1. All 5 review dimensions checked
-2. Architecture compliance verified against doc
-3. Clear feedback provided
-4. Decision made (approve/request/comment)
-5. Review posted to GitHub
-6. Author knows exactly what to do next
+- **Don't review red CI** — ask author to fix tests / lint first
+- **Don't bikeshed style** when the team has a linter — let the tool flag it
+- **Always include "what went well"** — pure-criticism reviews demoralize
+- **One severity per finding** — don't grade-inflate to push for a fix
+- **File:line for every HIGH+** — author shouldn't have to grep for what you mean
 
 ---
 
@@ -614,8 +223,9 @@ PR review is complete when:
 
 | Phase | Agent | Purpose |
 |-------|-------|---------|
-| ANALYZE | `@clean-architect` | Architecture compliance |
-| REVIEW | `@code-reviewer` | Code quality + best practices |
-| REVIEW | `@security-audit` | Security vulnerabilities |
-| REVIEW | `@perf-optimizer` | Performance analysis |
-| REVIEW | `@test-writer` | Test coverage + quality |
+| ANALYZE | `@clean-architect` | Architecture context |
+| REVIEW 3.1 | `@clean-architect` | Architecture compliance |
+| REVIEW 3.2 | `@security-audit` | Security findings |
+| REVIEW 3.3 | `@perf-optimizer` | N+1, indexes, slow paths |
+| REVIEW 3.4 | `@test-writer` | Coverage + test quality |
+| REVIEW 3.5 | `@code-reviewer` | Naming + quality |