ai-qakit 1.0.0

package/templates/.claude/skills/code-review/references/code-review-reception.md

@@ -0,0 +1,209 @@
+---
+name: receiving-code-review
+description: Use when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation
+---
+
+# Code Review Reception
+
+## Overview
+
+Code review requires technical evaluation, not emotional performance.
+
+**Core principle:** Verify before implementing. Ask before assuming. Technical correctness over social comfort.
+
+## The Response Pattern
+
+```
+WHEN receiving code review feedback:
+
+1. READ: Complete feedback without reacting
+2. UNDERSTAND: Restate requirement in own words (or ask)
+3. VERIFY: Check against codebase reality
+4. EVALUATE: Technically sound for THIS codebase?
+5. RESPOND: Technical acknowledgment or reasoned pushback
+6. IMPLEMENT: One item at a time, test each
+```
+
+## Forbidden Responses
+
+**NEVER:**
+- "You're absolutely right!" (explicit CLAUDE.md violation)
+- "Great point!" / "Excellent feedback!" (performative)
+- "Let me implement that now" (before verification)
+
+**INSTEAD:**
+- Restate the technical requirement
+- Ask clarifying questions
+- Push back with technical reasoning if wrong
+- Just start working (actions > words)
+
+## Handling Unclear Feedback
+
+```
+IF any item is unclear:
+  STOP - do not implement anything yet
+  ASK for clarification on unclear items
+
+WHY: Items may be related. Partial understanding = wrong implementation.
+```
+
+**Example:**
+```
+your human partner: "Fix 1-6"
+You understand 1,2,3,6. Unclear on 4,5.
+
+❌ WRONG: Implement 1,2,3,6 now, ask about 4,5 later
+✅ RIGHT: "I understand items 1,2,3,6. Need clarification on 4 and 5 before proceeding."
+```
+
+## Source-Specific Handling
+
+### From your human partner
+- **Trusted** - implement after understanding
+- **Still ask** if scope unclear
+- **No performative agreement**
+- **Skip to action** or technical acknowledgment
+
+### From External Reviewers
+```
+BEFORE implementing:
+  1. Check: Technically correct for THIS codebase?
+  2. Check: Breaks existing functionality?
+  3. Check: Reason for current implementation?
+  4. Check: Works on all platforms/versions?
+  5. Check: Does reviewer understand full context?
+
+IF suggestion seems wrong:
+  Push back with technical reasoning
+
+IF can't easily verify:
+  Say so: "I can't verify this without [X]. Should I [investigate/ask/proceed]?"
+
+IF conflicts with your human partner's prior decisions:
+  Stop and discuss with your human partner first
+```
+
+**your human partner's rule:** "External feedback - be skeptical, but check carefully"
+
+## YAGNI Check for "Professional" Features
+
+```
+IF reviewer suggests "implementing properly":
+  grep codebase for actual usage
+
+  IF unused: "This endpoint isn't called. Remove it (YAGNI)?"
+  IF used: Then implement properly
+```
+
+**your human partner's rule:** "You and reviewer both report to me. If we don't need this feature, don't add it."
+
+## Implementation Order
+
+```
+FOR multi-item feedback:
+  1. Clarify anything unclear FIRST
+  2. Then implement in this order:
+     - Blocking issues (breaks, security)
+     - Simple fixes (typos, imports)
+     - Complex fixes (refactoring, logic)
+  3. Test each fix individually
+  4. Verify no regressions
+```
+
+## When To Push Back
+
+Push back when:
+- Suggestion breaks existing functionality
+- Reviewer lacks full context
+- Violates YAGNI (unused feature)
+- Technically incorrect for this stack
+- Legacy/compatibility reasons exist
+- Conflicts with your human partner's architectural decisions
+
+**How to push back:**
+- Use technical reasoning, not defensiveness
+- Ask specific questions
+- Reference working tests/code
+- Involve your human partner if architectural
+
+**Signal if uncomfortable pushing back out loud:** "Strange things are afoot at the Circle K"
+
+## Acknowledging Correct Feedback
+
+When feedback IS correct:
+```
+✅ "Fixed. [Brief description of what changed]"
+✅ "Good catch - [specific issue]. Fixed in [location]."
+✅ [Just fix it and show in the code]
+
+❌ "You're absolutely right!"
+❌ "Great point!"
+❌ "Thanks for catching that!"
+❌ "Thanks for [anything]"
+❌ ANY gratitude expression
+```
+
+**Why no thanks:** Actions speak. Just fix it. The code itself shows you heard the feedback.
+
+**If you catch yourself about to write "Thanks":** DELETE IT. State the fix instead.
+
+## Gracefully Correcting Your Pushback
+
+If you pushed back and were wrong:
+```
+✅ "You were right - I checked [X] and it does [Y]. Implementing now."
+✅ "Verified this and you're correct. My initial understanding was wrong because [reason]. Fixing."
+
+❌ Long apology
+❌ Defending why you pushed back
+❌ Over-explaining
+```
+
+State the correction factually and move on.
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Performative agreement | State requirement or just act |
+| Blind implementation | Verify against codebase first |
+| Batch without testing | One at a time, test each |
+| Assuming reviewer is right | Check if breaks things |
+| Avoiding pushback | Technical correctness > comfort |
+| Partial implementation | Clarify all items first |
+| Can't verify, proceed anyway | State limitation, ask for direction |
+
+## Real Examples
+
+**Performative Agreement (Bad):**
+```
+Reviewer: "Remove legacy code"
+❌ "You're absolutely right! Let me remove that..."
+```
+
+**Technical Verification (Good):**
+```
+Reviewer: "Remove legacy code"
+✅ "Checking... build target is 10.15+, this API needs 13+. Need legacy for backward compat. Current impl has wrong bundle ID - fix it or drop pre-13 support?"
+```
+
+**YAGNI (Good):**
+```
+Reviewer: "Implement proper metrics tracking with database, date filters, CSV export"
+✅ "Grepped codebase - nothing calls this endpoint. Remove it (YAGNI)? Or is there usage I'm missing?"
+```
+
+**Unclear Item (Good):**
+```
+your human partner: "Fix items 1-6"
+You understand 1,2,3,6. Unclear on 4,5.
+✅ "Understand 1,2,3,6. Need clarification on 4 and 5 before implementing."
+```
+
+## The Bottom Line
+
+**External feedback = suggestions to evaluate, not orders to follow.**
+
+Verify. Question. Then implement.
+
+No performative agreement. Technical rigor always.

package/templates/.claude/skills/code-review/references/human-code-review-practices.md

@@ -0,0 +1,370 @@
+# Human Code Review Best Practices
+
+When reviewing code or providing feedback to human developers, apply these proven patterns for constructive, effective code review.
+
+## Review Mindset
+
+**Goals:**
+- Catch bugs and edge cases
+- Ensure code maintainability
+- Share knowledge across team
+- Enforce coding standards
+- Improve design and architecture
+
+**Not the goals:**
+- Show off knowledge
+- Nitpick formatting (use linters)
+- Block progress unnecessarily
+- Rewrite to your preference
+
+## Effective Feedback Patterns
+
+**Good feedback is:**
+- Specific and actionable
+- Educational, not judgmental
+- Focused on the code, not the person
+- Balanced (praise good work too)
+- Prioritized (critical vs nice-to-have)
+
+### Examples
+
+```markdown
+❌ Bad: "This is wrong."
+✅ Good: "This could cause a race condition when multiple users
+         access simultaneously. Consider using a mutex here."
+
+❌ Bad: "Why didn't you use X pattern?"
+✅ Good: "Have you considered the Repository pattern? It would
+         make this easier to test. Here's an example: [link]"
+
+❌ Bad: "Rename this variable."
+✅ Good: "[nit] Consider `userCount` instead of `uc` for
+         clarity. Not blocking if you prefer to keep it."
+```
+
+## Review Process (3 Phases)
+
+### Phase 1: High-Level Review (5-10 minutes)
+
+**Architecture & Design:**
+- Does the solution fit the problem?
+- Are there simpler approaches?
+- Is it consistent with existing patterns?
+- Will it scale?
+
+**File Organization:**
+- Are new files in the right places?
+- Is code grouped logically?
+- Are there duplicate files?
+
+**Testing Strategy:**
+- Are there tests?
+- Do tests cover edge cases?
+- Are tests readable?
+
+### Phase 2: Line-by-Line Review (10-20 minutes)
+
+**Logic & Correctness:**
+- Edge cases handled?
+- Off-by-one errors?
+- Null/undefined checks?
+- Race conditions?
+
+**Security:**
+- Input validation?
+- SQL injection risks?
+- XSS vulnerabilities?
+- Sensitive data exposure?
+
+**Performance:**
+- N+1 queries?
+- Unnecessary loops?
+- Memory leaks?
+- Blocking operations?
+
+**Maintainability:**
+- Clear variable names?
+- Functions doing one thing?
+- Complex code commented?
+- Magic numbers extracted?
+
+### Phase 3: Summary & Decision (2-3 minutes)
+
+1. Summarize key concerns
+2. Highlight what you liked
+3. Make clear decision:
+   - ✅ Approve
+   - 💬 Comment (minor suggestions)
+   - 🔄 Request Changes (must address)
+4. Offer to pair if complex
+
+## Review Techniques
+
+### Technique 1: The Question Approach
+
+Instead of stating problems, ask questions to encourage thinking:
+
+```markdown
+❌ "This will fail if the list is empty."
+✅ "What happens if `items` is an empty array?"
+
+❌ "You need error handling here."
+✅ "How should this behave if the API call fails?"
+
+❌ "This is inefficient."
+✅ "I see this loops through all users. Have we considered
+    the performance impact with 100k users?"
+```
+
+### Technique 2: Suggest, Don't Command
+
+```markdown
+❌ "You must change this to use async/await"
+✅ "Suggestion: async/await might make this more readable:
+    ```typescript
+    async function fetchUser(id: string) {
+        const user = await db.query('SELECT * FROM users WHERE id = ?', id);
+        return user;
+    }
+    ```
+    What do you think?"
+
+❌ "Extract this into a function"
+✅ "This logic appears in 3 places. Would it make sense to
+    extract it into a shared utility function?"
+```
+
+### Technique 3: Differentiate Severity
+
+Use labels to indicate priority:
+
+```markdown
+🔴 [blocking] - Must fix before merge
+🟡 [important] - Should fix, discuss if disagree
+🟢 [nit] - Nice to have, not blocking
+💡 [suggestion] - Alternative approach to consider
+📚 [learning] - Educational comment, no action needed
+🎉 [praise] - Good work, keep it up!
+
+Example:
+"🔴 [blocking] This SQL query is vulnerable to injection.
+ Please use parameterized queries."
+
+"🟢 [nit] Consider renaming `data` to `userData` for clarity."
+
+"🎉 [praise] Excellent test coverage! This will catch edge cases."
+```
+
+## Security Review Checklist
+
+### Authentication & Authorization
+- [ ] Is authentication required where needed?
+- [ ] Are authorization checks before every action?
+- [ ] Is JWT validation proper (signature, expiry)?
+- [ ] Are API keys/secrets properly secured?
+
+### Input Validation
+- [ ] All user inputs validated?
+- [ ] File uploads restricted (size, type)?
+- [ ] SQL queries parameterized?
+- [ ] XSS protection (escape output)?
+
+### Data Protection
+- [ ] Passwords hashed (bcrypt/argon2)?
+- [ ] Sensitive data encrypted at rest?
+- [ ] HTTPS enforced for sensitive data?
+- [ ] PII handled according to regulations?
+
+### Common Vulnerabilities
+- [ ] No eval() or similar dynamic execution?
+- [ ] No hardcoded secrets?
+- [ ] CSRF protection for state-changing operations?
+- [ ] Rate limiting on public endpoints?
+
+## Language-Specific Patterns
+
+### Python Code Review
+
+```python
+# ❌ Mutable default arguments
+def add_item(item, items=[]):  # Bug! Shared across calls
+    items.append(item)
+    return items
+
+# ✅ Use None as default
+def add_item(item, items=None):
+    if items is None:
+        items = []
+    items.append(item)
+    return items
+
+# ❌ Catching too broad
+try:
+    result = risky_operation()
+except:  # Catches everything, even KeyboardInterrupt!
+    pass
+
+# ✅ Catch specific exceptions
+try:
+    result = risky_operation()
+except ValueError as e:
+    logger.error(f"Invalid value: {e}")
+    raise
+```
+
+### TypeScript/JavaScript Code Review
+
+```typescript
+// ❌ Using any defeats type safety
+function processData(data: any) {  // Avoid any
+    return data.value;
+}
+
+// ✅ Use proper types
+interface DataPayload {
+    value: string;
+}
+function processData(data: DataPayload) {
+    return data.value;
+}
+
+// ❌ Not handling async errors
+async function fetchUser(id: string) {
+    const response = await fetch(`/api/users/${id}`);
+    return response.json();  // What if network fails?
+}
+
+// ✅ Handle errors properly
+async function fetchUser(id: string): Promise<User> {
+    try {
+        const response = await fetch(`/api/users/${id}`);
+        if (!response.ok) {
+            throw new Error(`HTTP ${response.status}`);
+        }
+        return await response.json();
+    } catch (error) {
+        console.error('Failed to fetch user:', error);
+        throw error;
+    }
+}
+```
+
+## Test Quality Review
+
+```typescript
+// ❌ Poor test: Implementation detail testing
+test('increments counter variable', () => {
+    const component = render(<Counter />);
+    const button = component.getByRole('button');
+    fireEvent.click(button);
+    expect(component.state.counter).toBe(1);  // Testing internal state
+});
+
+// ✅ Good test: Behavior testing
+test('displays incremented count when clicked', () => {
+    render(<Counter />);
+    const button = screen.getByRole('button', { name: /increment/i });
+    fireEvent.click(button);
+    expect(screen.getByText('Count: 1')).toBeInTheDocument();
+});
+```
+
+**Review questions for tests:**
+- Do tests describe behavior, not implementation?
+- Are test names clear and descriptive?
+- Do tests cover edge cases?
+- Are tests independent (no shared state)?
+- Can tests run in any order?
+
+## Giving Difficult Feedback
+
+### Pattern: Context + Issue + Solution
+
+```markdown
+Traditional: Praise + Criticism + Praise (feels fake)
+
+Better: Context + Specific Issue + Helpful Solution
+
+Example:
+"I noticed the payment processing logic is inline in the
+controller. This makes it harder to test and reuse.
+
+[Specific Issue]
+The calculateTotal() function mixes tax calculation,
+discount logic, and database queries, making it difficult
+to unit test and reason about.
+
+[Helpful Solution]
+Could we extract this into a PaymentService class? That
+would make it testable and reusable. I can pair with you
+on this if helpful."
+```
+
+## Handling Disagreements
+
+When author disagrees with your feedback:
+
+1. **Seek to Understand**
+   "Help me understand your approach. What led you to
+    choose this pattern?"
+
+2. **Acknowledge Valid Points**
+   "That's a good point about X. I hadn't considered that."
+
+3. **Provide Data**
+   "I'm concerned about performance. Can we add a benchmark
+    to validate the approach?"
+
+4. **Escalate if Needed**
+   "Let's get [architect/senior dev] to weigh in on this."
+
+5. **Know When to Let Go**
+   If it's working and not a critical issue, approve it.
+   Perfection is the enemy of progress.
+
+## Best Practices
+
+1. **Review Promptly**: Within 24 hours, ideally same day
+2. **Limit PR Size**: 200-400 lines max for effective review
+3. **Review in Time Blocks**: 60 minutes max, take breaks
+4. **Use Review Tools**: GitHub, GitLab, or dedicated tools
+5. **Automate What You Can**: Linters, formatters, security scans
+6. **Build Rapport**: Emoji, praise, and empathy matter
+7. **Be Available**: Offer to pair on complex issues
+8. **Learn from Others**: Review others' review comments
+
+## Common Pitfalls
+
+- **Perfectionism**: Blocking PRs for minor style preferences
+- **Scope Creep**: "While you're at it, can you also..."
+- **Inconsistency**: Different standards for different people
+- **Delayed Reviews**: Letting PRs sit for days
+- **Ghosting**: Requesting changes then disappearing
+- **Rubber Stamping**: Approving without actually reviewing
+- **Bike Shedding**: Debating trivial details extensively
+
+## PR Review Comment Template
+
+```markdown
+## Summary
+[Brief overview of what was reviewed]
+
+## Strengths
+- [What was done well]
+- [Good patterns or approaches]
+
+## Required Changes
+🔴 [Blocking issue 1]
+🔴 [Blocking issue 2]
+
+## Suggestions
+💡 [Improvement 1]
+💡 [Improvement 2]
+
+## Questions
+❓ [Clarification needed on X]
+❓ [Alternative approach consideration]
+
+## Verdict
+✅ Approve after addressing required changes
+```

package/templates/.claude/skills/code-review/references/requesting-code-review.md

@@ -0,0 +1,105 @@
+---
+name: requesting-code-review
+description: Use when completing tasks, implementing major features, or before merging to verify work meets requirements - dispatches code-reviewer subagent to review implementation against plan or requirements before proceeding
+---
+
+# Requesting Code Review
+
+Dispatch code-reviewer subagent to catch issues before they cascade.
+
+**Core principle:** Review early, review often.
+
+## When to Request Review
+
+**Mandatory:**
+- After each task in subagent-driven development
+- After completing major feature
+- Before merge to main
+
+**Optional but valuable:**
+- When stuck (fresh perspective)
+- Before refactoring (baseline check)
+- After fixing complex bug
+
+## How to Request
+
+**1. Get git SHAs:**
+```bash
+BASE_SHA=$(git rev-parse HEAD~1)  # or origin/main
+HEAD_SHA=$(git rev-parse HEAD)
+```
+
+**2. Dispatch code-reviewer subagent:**
+
+Use Task tool with `code-reviewer` type, fill template at `code-reviewer.md`
+
+**Placeholders:**
+- `{WHAT_WAS_IMPLEMENTED}` - What you just built
+- `{PLAN_OR_REQUIREMENTS}` - What it should do
+- `{BASE_SHA}` - Starting commit
+- `{HEAD_SHA}` - Ending commit
+- `{DESCRIPTION}` - Brief summary
+
+**3. Act on feedback:**
+- Fix Critical issues immediately
+- Fix Important issues before proceeding
+- Note Minor issues for later
+- Push back if reviewer is wrong (with reasoning)
+
+## Example
+
+```
+[Just completed Task 2: Add verification function]
+
+You: Let me request code review before proceeding.
+
+BASE_SHA=$(git log --oneline | grep "Task 1" | head -1 | awk '{print $1}')
+HEAD_SHA=$(git rev-parse HEAD)
+
+[Dispatch code-reviewer subagent]
+  WHAT_WAS_IMPLEMENTED: Verification and repair functions for conversation index
+  PLAN_OR_REQUIREMENTS: Task 2 from docs/plans/deployment-plan.md
+  BASE_SHA: a7981ec
+  HEAD_SHA: 3df7661
+  DESCRIPTION: Added verifyIndex() and repairIndex() with 4 issue types
+
+[Subagent returns]:
+  Strengths: Clean architecture, real tests
+  Issues:
+    Important: Missing progress indicators
+    Minor: Magic number (100) for reporting interval
+  Assessment: Ready to proceed
+
+You: [Fix progress indicators]
+[Continue to Task 3]
+```
+
+## Integration with Workflows
+
+**Subagent-Driven Development:**
+- Review after EACH task
+- Catch issues before they compound
+- Fix before moving to next task
+
+**Executing Plans:**
+- Review after each batch (3 tasks)
+- Get feedback, apply, continue
+
+**Ad-Hoc Development:**
+- Review before merge
+- Review when stuck
+
+## Red Flags
+
+**Never:**
+- Skip review because "it's simple"
+- Ignore Critical issues
+- Proceed with unfixed Important issues
+- Argue with valid technical feedback
+
+**If reviewer wrong:**
+- Push back with technical reasoning
+- Show code/tests that prove it works
+- Request clarification
+
+See template at: requesting-code-review/code-reviewer.md