aigroup-workflow 2.1.2 → 2.2.0

package/skills/quality/code-reviewer/references/feedback-examples.md

@@ -0,0 +1,144 @@
+# Feedback Examples
+
+## Good vs Bad Feedback
+
+### Be Specific, Not Vague
+
+```markdown
+BAD: "This is confusing"
+
+GOOD: "This function handles both validation and persistence. Consider
+      splitting into `validateUser()` and `saveUser()` for single
+      responsibility and easier testing."
+```
+
+### Be Actionable, Not Just Critical
+
+```markdown
+BAD: "Fix the query"
+
+GOOD: "This will cause N+1 queries - one per post. Use `include: [Author]`
+      to eager load authors in a single query. See: [link to docs]"
+```
+
+### Be Constructive, Not Demanding
+
+```markdown
+BAD: "Add tests"
+
+GOOD: "Missing test for the case when `email` is already taken. Add a test
+      that verifies 409 is returned with appropriate error message."
+```
+
+### Ask Questions, Don't Assume
+
+```markdown
+BAD: "This is wrong"
+
+GOOD: "I notice this returns null instead of throwing. Is that intentional?
+      The other methods throw on not-found. Should this be consistent?"
+```
+
+## Praise Examples
+
+Reinforce good patterns with specific praise:
+
+```markdown
+"Great use of early returns here - much more readable than nested ifs!"
+
+"Nice extraction of this validation logic into a reusable function."
+
+"Excellent error messages - they'll help debugging in production."
+
+"Good choice using a discriminated union here instead of optional fields."
+
+"Appreciate the comprehensive test coverage, especially the edge cases."
+```
+
+## Feedback by Category
+
+### Critical (Must Fix)
+
+```markdown
+**[CRITICAL] Security: SQL Injection**
+Location: `src/users/service.ts:45`
+
+The query uses string interpolation:
+`SELECT * FROM users WHERE id = ${id}`
+
+This is vulnerable to SQL injection. Use parameterized query:
+`db.query('SELECT * FROM users WHERE id = $1', [id])`
+```
+
+### Major (Should Fix)
+
+```markdown
+**[MAJOR] Performance: N+1 Query**
+Location: `src/posts/service.ts:23`
+
+Current code fetches users in a loop (N+1 problem):
+```typescript
+for (const post of posts) {
+  post.author = await User.findById(post.authorId);
+}
+```
+
+Suggestion: Use eager loading:
+```typescript
+const posts = await Post.findAll({ include: [User] });
+```
+
+Impact: ~100 extra DB queries per request with current approach.
+```
+
+### Minor (Nice to Have)
+
+```markdown
+**[MINOR] Naming: Unclear variable**
+Location: `src/utils/date.ts:12`
+
+`d` is unclear. Consider `createdDate` or `timestamp` for better readability.
+
+**[MINOR] Style: Prefer const**
+Location: `src/config/index.ts:8`
+
+`let config` is never reassigned. Use `const` for immutability.
+```
+
+## Question Format
+
+```markdown
+**[QUESTION]**
+Location: `src/orders/service.ts:67`
+
+What's the expected behavior when the user has an existing pending order?
+Should this:
+- Return the existing order?
+- Create a new one anyway?
+- Return an error?
+```
+
+## Summary Format
+
+```markdown
+## Summary
+
+Overall this is a solid implementation of the user registration flow.
+The validation logic is clean and the error handling is comprehensive.
+
+**Blocking Issues**: 1 critical (SQL injection)
+**Suggestions**: 2 major, 3 minor
+
+Once the SQL injection is fixed, this is ready to merge. The major
+suggestions are performance improvements worth considering.
+```
+
+## Quick Reference
+
+| Feedback Type | Tone | Required Action |
+|---------------|------|-----------------|
+| Critical | Firm, clear | Must fix before merge |
+| Major | Suggestive | Should fix |
+| Minor | Optional | Nice to have |
+| Praise | Positive | None - reinforcement |
+| Question | Curious | Response needed |

package/skills/quality/code-reviewer/references/receiving-feedback.md

@@ -0,0 +1,238 @@
+# Receiving Feedback
+
+---
+
+## Core Mindset
+
+> "Verify before implementing. Ask before assuming. Technical correctness over social comfort."
+
+Code review feedback is a technical discussion, not a social one. Focus on the code, not on feelings.
+
+---
+
+## The Six-Step Process
+
+### Step 1: Read Completely
+
+**Without reacting.** Read the entire comment before forming any response.
+
+```markdown
+❌ BAD: Read first sentence → start typing defense
+✅ GOOD: Read entire comment → understand full context → then respond
+```
+
+### Step 2: Restate Requirements
+
+Rephrase the reviewer's feedback in your own words to confirm understanding.
+
+```markdown
+Reviewer: "This function is doing too much. It handles validation,
+transformation, and persistence all in one place."
+
+Your restatement: "You're suggesting I split this into three separate
+functions: validate(), transform(), and persist()?"
+```
+
+### Step 3: Check Against Codebase
+
+Verify the feedback against actual code conditions before responding.
+
+```typescript
+// Reviewer says: "This will throw if user is null"
+
+// Check the code:
+function getUsername(user: User): string {
+  return user.name;  // No null check - reviewer is correct
+}
+
+// Or discover context:
+function getUsername(user: User): string {
+  return user.name;  // TypeScript enforces User, null not possible
+}
+```
+
+### Step 4: Evaluate Technical Soundness
+
+Consider whether the feedback applies to your specific stack and context.
+
+```markdown
+Reviewer: "You should use useMemo here for performance"
+
+Evaluate:
+- Is this component re-rendering frequently? → Check React DevTools
+- Is the computation expensive? → Profile it
+- Does React 19's compiler auto-optimize this? → Check version
+```
+
+### Step 5: Respond with Substance
+
+Provide technical acknowledgment or reasoned objection.
+
+```markdown
+✅ GOOD: "Fixed. Split into validate(), transform(), persist()
+         at lines 24, 45, 67."
+
+✅ GOOD: "Respectfully disagree. This list has max 5 items
+         (see schema.ts:12), so filter performance is O(5)."
+
+❌ BAD: "You're absolutely right! Great catch!"
+❌ BAD: "I don't think that's necessary."
+```
+
+### Step 6: Implement One at a Time
+
+Address each piece of feedback individually with verification.
+
+```markdown
+Feedback item 1: Add null check
+→ Implement → Test → Commit → Verify → Move to next
+
+Feedback item 2: Extract helper function
+→ Implement → Test → Commit → Verify → Move to next
+
+NOT: Try to address all feedback in one massive commit
+```
+
+---
+
+## Avoiding Agreement Theater
+
+### The Problem
+
+Performative agreement wastes time and provides no information. When you write "Great point!" you're adding noise, not signal.
+
+### Forbidden Phrases
+
+| Phrase | Why It's Wrong |
+|--------|----------------|
+| "You're absolutely right!" | Sycophantic, adds no information |
+| "Great point!" | Empty praise, not a response |
+| "Excellent feedback!" | Flattery, not engagement |
+| "Thanks for catching this!" | Unnecessary, just fix it |
+| "I really appreciate..." | Social fluff, not technical |
+
+### Actions Demonstrate Understanding
+
+```markdown
+❌ "You're absolutely right! Great catch on that null check!
+    Thanks so much for pointing this out!"
+
+✅ "Fixed. Added null check at line 42."
+```
+
+The code change shows you understood. Words are redundant.
+
+### When Acknowledgment IS Appropriate
+
+Brief, technical acknowledgment when learning something new:
+
+```markdown
+✅ "I wasn't aware of that edge case. Added handling at line 42."
+✅ "Good point about thread safety. Added mutex at line 67."
+```
+
+---
+
+## When to Push Back
+
+### Valid Reasons to Disagree
+
+Push back with technical reasoning when feedback:
+
+| Situation | How to Respond |
+|-----------|----------------|
+| Breaks existing functionality | "This change would break Feature X (see test at tests/feature-x.spec.ts:34)" |
+| Lacks full codebase context | "This pattern exists because of Y (see architecture.md#constraints)" |
+| Violates YAGNI | "This flexibility isn't needed yet - only one caller exists" |
+| Is technically incorrect | "This actually works because of Z (link to docs)" |
+| Conflicts with established architecture | "This conflicts with our JWT approach (see auth/README.md)" |
+
+### Good Pushback Format
+
+```markdown
+## Template
+This conflicts with [X]. [Evidence]. Was that the intent, or should we [alternative]?
+
+## Example
+This conflicts with our JWT authentication architecture (see auth/token.js:45).
+Switching to sessions would require restructuring the API middleware.
+Was that the intent, or should we keep JWT?
+```
+
+### Bad Pushback
+
+```markdown
+❌ "I don't think that's right."
+❌ "That won't work."
+❌ "We've always done it this way."
+❌ "That's too much work."
+```
+
+---
+
+## Verification Before Claiming Fixed
+
+### The Checklist
+
+Before writing "Fixed" or "Done":
+
+- [ ] Change is implemented
+- [ ] Tests pass (full suite, not just changed files)
+- [ ] Specific behavior mentioned in feedback is verified
+- [ ] Edge cases are tested
+- [ ] No unintended side effects introduced
+
+### Acceptable Responses
+
+```markdown
+✅ "Fixed. Added null check. Tests pass."
+✅ "Fixed at line 42. Verified with test case X."
+✅ "Implemented. All 47 tests pass."
+```
+
+### Unacceptable Responses
+
+```markdown
+❌ "I think this addresses your concern."
+❌ "Should be fixed now."
+❌ "Done, I believe."
+❌ "Fixed (probably)."
+```
+
+### When You Can't Verify
+
+If you cannot verify a fix:
+
+```markdown
+✅ "Implemented the change, but I'm unable to verify because
+    [specific reason]. Can you confirm on your end?"
+```
+
+---
+
+## Quick Reference
+
+| Situation | Response |
+|-----------|----------|
+| Reviewer is correct | "Fixed. [What you changed]." |
+| You need clarification | "To confirm: you're suggesting [restatement]?" |
+| Reviewer is incorrect | "This works because [evidence]. [Link to proof]." |
+| You disagree on approach | "This conflicts with [X]. Should we [alternative]?" |
+| You learned something | "I wasn't aware of [X]. Fixed at line [N]." |
+| You can't verify | "Implemented. Unable to verify because [reason]." |
+
+---
+
+## Anti-Patterns
+
+| Pattern | Problem | Fix |
+|---------|---------|-----|
+| Defensive responses | Creates conflict, wastes time | Assume good faith, respond technically |
+| Apologetic responses | Unprofessional, adds noise | Just fix it |
+| Delayed responses | Blocks review cycle | Respond within hours, not days |
+| Vague responses | Leaves reviewer uncertain | Be specific about changes |
+| Ignoring feedback | Disrespectful, creates friction | Address every point |
+
+---
+
+*Content adapted from [obra/superpowers](https://github.com/obra/superpowers) by Jesse Vincent (@obra), MIT License.*

package/skills/quality/code-reviewer/references/report-template.md

@@ -0,0 +1,109 @@
+# Report Template
+
+## Full Review Report Template
+
+```markdown
+# Code Review: [PR Title]
+
+## Summary
+[1-2 sentence overview of the changes and overall assessment]
+
+**Verdict**: [ ] Approve | [x] Request Changes | [ ] Comment
+
+## Critical Issues (Must Fix)
+
+### 1. [File:Line] Security: SQL Injection Risk
+- **Current**: String interpolation in query
+- **Suggested**: Use parameterized query
+- **Impact**: Potential data breach
+
+```typescript
+// Current (vulnerable)
+const query = `SELECT * FROM users WHERE id = ${id}`;
+
+// Suggested (secure)
+const query = 'SELECT * FROM users WHERE id = $1';
+db.query(query, [id]);
+```
+
+## Major Issues (Should Fix)
+
+### 1. [File:Line] Performance: N+1 Query
+- **Current**: Fetching users in loop
+- **Suggested**: Use eager loading with include
+- **Impact**: ~100 extra DB queries per request
+
+### 2. [File:Line] Logic: Missing edge case
+- **Current**: No handling for empty array
+- **Suggested**: Add guard clause
+- **Impact**: Potential runtime error
+
+## Minor Issues (Nice to Have)
+
+### 1. [File:Line] Naming: Unclear variable name
+- **Current**: `d`
+- **Suggested**: `createdDate`
+
+### 2. [File:Line] Style: Inconsistent formatting
+- **Current**: Mixed quotes
+- **Suggested**: Use single quotes consistently
+
+## Positive Feedback
+- Clean separation of concerns in service layer
+- Comprehensive input validation on DTOs
+- Good test coverage for edge cases
+- Excellent error messages
+
+## Questions for Author
+- What's the expected behavior when X happens?
+- Should this support pagination for large datasets?
+- Is the retry logic intentional or accidental?
+
+## Test Coverage Assessment
+- [ ] Happy path tested
+- [x] Error cases tested
+- [ ] Edge cases tested (missing empty array test)
+- [x] Integration tests present
+
+## Checklist
+- [x] No security vulnerabilities
+- [ ] Performance is acceptable (N+1 issue)
+- [x] Code is readable
+- [x] Tests are adequate
+- [x] Documentation is present
+```
+
+## Verdict Guidelines
+
+| Verdict | When to Use |
+|---------|-------------|
+| **Approve** | No blocking issues, minor suggestions only |
+| **Request Changes** | Critical or major issues must be fixed |
+| **Comment** | Questions need answers, no blocking issues |
+
+## Severity Definitions
+
+| Severity | Definition | Examples |
+|----------|------------|----------|
+| **Critical** | Security risk, data loss, crashes | SQL injection, auth bypass |
+| **Major** | Significant performance, maintainability | N+1 queries, god functions |
+| **Minor** | Style, naming, small improvements | Variable names, formatting |
+
+## Time Boxing
+
+| Section | Suggested Time |
+|---------|----------------|
+| Context & understanding | 5 minutes |
+| Critical/security review | 10 minutes |
+| Logic & performance | 15 minutes |
+| Tests review | 10 minutes |
+| Writing report | 10 minutes |
+| **Total** | ~50 minutes |
+
+## Quick Checks Before Submitting
+
+- [ ] All critical issues have clear remediation
+- [ ] Major issues explain the impact
+- [ ] At least one positive comment included
+- [ ] Questions are specific and answerable
+- [ ] Verdict matches the issues found

package/skills/quality/code-reviewer/references/review-checklist.md

@@ -0,0 +1,88 @@
+# Review Checklist
+
+## Comprehensive Review Checklist
+
+| Category | Key Questions |
+|----------|---------------|
+| **Design** | Does it fit existing patterns? Right abstraction level? |
+| **Logic** | Edge cases handled? Race conditions? Null checks? |
+| **Security** | Input validated? Auth checked? Secrets safe? |
+| **Performance** | N+1 queries? Memory leaks? Caching needed? |
+| **Tests** | Adequate coverage? Edge cases tested? Mocks appropriate? |
+| **Naming** | Clear, consistent, intention-revealing? |
+| **Error Handling** | Errors caught? Meaningful messages? Logged? |
+| **Documentation** | Public APIs documented? Complex logic explained? |
+
+## Review Process
+
+### 1. Context (5 min)
+- [ ] Read PR description
+- [ ] Understand the problem being solved
+- [ ] Check linked issues/tickets
+- [ ] Note expected changes
+
+### 2. Structure (10 min)
+- [ ] Review file organization
+- [ ] Check architectural fit
+- [ ] Verify design patterns used
+- [ ] Note any breaking changes
+
+### 3. Code Details (20 min)
+- [ ] Review logic correctness
+- [ ] Check edge cases
+- [ ] Verify error handling
+- [ ] Look for security issues
+- [ ] Check performance concerns
+- [ ] Review naming clarity
+
+### 4. Tests (10 min)
+- [ ] Verify test coverage
+- [ ] Check test quality
+- [ ] Look for edge case tests
+- [ ] Ensure mocks are appropriate
+
+### 5. Final Pass (5 min)
+- [ ] Note positive patterns
+- [ ] Prioritize feedback
+- [ ] Write summary
+
+## Category Deep Dive
+
+### Design Questions
+- Does this change belong in this file/module?
+- Is the abstraction level appropriate?
+- Could this be simpler?
+- Does it follow existing patterns?
+- Is it extensible without modification?
+
+### Logic Questions
+- What happens with null/undefined inputs?
+- Are boundary conditions handled?
+- Could there be race conditions?
+- Is the order of operations correct?
+- Are all code paths tested?
+
+### Security Questions
+- Is all user input validated?
+- Are SQL queries parameterized?
+- Is output properly encoded?
+- Are secrets handled safely?
+- Is authentication checked?
+- Is authorization enforced?
+
+### Performance Questions
+- Are there N+1 query patterns?
+- Is data fetched efficiently?
+- Are expensive operations cached?
+- Could this cause memory leaks?
+- Is pagination implemented?
+
+## Quick Reference
+
+| Review Focus | Time % |
+|--------------|--------|
+| Context & PR description | 10% |
+| Architecture & design | 20% |
+| Code logic & details | 40% |
+| Tests & coverage | 20% |
+| Final review & summary | 10% |