thomasgauvin/codebase-fix-and-pr

Codebase Fix and Pull Request

When to use this skill

Use this skill when you need to apply code fixes or improvements to a GitHub repository and automatically create a pull request. Specifically, use it when you need to:

• Fix bugs reported by users or found through code review
• Implement feature improvements
• Apply refactoring changes
• Fix documentation or configuration
• Apply automated code corrections
• Update dependencies or package versions

Overview

This skill guides an agent through the complete workflow of analyzing user feedback, making targeted code changes, and creating a pull request. The agent uses GitHub authentication via environment variables and the GitHub MCP tools to complete the entire flow.

Prerequisites

Before using this skill:

1. Configure Git CLI: Use the configure-git-cli skill to set up git user identity and GitHub authentication with your PAT
2. Required environment variables:
   • GITHUB_EMAIL: Your git email
   • GITHUB_NAME: Your git name
   • GITHUB_PAT: GitHub Personal Access Token with repo and workflow scopes

Workflow

Step 0: Configure Git (Prerequisite)

Before performing any git operations, ensure git is configured by invoking the configure-git-cli skill. This will:

• Set your git user email and name
• Configure GitHub authentication with your PAT
• Verify git credentials work correctly

Once configured, you can proceed with the following steps.

Step 1: Parse Requirements

Input required:

• GitHub repository URL or owner/repo format
• User feedback, issue description, or fix requirement
• Specific files or areas to modify (optional)
• PR description and title (optional - will auto-generate if not provided)

Actions:

1. Parse the user feedback to understand:
   • What needs to be fixed
   • Why it needs to be fixed
   • Which files are likely affected
   • Success criteria for the fix
2. Break down complex requests into discrete changes
3. Plan the implementation approach

Step 2: Repository Setup

Actions:

1. Git is already configured from Step 0, so authentication is ready
2. Clone the repository:

   git clone https://github.com/owner/repo.git
   cd repo
   

3. Verify repository structure and identify relevant files
4. Document the current state before making changes

Step 3: Create Feature Branch

Actions:

1. Create a new branch with a descriptive name:

   git checkout -b fix/description-of-change
   # or
   git checkout -b feature/description-of-change
   

2. Branch naming conventions:

   • Use fix/ prefix for bug fixes
   • Use feature/ prefix for new features or improvements
   • Use refactor/ prefix for refactoring work
   • Use docs/ prefix for documentation updates
   • Use kebab-case for the description

3. Verify the branch was created successfully

Step 4: Analyze and Make Changes

For each required change:

1. Locate the relevant file(s)

   • Read the file(s) that need modification
   • Understand the current code structure
   • Identify dependencies and imports

2. Make targeted changes

   • Modify only what's necessary to fix the issue
   • Maintain code style consistency
   • Keep changes focused and atomic
   • Update related tests if applicable

3. Verify changes

   • Check for syntax errors
   • Verify the change achieves the stated goal
   • Ensure no unrelated code was modified

Common change patterns:

• Bug fixes (modify logic)
• Configuration updates (modify config files)
• Documentation (update README, comments, docs)
• Dependency updates (modify package.json, requirements.txt)
• Test additions (new test files)
• Code refactoring (improve structure)

Step 5: Commit Changes

Actions:

1. Stage the changes:

   git add .
   # or for specific files:
   git add path/to/file1 path/to/file2
   

2. Create a meaningful commit message:

   • Use conventional commit format (recommended)
   • First line: summary (50 characters max)
   • Blank line
   • Body: detailed explanation (optional)
   • Reference issue numbers if applicable

Commit message examples:

fix: resolve authentication timeout in user service

When a user login attempt exceeded 30 seconds, the timeout
handler was not properly cleaning up resources. This caused
the subsequent requests to fail. 

Now using a WeakMap to track in-flight requests and properly
clean up on timeout.

Fixes #123

feat: add retry logic to API client calls

Adds exponential backoff retry strategy for transient
API failures. Configurable retry count and backoff
multiplier.

docs: update installation instructions for macOS

Step 6: Push to Remote Branch

Actions:

1. Push the branch to the remote repository:

   git push origin fix/description-of-change
   

2. Verify the push was successful
3. Note the branch name for PR creation

Step 7: Create Pull Request via GitHub MCP

Using the GitHub MCP authenticated tools:

1. Call the GitHub MCP to create a pull request with:

   • Title: Clear, descriptive title (auto-generated or provided)
   • Description: What was changed and why
   • Head: The feature branch name
   • Base: The target branch (usually main or develop)

2. PR Description template:

   ## What changed
   Brief summary of the changes
   
   ## Why
   Explanation of the motivation for these changes
   
   ## How to test
   Steps to verify the fix works correctly
   
   ## Related issues
   Fixes #123
   Closes #456
   

3. PR creation example:

   • Title: "Fix authentication timeout in user service"
   • Base branch: "main"
   • Head branch: "fix/auth-timeout"
   • Description: Includes what changed, why, testing steps

Step 8: Verify PR Creation

Actions:

1. Confirm the PR was created successfully
2. Verify:
   • All changes are visible in the PR diff
   • Commit history is clean
   • No unrelated files were modified
   • PR description is clear
3. Provide the PR URL and summary to the user

Common Patterns

Bug Fix Pattern

1. Identify the bug in the code
2. Understand the root cause
3. Fix the specific issue (usually 1-2 files)
4. Create test case if not present
5. Commit with "fix:" prefix
6. Create PR with issue reference

Feature Addition Pattern

1. Identify where to add the feature
2. Implement the feature
3. Add tests for the feature
4. Update documentation if needed
5. Commit with "feat:" prefix
6. Create PR with feature description

Documentation Update Pattern

1. Identify documentation that needs updating
2. Update markdown or comment documentation
3. Fix any broken links
4. Commit with "docs:" prefix
5. Create PR with summary of changes

Dependency Update Pattern

1. Update version in package.json or requirements.txt
2. Run dependency installation/update
3. Test that the code works with new version
4. Commit with "chore:" or "deps:" prefix
5. Create PR documenting version changes

Error Handling

If repository clone fails:

• Verify the PAT has repo access permissions
• Check that the repository URL is correct
• Ensure network connectivity

If branch creation fails:

• Check if the branch already exists
• Verify you're in the correct repository directory
• Ensure git is properly configured

If commit fails:

• Verify files exist and have correct changes
• Check for merge conflicts (if pulling latest)
• Ensure file permissions are correct

If PR creation fails:

• Verify the branch has been pushed successfully
• Check that the base branch exists
• Ensure the GitHub PAT has PR creation permissions
• Verify no branch protection rules are blocking

GitHub MCP Integration

The skill uses the GitHub MCP tools which are pre-authenticated with the GitHub PAT:

Available operations:

• create_pull_request: Create a new PR
• Git operations via command line using configured credentials
• Repository metadata access

Environment variables required:

• GITHUB_PAT: GitHub Personal Access Token with repo and pull-request scopes
• (Git is configured via the configure-git-cli skill)

Best Practices

1. Make atomic commits: Each commit should represent one logical change
2. Keep PRs focused: Fix one issue or implement one feature per PR
3. Write clear messages: Future developers will read your commits
4. Test locally first: Verify changes work before pushing
5. Reference issues: Link to related issues in commit and PR descriptions
6. Describe the "why": Explain motivation, not just what changed
7. Keep changes minimal: Don't refactor unrelated code

Example Use Cases

Bug Fix Example

User feedback: "The login button doesn't work on mobile devices"

Agent process:

1. Parse the issue: Mobile login failure
2. Clone repository
3. Create branch: fix/mobile-login-button
4. Locate login component
5. Debug and fix responsive design issue
6. Test the fix
7. Commit: "fix: correct mobile login button styling"
8. Push branch
9. Create PR: "Fix login button on mobile devices"

Feature Addition Example

User feedback: "Add dark mode support to the application"

Agent process:

1. Parse the requirement: Implement dark mode
2. Clone repository
3. Create branch: feature/dark-mode-support
4. Implement theme switching logic
5. Update components to support theme
6. Add configuration option
7. Create tests for theme switching
8. Commit: "feat: add dark mode theme support"
9. Push branch
10. Create PR: "Add dark mode support with theme switcher"

Documentation Update Example

User feedback: "The API documentation is outdated"

Agent process:

1. Parse the requirement: Update API docs
2. Clone repository
3. Create branch: docs/update-api-documentation
4. Locate and update README or docs folder
5. Fix outdated examples
6. Update endpoint descriptions
7. Commit: "docs: update API documentation examples"
8. Push branch
9. Create PR: "Update API documentation with current endpoints"

Success Criteria

The workflow is complete when:

• ✅ Repository successfully cloned
• ✅ Feature branch created with descriptive name
• ✅ All required changes made to files
• ✅ Changes are focused and atomic
• ✅ Commit message is clear and follows conventions
• ✅ Changes pushed to remote
• ✅ Pull request created successfully
• ✅ PR includes clear description and issue references
• ✅ User provided with PR link and summary