devflow-kit 0.8.1 → 1.0.0

package/shared/skills/review-methodology/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: review-methodology
+description: Standard review methodology providing the 6-step process and 3-category issue classification (must-fix, should-fix, nit) used by all DevFlow review agents. Ensures consistent, fair, and actionable code reviews across all focus areas. Loaded by the unified Reviewer agent.
+user-invocable: false
+allowed-tools: Read, Grep, Glob, Bash
+---
+
+# Review Methodology
+
+The canonical review process for all DevFlow review agents. Ensures consistent, fair, and actionable code reviews.
+
+## Iron Law
+
+> **NEVER BLOCK FOR PRE-EXISTING ISSUES**
+>
+> Only issues in YOUR CHANGES can block a PR. Pre-existing issues are informational only.
+> If you didn't add it, you don't own it. Fair reviews focus on the diff, not the codebase.
+
+## Core Philosophy
+
+1. **Focus on changed lines first** - Developer introduced these
+2. **Context matters** - Issues near changes should be fixed together
+3. **Be fair** - Don't block PRs for legacy code
+4. **Be specific** - Exact file:line with examples
+5. **Be actionable** - Clear fixes, not vague complaints
+
+---
+
+## 6-Step Review Process
+
+### Step 1: Identify Changed Lines
+
+Get the diff to understand what changed. Identify base branch and extract changed files/lines.
+
+### Step 2: Categorize Issues
+
+| Category | Scope | Priority | Action |
+|----------|-------|----------|--------|
+| **1. Issues in Your Changes** | Lines ADDED/MODIFIED in this branch | BLOCKING | Must fix before merge |
+| **2. Issues in Code You Touched** | Same file/function, but not your line | HIGH | Should fix while here |
+| **3. Pre-existing Issues** | Lines you didn't touch at all | INFORMATIONAL | Fix in separate PR |
+
+### Step 3: Analyze with Domain Expertise
+
+Apply your specialized lens (security, performance, tests, etc.) to each category:
+
+- **Category 1** - Maximum scrutiny, any issue blocks PR
+- **Category 2** - Should fix together with your changes
+- **Category 3** - Note but don't block, suggest separate issues
+
+### Step 4: Prioritize by Severity
+
+| Severity | Description | Examples |
+|----------|-------------|----------|
+| **CRITICAL** | Immediate risk, must fix | Security vulnerabilities, data loss risks, breaking API changes |
+| **HIGH** | Significant risk, should fix | Performance degradation, missing error handling |
+| **MEDIUM** | Moderate risk, consider fixing | Style inconsistencies, missing documentation |
+| **LOW** | Minor improvements | Naming suggestions, optional optimizations |
+
+### Step 5: Create Actionable Comments
+
+For each issue, provide:
+1. **Location** - Exact file:line reference
+2. **Problem** - Clear description
+3. **Impact** - Why this matters
+4. **Fix** - Specific code solution
+5. **Category** - Which of the 3 categories
+
+### Step 6: Generate Report
+
+Create report with all three issue sections, summary counts, and merge recommendation.
+
+---
+
+## Key Principles Summary
+
+| Principle | Description |
+|-----------|-------------|
+| **Diff-Aware** | Focus on actual changes, not pre-existing issues |
+| **Fair** | Don't block PRs for legacy problems |
+| **Specific** | Exact file:line, not vague complaints |
+| **Actionable** | Show the fix, not just the problem |
+| **Categorized** | Clear distinction between blocking and informational |
+| **Prioritized** | Critical > High > Medium > Low |
+| **Documented** | Reports saved for future reference |
+
+---
+
+## Extended References
+
+For detailed implementation:
+
+| Reference | Content |
+|-----------|---------|
+| `references/report-template.md` | Full report template with all sections |
+| `references/pr-comments.md` | PR comment API integration details |
+| `references/commands.md` | Bash commands for getting diffs and saving reports |
+
+---
+
+## Integration
+
+This methodology is used by the **Reviewer** agent with different focus areas:
+
+| Focus | Pattern Skill |
+|-------|---------------|
+| `security` | security-patterns |
+| `performance` | performance-patterns |
+| `architecture` | architecture-patterns |
+| `tests` | test-patterns |
+| `consistency` | consistency-patterns |
+| `complexity` | complexity-patterns |
+| `regression` | regression-patterns |
+| `dependencies` | dependencies-patterns |
+| `documentation` | documentation-patterns |
+| `typescript` | typescript |
+| `database` | database-patterns |
+
+The Reviewer agent loads all pattern skills and applies the relevant one based on the focus area specified in its invocation prompt.

package/shared/skills/review-methodology/references/patterns.md

@@ -0,0 +1,186 @@
+# Review Methodology Patterns
+
+Correct patterns for effective code reviews.
+
+---
+
+## 6-Step Review Process
+
+1. **Understand Context** - Read PR description, linked issues
+2. **Get Diff** - Analyze changed files
+3. **Review by Category** - Security, architecture, performance, etc.
+4. **Classify Issues** - CRITICAL, HIGH, MEDIUM, LOW
+5. **Write Report** - Structured format with file:line references
+6. **Post Comments** - Use GitHub API for PR comments
+
+---
+
+## Issue Classification
+
+| Category | Criteria |
+|----------|----------|
+| CRITICAL | Security vulnerabilities, data loss, crashes |
+| HIGH | Bugs, significant performance issues |
+| MEDIUM | Code quality, maintainability |
+| LOW | Style, documentation, minor improvements |
+
+---
+
+## Diff Analysis Commands
+
+### Getting the Diff
+
+```bash
+# Get the base branch
+BASE_BRANCH=""
+for branch in main master develop; do
+  if git show-ref --verify --quiet refs/heads/$branch; then
+    BASE_BRANCH=$branch
+    break
+  fi
+done
+
+# Get changed files
+git diff --name-only $BASE_BRANCH...HEAD > /tmp/changed_files.txt
+
+# Get detailed diff with line numbers
+git diff $BASE_BRANCH...HEAD > /tmp/full_diff.txt
+
+# Extract exact line numbers that changed
+git diff $BASE_BRANCH...HEAD --unified=0 | grep -E '^@@' > /tmp/changed_lines.txt
+
+# Get diff statistics
+git diff $BASE_BRANCH...HEAD --stat > /tmp/diff_stats.txt
+
+echo "Changed files: $(wc -l < /tmp/changed_files.txt)"
+echo "Base branch: $BASE_BRANCH"
+echo "Current branch: $(git branch --show-current)"
+```
+
+### Useful Git Commands
+
+| Command | Purpose |
+|---------|---------|
+| `git diff --name-only BASE...HEAD` | List changed files |
+| `git diff BASE...HEAD --stat` | Summary of changes |
+| `git diff BASE...HEAD --unified=0` | Only changed lines (no context) |
+| `git diff BASE...HEAD -- path/` | Diff for specific directory |
+| `git log BASE..HEAD --oneline` | Commits in this branch |
+| `git show --stat HEAD` | Last commit details |
+
+### Branch Detection
+
+```bash
+# Detect base branch (in priority order)
+for branch in main master develop; do
+  if git show-ref --verify --quiet refs/heads/$branch; then
+    BASE_BRANCH=$branch
+    break
+  fi
+done
+
+# Get current branch
+CURRENT_BRANCH=$(git branch --show-current)
+
+# Get branch slug for filenames
+BRANCH_SLUG=$(echo "$CURRENT_BRANCH" | sed 's/\//-/g')
+```
+
+---
+
+## Report File Conventions
+
+```bash
+# Get timestamp and branch slug
+TIMESTAMP=$(date +%Y-%m-%d_%H%M)
+BRANCH_SLUG=$(git branch --show-current | sed 's/\//-/g')
+
+# When invoked by /code-review command
+REPORT_FILE=".docs/reviews/${BRANCH_SLUG}/{domain}-report.${TIMESTAMP}.md"
+
+# When invoked standalone
+REPORT_FILE="${REPORT_FILE:-.docs/reviews/standalone/{domain}-report.${TIMESTAMP}.md}"
+
+# Ensure directory exists
+mkdir -p "$(dirname "$REPORT_FILE")"
+
+# Save report
+cat > "$REPORT_FILE" <<'REPORT'
+{Generated report content}
+REPORT
+
+echo "Review saved: $REPORT_FILE"
+```
+
+---
+
+## PR Comment Integration
+
+### Comment Creation Function
+
+```bash
+REPO=$(gh repo view --json nameWithOwner -q '.nameWithOwner')
+COMMIT_SHA=$(git rev-parse HEAD)
+COMMENTS_CREATED=0
+COMMENTS_SKIPPED=0
+
+create_pr_comment() {
+    local FILE="$1" LINE="$2" BODY="$3"
+
+    # Only comment on lines in the PR diff
+    if gh pr diff "$PR_NUMBER" --name-only 2>/dev/null | grep -q "^${FILE}$"; then
+        gh api "repos/${REPO}/pulls/${PR_NUMBER}/comments" \
+            -f body="$BODY" \
+            -f commit_id="$COMMIT_SHA" \
+            -f path="$FILE" \
+            -f line="$LINE" \
+            -f side="RIGHT" 2>/dev/null \
+            && COMMENTS_CREATED=$((COMMENTS_CREATED + 1)) \
+            || COMMENTS_SKIPPED=$((COMMENTS_SKIPPED + 1))
+    else
+        COMMENTS_SKIPPED=$((COMMENTS_SKIPPED + 1))
+    fi
+
+    # Rate limiting
+    sleep 1
+}
+
+# Only create comments for BLOCKING issues (Category 1)
+# Category 2 and 3 go in the summary report only
+```
+
+### Comment Rules
+
+1. **Only comment on blocking issues** - Category 1 (Issues in Your Changes)
+2. **Verify file is in PR diff** - Skip files not part of the PR
+3. **Rate limit API calls** - 1 second delay between comments
+4. **Track statistics** - Count created vs skipped comments
+
+### API Parameters
+
+| Parameter | Value | Description |
+|-----------|-------|-------------|
+| `body` | Comment text | Markdown-formatted comment |
+| `commit_id` | HEAD SHA | The commit to attach comment to |
+| `path` | File path | Relative path to file |
+| `line` | Line number | Line number in the diff |
+| `side` | "RIGHT" | Comment on new file version |
+
+### Comment Summary Section
+
+Add to report footer:
+
+```markdown
+---
+
+## PR Comment Summary
+
+- **Comments Created**: ${COMMENTS_CREATED}
+- **Comments Skipped**: ${COMMENTS_SKIPPED} (lines not in PR diff)
+```
+
+---
+
+## Quick Reference
+
+See [report-template.md](report-template.md) for full report format.

package/shared/skills/review-methodology/references/report-template.md

@@ -0,0 +1,142 @@
+# Review Report Template
+
+Full template for generating review reports.
+
+## Report Structure
+
+```markdown
+# {Domain} Review Report
+
+**Branch**: ${CURRENT_BRANCH}
+**Base**: ${BASE_BRANCH}
+**Date**: $(date +%Y-%m-%d %H:%M:%S)
+**Files Analyzed**: ${FILE_COUNT}
+**Lines Changed**: ${LINES_CHANGED}
+
+---
+
+## Issues in Your Changes (BLOCKING)
+
+These issues were introduced in lines you added or modified:
+
+### CRITICAL
+
+**[Issue Title]** - `file.ts:123` (line ADDED in this branch)
+- **Issue**: {description}
+- **Impact**: {why it matters}
+- **Code**:
+  ```typescript
+  {problematic code}
+  ```
+- **Fix**:
+  ```typescript
+  {corrected code}
+  ```
+
+### HIGH
+
+{More findings in lines you changed}
+
+---
+
+## Issues in Code You Touched (Should Fix)
+
+These issues exist in code you modified or functions you updated:
+
+### HIGH
+
+**[Issue Title]** - `file.ts:89` (in function you modified)
+- **Issue**: {description}
+- **Context**: You modified this function but didn't fix this
+- **Recommendation**: Fix while you're here
+
+{More findings in touched code}
+
+---
+
+## Pre-existing Issues (Not Blocking)
+
+These issues exist in files you reviewed but are unrelated to your changes:
+
+### MEDIUM
+
+**[Issue Title]** - `file.ts:456` (pre-existing, line not changed)
+- **Issue**: {description}
+- **Recommendation**: Fix in separate PR
+- **Reason not blocking**: Existed before your changes
+
+{More pre-existing findings}
+
+---
+
+## Summary
+
+**Your Changes:**
+- CRITICAL: X (MUST FIX)
+- HIGH: Y (MUST FIX)
+- MEDIUM: Z
+
+**Code You Touched:**
+- HIGH: X (SHOULD FIX)
+- MEDIUM: Y (SHOULD FIX)
+
+**Pre-existing:**
+- MEDIUM: X (OPTIONAL)
+- LOW: Y (OPTIONAL)
+
+**{Domain} Score**: {X}/10
+
+**Merge Recommendation**:
+- BLOCK MERGE (if critical/high issues in your changes)
+- REVIEW REQUIRED (if medium issues in your changes)
+- APPROVED WITH CONDITIONS (if only touched/pre-existing issues)
+- APPROVED (if no issues in your changes)
+
+---
+
+## Remediation Priority
+
+**Fix before merge:**
+1. {Critical issue in your changes}
+2. {High issue in your changes}
+
+**Fix while you're here:**
+1. {Issue in code you touched}
+
+**Future work:**
+- Create issues for pre-existing problems
+- Track technical debt separately
+```
+
+## PR Line Comment Format
+
+For individual line comments on PRs:
+
+```markdown
+**{Icon} {Domain}: {Issue Title}**
+
+{Brief description of the issue}
+
+**Current:**
+```{language}
+{problematic code}
+```
+
+**Suggested Fix:**
+```{language}
+{fixed code}
+```
+
+**Why:** {Explanation of impact}
+
+---
+*Severity: {CRITICAL/HIGH/MEDIUM} | Category: {Your Changes/Code You Touched/Pre-existing}*
+<sub>Claude Code `/code-review`</sub>
+```
+
+## File Naming
+
+Reports use this naming convention:
+- Directory: `.docs/reviews/{branch-slug}/`
+- Filename: `{domain}-report.{YYYY-MM-DD_HHMM}.md`
+- Summary: `review-summary.{YYYY-MM-DD_HHMM}.md`

package/shared/skills/review-methodology/references/violations.md

@@ -0,0 +1,125 @@
+# Review Methodology Violations
+
+Common anti-patterns that undermine effective code reviews.
+
+---
+
+## Review Process Violations
+
+| Violation | Problem | Fix |
+|-----------|---------|-----|
+| Blocking for pre-existing issues | Unfair to author | Only flag issues in changed code |
+| Missing severity classification | Unclear priority | Use CRITICAL/HIGH/MEDIUM/LOW |
+| No file:line references | Hard to locate | Always include specific locations |
+| Vague feedback | Not actionable | Provide concrete fixes |
+| Mixing concerns | Confusing review | Separate by category |
+| Opinion as requirement | Overreach | Distinguish style from correctness |
+
+---
+
+## Diff Analysis Violations
+
+### Incorrect Base Branch Detection
+
+```bash
+# VIOLATION: Hardcoding base branch
+BASE_BRANCH="main"  # Fails if repo uses master or develop
+
+# VIOLATION: Not verifying branch exists
+git diff main...HEAD  # Errors if main doesn't exist
+```
+
+### Missing Change Context
+
+```bash
+# VIOLATION: Getting all files instead of changed files
+git ls-files  # Wrong - includes unchanged files
+
+# VIOLATION: Missing line-level precision
+git diff --name-only  # Only file names, no line numbers
+```
+
+---
+
+## PR Comment Violations
+
+### Commenting on Wrong Lines
+
+```bash
+# VIOLATION: Commenting without checking if file is in diff
+gh api "repos/${REPO}/pulls/${PR_NUMBER}/comments" \
+    -f path="$FILE" \
+    -f line="$LINE"  # May fail if file not in PR
+
+# VIOLATION: No rate limiting
+for issue in "${ISSUES[@]}"; do
+    create_pr_comment "$issue"  # Will hit API rate limits
+done
+```
+
+### Wrong Comment Scope
+
+```bash
+# VIOLATION: Commenting on pre-existing issues
+# Category 3 issues should NOT get PR comments
+create_pr_comment "file.ts" "456" "Pre-existing bug"  # Wrong!
+
+# VIOLATION: Missing severity indicator
+create_pr_comment "file.ts" "123" "This is a problem"  # No severity
+```
+
+---
+
+## Report Violations
+
+### Missing Structure
+
+```markdown
+# VIOLATION: Flat list without categories
+
+- Bug in file.ts:123
+- Security issue in auth.ts:45
+- Style problem in utils.ts:89
+```
+
+### Missing Context
+
+```markdown
+# VIOLATION: Issue without remediation
+
+**Issue**: SQL injection in query.ts:34
+<!-- No fix provided, no severity, no impact -->
+```
+
+### Incorrect File Naming
+
+```bash
+# VIOLATION: Non-standard naming
+REPORT_FILE="review.md"  # No timestamp, no branch
+
+# VIOLATION: Wrong directory
+REPORT_FILE="./reviews/report.md"  # Should be .docs/reviews/
+```
+
+---
+
+## Detection Patterns
+
+Use these to find violations in review code:
+
+```bash
+# Find hardcoded base branches
+grep -r 'BASE_BRANCH="main"' --include="*.sh"
+
+# Find missing rate limiting
+grep -r 'gh api.*comments' --include="*.sh" | grep -v 'sleep'
+
+# Find missing severity classifications
+grep -r 'create_pr_comment' --include="*.sh" | grep -v 'CRITICAL\|HIGH\|MEDIUM\|LOW'
+```
+
+---
+
+## Quick Reference
+
+See [report-template.md](report-template.md) for proper review format.