scitex-ai/claude-code-telegrammer/pull-request

Pull Request Skill

When to Use

• Contributing to any repository via PR (external or internal)

Principles

1. Minimal change — Touch only what's necessary for the feature/fix
2. Follow their conventions — Their style, not ours
3. Atomic PR — One PR = one feature/fix. Never mix concerns
4. Read first, code second — CONTRIBUTING.md, README (how to contribute section), existing PRs

Workflow

1. Read Their Rules

cat CONTRIBUTING.md .github/CONTRIBUTING.md README.md 2>/dev/null | head -200
git -C /full/path log --oneline -20    # commit message style
git -C /full/path branch -r | head -20 # branch naming
ls .github/PULL_REQUEST_TEMPLATE* 2>/dev/null

2. Bypass Our Claude Code Hooks for External Projects

Our Claude Code hooks (ruff auto-format, line-limit, pytest-fullpath, git-C enforcement) WILL corrupt external codebases by reformatting their files to our style. This is the #1 source of dirty PRs.

Offending hooks (defined in `.claude/hooks/settings.json`):

• PostToolUse format_code.sh — ruff/black auto-format on Write|Edit
• PostToolUse run_lint.sh — linter auto-fix on Write|Edit
• PreToolUse limit_line_numbers.sh — blocks files >512 lines
• PreToolUse enforce_pytest_fullpath.sh — blocks relative pytest paths
• PreToolUse enforce_git_dash_C.sh — blocks git without -C flag

Solution: Start Claude Code with `cc --disable-hooks`

This sets CLAUDE_CODE_DISABLE_HOOKS=true via _cld_start_session in ~/.bash.d/all/010_claude/010_claude_session.src, which disables ALL PreToolUse and PostToolUse hooks (ruff, lint, line-limit, etc.).

# Start session with hooks disabled
cc --disable-hooks

If already in a session WITH hooks enabled, you must exit and restart with --disable-hooks. Setting the env var inside Bash tool mid-session does NOT retroactively disable Claude Code hooks.

Fallback if hooks are active (can't restart): Use Bash tool with python3 for file edits to bypass Write|Edit matchers:

python3 -c "
from pathlib import Path
p = Path('src/their_file.py')
t = p.read_text()
t = t.replace('old_code', 'new_code')
p.write_text(t)
"

Always verify diff is minimal before pushing:

git -C /full/path diff HEAD~1 -- src/ | head -60

Recovery if hooks already reformatted:

git -C /full/path checkout main -- src/their_file.py
# Then re-apply only your changes

3. Fork and Branch

# Fork (--clone=false if repo already cloned)
GH_TOKEN="<token>" gh repo fork <owner>/<repo> --clone=false
 
# Add fork as remote with token auth for push
git -C /full/path remote add fork https://<username>:<token>@github.com/<username>/<repo>.git
 
# Create branch matching their naming convention
git -C /full/path checkout -b <their-branch-naming-style>

4. Code, Commit, Push

• Match their commit message format (check git log --oneline -20)
• Match their code style / linter / formatter (run theirs, not ours)
• Run their tests (full suite, not just new tests)
• Rebase on their latest main

# Stage only your files (never git add -A on external repos)
git -C /full/path add src/specific_file.py tests/test_specific.py
 
# Commit matching their style
git -C /full/path commit -m "Their style commit message"
 
# Push to YOUR fork, not origin
git -C /full/path push -u fork <branch>

5. Create PR

Token Requirements for External Repos

Fine-grained PATs scoped to your own repos CANNOT create PRs/issues on external repos. You need either:

• A classic PAT with public_repo scope
• A fine-grained PAT with "All repositories" access

If the token lacks permission, provide the user with a direct compare URL:

https://github.com/<owner>/<repo>/compare/main...<your-username>:<repo>:<branch>

Creating the PR

GH_TOKEN="<classic-pat>" gh pr create \
  --repo <owner>/<repo> \
  --head <your-username>:<branch> \
  --base main \
  --title "Short title" \
  --body "$(cat <<'EOF'
## Summary
What and why (1-3 lines).
 
## Test Plan
How to verify.
 
Fixes #123
EOF
)"

If gh CLI fails (token scope issue), use REST API:

curl -s -X POST \
  -H "Authorization: token <classic-pat>" \
  -H "Accept: application/vnd.github+json" \
  https://api.github.com/repos/<owner>/<repo>/pulls \
  -d '{"title":"...","head":"<user>:<branch>","base":"main","body":"..."}'

If both fail, give the user the compare URL to create manually.

Rules

• Read CONTRIBUTING.md before touching code
• One PR, one concern — never bundle unrelated changes
• Their style wins — commit format, code style, test framework, test runner
• Minimal diff — no drive-by cleanups, no extra files
• Rebase before submit — clean history on their latest main
• Use `git -C` for all git commands
• Push to fork remote — never push to origin (upstream)
• Run their full test suite — verify zero regressions before PR
• Token awareness — check token scope early, don't waste time on auth failures

PR Template

When PR template does not exist in target project, use this as an template.

## Summary
<!-- What this PR does and why. 1-3 lines. -->
 
## Changes
<!-- Key changes, briefly. -->
 
## Test Plan
<!-- How you verified this works. -->
 
## Checklist
- [ ] Follows existing code style
- [ ] Tests pass
- [ ] Documentation updated (if applicable)