diff --git a/home/.claude/CLAUDE.md b/home/.claude/CLAUDE.md index 0d0defa8..9d283a9b 100644 --- a/home/.claude/CLAUDE.md +++ b/home/.claude/CLAUDE.md @@ -51,6 +51,7 @@ Configured in `~/.claude/settings.json` for autonomous operation: ## Quality Gates - Run quality gates appropriate to the project (linter, formatter, tests) before pushing. +- Significant user-facing features should include examples demonstrating usage - this ensures the codepath doesn't go stale. ## PR Workflow @@ -72,25 +73,19 @@ Configured in `~/.claude/settings.json` for autonomous operation: ### Handling PR Feedback -After CI completes and there's reviewer feedback, run `/pr-feedback --remote` to process it: +After CI passes, run `/pr-feedback --remote` to fetch and process reviewer comments. Use `--local` for self-checks after implementing fixes (reviewers haven't seen your changes yet). 1. **Fetch comments** from the PR 2. **Categorize** feedback as Critical, Important, or Suggestion 3. **Form opinions** - assess whether each item is valid given your context on the work -4. **Present grouped output** organized by action: - - **Implement**: Items to fix immediately - - **Discuss**: Items needing user input - - **Skip**: Items to note but not implement -5. **Implement immediately**: Critical/Important items you agree with -6. **Stop and discuss**: Critical/Important items you disagree with or are uncertain about - -**Key principle**: You have context on the work's purpose that automated reviewers lack. Honest disagreement is more valuable than blind compliance. If feedback misses the point or adds unnecessary complexity, flag it for discussion. - -### After Feedback Discussion - -- Implement items where agreement was reached -- Skip items agreed to skip -- Create GitHub issues for out-of-scope work +4. **Present ALL items** via AskUserQuestion with your opinion included +5. **Act on user's choices**: + - **Implement**: Fix it immediately + - **Skip**: Note it was skipped, move on + - **Defer**: Create a GitHub issue for later +6. **Push and re-check** - run `/pr-feedback --local` to verify changes are clean + +**Key principle**: You have context on the work's purpose that automated reviewers lack. Include your opinion in each question to help inform the user's decision. ## Issue Workflow diff --git a/home/.claude/commands/pr-feedback.md b/home/.claude/commands/pr-feedback.md index 930545ee..abc53b5f 100644 --- a/home/.claude/commands/pr-feedback.md +++ b/home/.claude/commands/pr-feedback.md @@ -12,12 +12,10 @@ Process and respond to PR review feedback with critical thinking. - **Default**: Run both local analysis AND fetch remote comments in parallel - `--local`: Only run local analysis (via `/pr-review-toolkit:review-pr`) - `--remote`: Only fetch remote comments from external reviewers -- If both flags are specified, they cancel out and default behavior (both) is used +- If both `--local` and `--remote` are specified, runs both (same as default) ## Instructions -When this skill is invoked: - ### 1. Run Analysis **Default (both)**: In parallel: @@ -40,88 +38,64 @@ gh api repos/{owner}/{repo}/pulls/$PR_NUM/reviews gh api repos/{owner}/{repo}/issues/$PR_NUM/comments ``` -### 3. Categorize Feedback - -Classify each piece of feedback: - -- **Critical**: Security issues, bugs, broken functionality, missing error handling -- **Important**: Test coverage gaps, API design issues, documentation gaps, code quality -- **Suggestions**: Style preferences, minor refactors, nice-to-haves, optimizations - -### 4. Form Opinions - -For each item, assess: -- Does this feedback understand the context and purpose of the change? -- Is this a genuine improvement or unnecessary complexity? -- Does implementing this align with project conventions (check CLAUDE.md)? -- Is the effort proportional to the benefit? - -### 5. Present Opinion Table - -Output findings grouped by action, with continuous numbering across groups: - -```markdown -## PR Feedback Review - -### Implement - -#### 1. [Critical] `path:123` (Remote) -> Summary of the feedback -**Opinion**: Agree - [reason] - -#### 2. [Important] `path:456` (Local) -> Summary of the feedback -**Opinion**: Agree - [reason] - -### Discuss - -#### 3. [Important] `path:789` (Remote) -> Summary of the feedback -**Opinion**: Disagree - [reason why this needs discussion] - -### Skip - -#### 4. [Suggestion] `path:012` (Local) -> Summary of the feedback -**Opinion**: Trivial / Out of scope / Already addressed +### 3. Categorize and Form Opinions + +For each piece of feedback: + +1. **Classify severity**: Critical / Important / Suggestion +2. **Form opinion**: Agree, Disagree, or Uncertain +3. **Note reasoning**: Why you think this way given context + +### 4. Present All Items via AskUserQuestion + +Use `AskUserQuestion` to get user decisions on ALL feedback items. The tool supports 1-4 questions per call, so batch items in groups of 4 if there are more (prioritize Critical → Important → Suggestion). Act on each batch's decisions before presenting the next group. + +```json +{ + "questions": [ + { + "question": "[Critical] Fix notify.sh JSON interface - Agree, should fix", + "header": "#1", + "options": [ + {"label": "Implement", "description": "Fix it now"}, + {"label": "Skip", "description": "Not worth it"}, + {"label": "Defer", "description": "Create issue for later"} + ], + "multiSelect": false + }, + { + "question": "[Suggestion] Add error handling for missing PR - Disagree, edge case", + "header": "#2", + "options": [ + {"label": "Implement", "description": "Fix it now"}, + {"label": "Skip", "description": "Not worth it"}, + {"label": "Defer", "description": "Create issue for later"} + ], + "multiSelect": false + } + ] +} ``` -**Source indicators**: `(Local)` = from pr-review-toolkit, `(Remote)` = from external reviewers - -Numbers are continuous across groups so items can be referenced easily (e.g., "let's discuss #3"). - -### 6. Implementation Rules - -**Implement immediately** (no discussion needed): -- Critical items you agree with -- Important items you agree with -- Suggestions you agree with AND are trivial (<5 lines) - -**Stop and discuss** (wait for user input): -- Critical items you disagree with or are uncertain about -- Important items you disagree with or are uncertain about -- Any feedback that seems to misunderstand the purpose of the change +Include your opinion in the question text so user has context, but let them decide. -**Skip** (note in summary but don't implement): -- Suggestions you disagree with -- Out-of-scope feedback (create GitHub issue instead) -- Feedback already addressed +Always include a final open-ended question: "Any other comments or questions?" with options like "None, proceed" and "Yes, let me add something". -### 7. After Discussion +### 5. Act on User Decisions -Once the user provides input on disputed items: -- Implement items where you reached agreement -- Skip items the user agrees to skip -- Create issues for items deferred to future work +Based on user's choices: +- **Implement**: Fix the item immediately +- **Skip**: Note it was skipped, move on +- **Defer**: Create a GitHub issue with title summarizing the feedback, body containing the original comment and PR link, and appropriate labels -### 8. Push and Re-check +### 6. Push and Re-check After implementing feedback: 1. Run project quality gates (linter, formatter, tests as defined in CLAUDE.md) 2. Commit with message referencing the feedback addressed 3. Push changes -4. Re-run `/pr-feedback` to verify no new comments +4. Re-run `/pr-feedback --local` to verify changes are clean ## Key Principle -You have context on the work's purpose that automated reviewers lack. If feedback seems to miss the point, add unnecessary complexity, or conflict with project conventions, flag it for discussion rather than blindly implementing. Honest disagreement is more valuable than compliance. +You have context on the work's purpose that automated reviewers lack. Include your opinion in the question text, but let the user make the final call. Your reasoning helps inform their decision.