SKILL.md6.0 KBView on GitHub ---
name: commit-pr
description: Stage and commit changes, run full pre-PR validation, push and open a PR, then monitor CI and address failures. Use when the user wants a /commit -> /pr workflow that gates on checks before and after PR creation.
---
# Commit -> PR Workflow
Use this skill when the user wants to commit work and immediately open a PR, with verification before PR creation and CI monitoring after.
## Inputs
- Optional scope for files to stage (paths, directories, or plain-English scope)
- Optional PR base branch (default: `staging`)
## Workflow
### 1) Inspect local changes
Run:
```bash
git status
git diff --stat
git log --format="%s" -10
```
### 2) Stage and commit
- If no scope is given, stage everything with `git add -A`.
- If scope is provided, stage only matching files.
- Never stage secrets (`.env`, credentials, private keys).
- Write a concise commit message matching repo style: `type: short description`.
- Commit with a heredoc message.
If commit hooks fail, fix root causes, restage, and retry (no `--no-verify`).
### 3) Run pre-PR validation (required)
Before any push or PR creation, run:
```bash
pnpm run autofix:local
```
This is the quality gate for lint, dependency direction checks, and core test suites.
If validation fails:
1. Fix the failure.
2. Commit the fix with `fix: ...`.
3. Run `pnpm run autofix:local` again.
4. Repeat until green (max 3 rounds, then escalate to user).
### 4) Always sync with fresh base branch (required)
Before any push or PR creation, always fetch the latest base branch from origin and merge it:
```bash
git fetch origin staging
git merge origin/staging
```
- If the user specifies a different base, replace `staging` above.
- If merge conflicts occur, resolve all conflicts immediately, complete the merge commit, and verify `git status` is clean before proceeding.
- After conflict resolution, rerun:
```bash
pnpm run autofix:local
```
Only continue once merge/conflict resolution is complete and validation is green.
### 5) Push branch
```bash
git push
```
If no upstream exists:
```bash
git push -u origin HEAD
```
### 6) Open PR
Create the PR with `gh pr create` using a concise title and body:
- Summary: what changed and why
- Test plan: what passed (`pnpm run autofix:local`) and any targeted checks
Default base branch is `staging` unless user asks otherwise.
### 7) Monitor CI and auto-fix failures (required)
After the PR is open, **stay on the task** — do not report back until CI has reached a terminal state or the timeout is hit.
#### Poll for check completion
```bash
gh pr checks <PR_NUMBER> --watch --interval 30
```
- **Timeout:** ~5 minutes (10 poll cycles at 30s). If checks are still pending after 5 minutes, note which are pending and continue monitoring in the report; do not block indefinitely.
- **Expected checks** (from `.github/workflows/ci.yml`): `autofix`, `Mail app tests (Jest)`, `Server tests (Vitest)`. Greptile may appear as a separate check.
#### On CI failure — fix automatically
For every failing check that is **not** Greptile:
1. **Investigate** — pull the failure log:
```bash
gh run list --branch <HEAD_BRANCH> --limit 5
gh run view <RUN_ID> --log-failed
```
2. **Fix** the root cause locally (reproduce with the same command CI runs if possible).
3. **Verify** with `pnpm run autofix:local`.
4. **Commit and push** with `fix: ...` or `fix(ci): ...`.
5. **Re-poll** checks on the new commit (another ~5 minute window).
Repeat until all non-Greptile checks pass (max 3 fix rounds, then escalate to user).
Do **not** skip failing checks, use `--no-verify`, or force-push unless the user explicitly asks.
#### On CI success
Proceed to step 8.
### 8) Greptile review — investigate and report (do NOT auto-fix)
Greptile comments require judgment. **Do not blindly apply every suggestion.** Instead, investigate and produce a brief report for the user.
#### Wait for Greptile
Greptile often runs after CI. If the Greptile check is still pending when CI passes, poll up to ~3 additional minutes:
```bash
gh pr checks <PR_NUMBER> --watch --interval 30
```
If Greptile has not finished after that, note it as pending in the report and fetch whatever is available.
#### Fetch Greptile feedback
```bash
gh pr view <PR_NUMBER> --json reviews,statusCheckRollup
gh api repos/{owner}/{repo}/pulls/<PR_NUMBER>/comments
gh api repos/{owner}/{repo}/pulls/<PR_NUMBER>/reviews
```
Filter to comments/reviews from `greptile-apps[bot]` or `greptile-apps-staging[bot]`.
#### Investigate each comment
For every Greptile inline comment or review note:
1. Read the flagged code in context.
2. Classify:
- **Valid** — real bug, missing edge case, or genuine improvement worth fixing
- **False positive** — stylistic nit, misunderstanding of intent, or already handled
- **Informational** — FYI, no code change needed
3. If **Valid** and the fix is small and clearly correct, you may fix it in the same session — but still document it in the report. For ambiguous or large-scope suggestions, report only; do not fix without user confirmation.
#### Greptile report format
Include this section in the final report back:
```markdown
## Greptile review
**Confidence:** X/5 (from latest Greptile review body, if present)
**Unresolved inline comments:** N
| File | Comment summary | Verdict | Action |
|------|----------------|---------|--------|
| `path/to/file.ts:42` | Missing null check on `foo` | Valid | Fixed in abc1234 |
| `path/to/other.ts:10` | Extract helper function | False positive | Intentional inline logic |
| ... | ... | ... | ... |
**Summary:** 1–3 sentences on overall Greptile feedback quality and whether the PR is merge-ready from a review perspective.
```
### 9) Report back
Return:
- Commit SHA(s) and message(s) — including any CI fix commits pushed after PR creation
- Pre-PR validation result (`pnpm run autofix:local`)
- PR URL
- **CI status** — which checks passed/failed; any fix commits pushed
- **Greptile report** — per step 8 format
- Any follow-up risks or TODOs that need user input