payload-billing/.github/CLAUDE_PR_ASSISTANT.md

# Claude PR Assistant

This workflow allows Claude to assist with Pull Requests by implementing improvements, fixes, and changes directly on the PR branch when mentioned in comments.

## How to Use

### 1. Comment on Any PR

Use one of these trigger commands in a comment on any open pull request:

- `@claude implement` - Implement new features or functionality
- `@claude fix` - Fix bugs or issues in the PR
- `@claude improve` - Improve existing code quality
- `@claude update` - Update code to match requirements
- `@claude refactor` - Refactor code for better structure
- `@claude help` - General assistance with the PR

### 2. Example Usage

```
@claude fix

Please fix the TypeScript errors in the payments collection and ensure proper typing for the provider data field.
```

```
@claude improve

Can you optimize the invoice generation logic and add better error handling?
```

```
@claude implement

Add validation for email addresses in the customer billing information fields. Make sure it follows the existing validation patterns.
```

## What Happens

1. **Permission Check**: Verifies you are `bvdaakster` (only authorized user)
2. **PR Analysis**: Claude analyzes the current PR context and changes
3. **Implementation**: Makes the requested changes directly on the PR branch
4. **Quality Checks**: Runs build, typecheck, and lint
5. **Commit & Push**: Commits changes with descriptive messages
6. **Notification**: Updates the PR with completion status

## Features

### ✅ Direct PR Modification
- Works directly on the existing PR branch
- No new branches or PRs created
- Changes appear immediately in the PR

### ✅ Smart Context Awareness
- Understands the current PR changes
- Analyzes existing code patterns
- Maintains consistency with the codebase

### ✅ Comprehensive Request Handling
- Code improvements and refactoring
- Bug fixes within the PR
- Adding missing features
- Documentation updates
- Type error fixes
- Performance optimizations
- Test additions

### ✅ Quality Assurance
- Follows TypeScript conventions
- Uses ESM module structure
- Runs automated quality checks
- Maintains coding standards

## Command Reference

| Command | Purpose | Example |
|---------|---------|---------|
| `@claude implement` | Add new functionality | "implement user authentication" |
| `@claude fix` | Fix bugs or errors | "fix the validation logic" |
| `@claude improve` | Enhance existing code | "improve performance of query" |
| `@claude update` | Update to requirements | "update to use new API format" |
| `@claude refactor` | Restructure code | "refactor into smaller functions" |
| `@claude help` | General assistance | "help with error handling" |

## Examples

### Bug Fix Request
```
@claude fix

There's a TypeScript error in `src/providers/stripe.ts` on line 45. The `amount` property is missing from the payment object. Please fix this and ensure proper typing.
```

### Feature Implementation
```
@claude implement

Add support for recurring payments in the Stripe provider. Follow the same pattern as the Mollie provider and include proper webhook handling.
```

### Code Improvement
```
@claude improve

The `validatePayment` function in utils.ts is getting complex. Please refactor it to be more readable and add proper error messages for each validation case.
```

### Documentation Update
```
@claude update

Update the JSDoc comments in the billing plugin configuration to include examples of how to use the new customer info extractor feature.
```

## Response Types

### Success Response
```
✅ PR Assistance Complete!

🔧 Changes Made:
- ✅ Analyzed PR context and requirements
- ✅ Implemented requested improvements/fixes
- ✅ Followed project coding standards
- ✅ Updated the current PR branch

Changes are ready for review! 🚀
```

### No Changes Response
```
ℹ️ PR Assistance Complete - No Changes

Analysis Result: The requested feature is already implemented

💡 Suggestions:
- Provide more detailed requirements
- Point to specific files or functions
```

### Error Response
```
❌ PR Assistance Failed

🔄 Try Again:
- Providing more specific instructions
- Breaking down complex requests
```

## Best Practices

### Clear Instructions
- Be specific about what you want changed
- Reference specific files or functions when possible
- Provide context about the desired outcome

### Examples of Good Requests
```
@claude fix the TypeScript error in src/collections/payments.ts line 42 where the status field is missing from the Payment interface

@claude implement email validation in the customer billing form using the same pattern as the phone validation

@claude refactor the webhook handler in providers/mollie.ts to extract the payment processing logic into separate functions
```

### Examples of Unclear Requests
```
@claude fix everything
@claude make it better
@claude help with this
```

## Limitations

- **User Restriction**: Only `bvdaakster` can use this feature
- **PR Only**: Works on pull request comments, not issue comments
- **Open PRs**: Only works on open pull requests
- **Branch Access**: Requires write access to the PR branch

## Technical Details

### Workflow Triggers
- Event: `issue_comment` on pull requests
- Conditions: Comment contains Claude trigger words
- Permissions: User must be `bvdaakster`

### Quality Checks
Claude automatically runs:
- `pnpm build` - Verify code compiles
- `pnpm typecheck` - Check TypeScript types
- `pnpm lint` - Ensure code style compliance
- `npm run test` - Run test suite (if available)

### Commit Messages
Automatic commits include:
- Description of the request
- PR number and requester
- Claude attribution
- Proper co-authoring

### Branch Strategy
- Works directly on the PR's head branch
- No additional branches created
- Changes pushed to existing PR
- Maintains PR history

## Troubleshooting

### Common Issues

1. **Permission Denied**
   - Only `bvdaakster` can use Claude PR assistance
   - Verify you're commenting as the correct user

2. **No Changes Made**
   - Request might be unclear or already implemented
   - Try providing more specific instructions
   - Reference specific files or lines

3. **Workflow Failed**
   - Check the Actions tab for detailed logs
   - Verify the PR branch is accessible
   - Ensure request is actionable

### Getting Help

If Claude assistance isn't working:
1. Check the workflow logs in Actions tab
2. Verify your request is specific and actionable
3. Try breaking complex requests into smaller parts
4. Use different command triggers (@claude fix vs @claude implement)

---

**Note**: This feature uses the official Anthropic Claude Code action for reliable, production-ready assistance. All changes should be reviewed before merging.