pre-push

# Pre-push Checks Skill

Get your branch push-ready: detect which areas your changes touch, auto-fix what's mechanically fixable, then run the same checks CI's merge gate runs for those areas — and triage whatever's left with the user.

This is a manually-invoked check, not a git hook — it runs only when you ask for it, so it never gets in the way of committing incrementally. Reach for it when you're about to push or open a PR. (When opening a PR, run this first, then use the `pr-create` / `pr-writer` skills to draft and open it.)

The repo's CI (`.github/workflows/ci.yml`) detects which of three areas changed and runs only those: **python** (`strands-py/`), **typescript** (`strands-ts/`), and **docs** (`site/`). This skill mirrors that routing locally.

## Process

### 1. Run the bundled script

From the repo root:

```bash
bash .agents/skills/pre-push/run-checks.sh
```

That path is relative to the repo root, but the script itself runs from anywhere in the repo — it locates the root with `git rev-parse --show-toplevel` before doing anything, so the area detection and checks are unaffected by your working directory. From a subdirectory, just point at the script absolutely:

```bash
bash "$(git rev-parse --show-toplevel)/.agents/skills/pre-push/run-checks.sh"
```

It detects the changed areas — comparing against the closest `main`/`master` base it can find (local or any remote, so `upstream/main` on a fork works too — fork-aware), plus staged, unstaged, and untracked changes — using the same path filters CI uses, then for each detected area runs two phases:

- **Phase 1 — auto-fix:** formatting, lint `--fix`, and lockfile sync. These are scoped to the files your change touches (so they never reformat unrelated files into your commit), write to working-tree files, and never fail the run.
- **Phase 2 — check:** the gate (build, lint check, format check, type-check, tests, audit), run tree-wide for CI parity. Phase 2 runs on the now-fixed tree and decides pass/fail.

The script exits non-zero if any check fails after fixing.

Useful flags:

- `--list` — show the detected areas and triggering files without running anything. Use first to confirm scope.
- `--all` — run every area regardless of what changed.
- `--base <ref>` — compare against `<ref>` instead of the auto-detected base.
- `--heavy` — also run the slow CI-parity steps skipped by default (browser tests, `test:package`, full Python version matrix). Slower, may need extra system deps; reach for it only when the change is risky in those dimensions.
- `python` / `typescript` / `docs` — run specific areas explicitly, overriding detection.

### 2. Triage what phase 2 reports

If phase 2 comes back green, you're done — report it and stop. If it's red, work the failures before calling the branch push-ready, splitting by whether the fix requires judgment:

- **Mechanical / unambiguous** — a missing type annotation, an unused import the linter flagged but didn't strip, a lockfile that needs committing. Just fix these and re-run the script.
- **Anything ambiguous** — loop back to the developer with the failing output before changing anything. The clearest case is a **test failure**: it means either the change broke real behavior (fix the code) or the behavior change is intended and the test is stale (fix the test). Don't guess, and never rewrite a test just to make it pass — that silences the very check that caught the regression. Surface it and let the developer decide.

How that split applies to the specific things phase 2 reports:

- **Lint / type errors** the autofixer couldn't resolve — usually mechanical; fix the code and re-run.
- **Test failures** — the judgment case above: show the failing output and let the developer decide whether the code or the test is wrong.
- **`npm audit`** — a high-severity advisory may be a pre-existing transitive dependency issue outside this change. Surface it; don't block the user's work on it. Note it and move on.
- **Missing tool** (`hatch`/`npm` not found) — the script says how to install. Report it; don't silently work around it.

After fixing anything, re-run the script to confirm green.

## Rules

- Always run the script rather than freehanding the commands — it keeps the path filters and check list in sync with CI.
- A green run clears the deterministic, single-platform failures but does not reproduce CI's OS/version matrices or the npm-pack smoke test. Report "local checks passed," not "CI will pass."
- The script writes to working-tree files in phase 1 (formatters, lockfile). That's expected for a push-readiness helper; the user can review with `git diff` before committing.
- If no area is detected (the change touches only files outside python/typescript/docs, e.g. top-level docs or `.agents/`), say so — there's nothing the merge gate runs for it, and that's fine.