Hotfix - Mobile PR Creation

Create hotfix PRs directly from Telegram when you need to push a quick fix but are away from your development machine.

Quick Start

/hotfix Fix the rate limiter that's blocking all requests

This will:

Analyze your description using AI
Suggest code changes based on context
Create a PR with the fix
Notify you with the PR link

Security

Admin Only: This command is restricted to the admin Telegram user ID configured in ADMIN_TELEGRAM_ID.

Rate Limited: 5 hotfixes per hour maximum to prevent abuse.

GitHub App Auth: Uses GitHub App installation tokens (not PAT) for secure, scoped repository access.

Commands

Create a Hotfix

/hotfix [description of what to fix]

Examples:

/hotfix Fix CORS headers missing on the health endpoint

/hotfix Add null check in the user profile API that's causing 500 errors

/hotfix Update the OpenRouter model from claude-3-opus to claude-opus-4-5

With Specific Files (Advanced)

You can specify exact file changes in your description:

/hotfix Update mini-app/api/lib/cors.ts to add OPTIONS handling

How It Works

1. Request Validation

Verifies Telegram user ID matches admin
Checks rate limit (5/hour)
Validates GitHub App is configured

2. AI Analysis

When you provide a description, Claude analyzes:

The codebase structure
Relevant files based on your description
Suggests specific code changes

3. PR Creation

The system will:

Create a new branch: hotfix/{timestamp}
Commit suggested changes
Open a PR against the default branch
Send you the PR link via Telegram

4. Notification

You'll receive a Telegram message with:

PR title
Link to review the PR
Or error details if something failed

API Endpoint

The hotfix skill calls:

POST /api/hotfix/create

Request Body:

{
  "telegram_user_id": "302137836",
  "description": "Fix the rate limiter issue",
  "branch_name": "hotfix/rate-limiter-fix" // optional
}

Response:

{
  "success": true,
  "pr_url": "https://github.com/owner/repo/pull/123",
  "branch_name": "hotfix/1705612800000"
}

Implementation

When the /hotfix command is triggered:

1. Extract the description

Parse everything after /hotfix as the fix description:

User: /hotfix Fix the broken auth flow
Description: "Fix the broken auth flow"

2. Call the Hotfix API

curl -X POST "https://clawdbot-railway.vercel.app/api/hotfix/create" \
  -H "Content-Type: application/json" \
  -d '{
    "telegram_user_id": "302137836",
    "description": "Fix the broken auth flow"
  }'

3. Handle the Response

Success:

Hotfix PR created!

Title: Fix the broken auth flow
PR: https://github.com/Chipagosfinest/clawdbot-railway/pull/42

Review and merge when ready.

Error (Unauthorized):

Sorry, hotfix creation is restricted to admin users only.

Error (Rate Limited):

Rate limit exceeded. You can create up to 5 hotfixes per hour.
Try again in [X] minutes.

Error (GitHub App not configured):

GitHub App is not configured. Contact the admin to set up:
- GITHUB_APP_ID
- GITHUB_APP_INSTALLATION_ID
- GITHUB_APP_PRIVATE_KEY_BASE64

Configuration

Required Environment Variables

Variable	Description
`ADMIN_TELEGRAM_ID`	Telegram user ID authorized for hotfixes
`GITHUB_APP_ID`	GitHub App ID
`GITHUB_APP_INSTALLATION_ID`	Installation ID for the repo
`GITHUB_APP_PRIVATE_KEY_BASE64`	Base64-encoded private key
`GITHUB_REPO`	Target repo (default: Chipagosfinest/clawdbot-railway)
`OPENROUTER_API_KEY`	For AI-powered fix analysis
`TELEGRAM_BOT_TOKEN`	For sending notifications

GitHub App Permissions

The GitHub App needs:

Repository permissions:
- Contents: Read & Write (for commits)
- Pull requests: Read & Write (for PR creation)
- Metadata: Read (required)

Best Practices

Good Hotfix Descriptions

Be specific about:

The file or component affected
The error or issue you're seeing
What behavior you expect

Good:

/hotfix The /api/health endpoint returns 500 because the Supabase client isn't initialized - add null check

Less Good:

/hotfix fix the bug

When to Use Hotfix

Use /hotfix for:

Critical bugs affecting production
Quick config changes
Typo fixes
Adding missing null checks

Don't use for:

Large feature work
Refactoring
Changes requiring testing

Review Before Merge

Always review the AI-generated PR before merging. The AI makes suggestions based on context, but you should verify:

Code correctness
No unintended side effects
Proper error handling

Error Handling

Error	Cause	Solution
403 Unauthorized	Wrong Telegram ID	Only admin can use hotfix
429 Rate Limited	Too many requests	Wait and try again
500 GitHub App Error	App not configured	Check env vars
500 AI Analysis Failed	OpenRouter issue	PR created without AI suggestions

Auto-Fix System (/api/lib/auto-fix.ts): Automatic error detection and PR creation
Self-Report (/api/lib/self-report.ts): Issue creation for errors
GitHub App Auth (/api/lib/github-app.ts): Token generation

Workflow Integration

The hotfix skill integrates with the broader self-healing system:

[Error Detected] -> [Auto-Fix analyzes] -> [PR created] -> [Admin reviews]
                                                              |
[Admin on mobile] -> [/hotfix command] -> [PR created] -------+

Both paths lead to PRs that require human review before merging.

hotfix