backend-atomic-commit

What this skill does

# Backend Atomic Commit Skill

## When to Use This Skill

Use this Skill in backend/Django repos (especially the Diversio monolith
backend) when you want:

- `/backend-atomic-commit:pre-commit` – to **actively fix** the current code
  (formatting, imports, type hints, logging, etc.) so that it matches:
  - Local `AGENTS.md`, linked repo-local docs, and quality gates.
  - `.pre-commit-config.yaml` expectations.
  - `.security/` diff helpers (ruff and local imports).
  - Monty’s backend taste.
- `/backend-atomic-commit:atomic-commit` – to run the same checks plus:
  - Enforce that the **staged changes are atomic** (one coherent change).
  - Ensure all quality gates are green (no shortcuts).
  - Propose a commit message that follows the repo-local harness **without** any Claude or AI signatures.
- `/backend-atomic-commit:commit` – to run `atomic-commit`, then **create the commit** once all gates are green (no bypassing commit-msg hooks).

Representative prompt shapes live in `references/usage-examples.md`.

If you’re not in a backend repo (no `manage.py`, no backend-style `AGENTS.md`,
no `.pre-commit-config.yaml`, no backend quality docs), this Skill should say
so explicitly and fall back to a lighter “generic Python pre-commit” behavior.

## Modes

This Skill behaves differently based on how it is invoked:

- `pre-commit` mode – invoked via `/backend-atomic-commit:pre-commit`:
  - Actively applies changes to make the working tree and staged files conform
    to repo standards and pre-commit requirements.
  - Runs all relevant static checks and auto-fixers.
  - Does **not** propose or drive a commit.
- `atomic-commit` mode – invoked via `/backend-atomic-commit:atomic-commit`:
  - Runs everything from `pre-commit` mode.
  - Enforces atomicity of staged changes.
  - Requires all gates to be green.
  - Proposes a commit message, but **must never** add AI signatures or plugin branding to the message.
- `commit` mode – invoked via `/backend-atomic-commit:commit`:
  - Runs everything from `atomic-commit` mode.
  - Creates the commit once all gates are green.
  - Must still never add AI signatures or plugin branding to the message.

The command markdown sets the mode. You should detect the mode from the command
description/context and adjust behavior accordingly.

## Core Priorities

Emulate Monty’s backend engineering and review taste, tuned for pre-commit:

1. **Correctness & invariants** – multi-tenancy, time dimensions, and security
   constraints come first.
   - Never eyeball date/time math (day-of-week, "yesterday", timezone edges).
     Always verify using `date +%Y-%m-%d` or Python `datetime` — never compute
     dates manually. Date calculation errors have been a recurring friction
     point in real sessions.
2. **Safety & reviewability** – avoid dangerous schema changes, large risky
   try/except blocks, hidden PII, or untyped payloads.
3. **Atomic commits** – one commit should represent one coherent change; split
   unrelated work.
4. **Local harness first** – treat `AGENTS.md` as the canonical entrypoint,
   follow linked repo-local docs and directory-scoped `AGENTS.md` files for
   per-topic truth, and do not treat `CLAUDE.md` as a unique rule source.
5. **Tooling alignment** – use uv wrappers, `.security/*` helpers, and
   `.pre-commit-config.yaml` hooks as documented, not ad-hoc commands.
6. **Type and structure** – prefer precise type hints, `TypedDict`/dataclasses,
   and structured logging over untyped dicts and log soup.
7. **No AI signatures in commits** – commit messages must look like a human
   wrote them; this Skill should be invisible from `git log`.

Always prioritize `[BLOCKING]` issues over style and nits.

## Environment & Context Gathering

When this Skill runs, you should first gather context using `Bash`, `Read`,
`Glob`, and `Grep`:

- Git context:
  - `git status --porcelain`
  - `git branch --show-current`
  - `git diff --cached --stat`
  - `git diff --cached --name-only`
  - `git log --oneline -10`
- Repo configuration:
  - Read `AGENTS.md` first for repo-specific rules and doc routing.
  - Load linked repo-local docs relevant to the changed files, especially
    quality gates, runbooks, architecture docs, directory-scoped `AGENTS.md`
    files, and any GitHub-first workflow sections covering branch naming,
    issue linkage, or PR readiness.
  - If `CLAUDE.md` exists, treat it as a pointer to `AGENTS.md`, not as a
    source of unique behavioral rules.
  - If the harness is missing or obviously stale, recommend generating or
    canonicalizing docs via the `repo-docs` plugin so rules stop living in
    tribal knowledge.
  - Detect `.pre-commit-config.yaml`.
  - Detect `.security/` scripts, especially:
    - `./.security/gate_cache.sh`
    - `./.security/ruff_pr_diff.sh`
    - `./.security/local_imports_pr_diff.sh`
  - Detect `manage.py` / Django project layout.
- Tool availability:
  - `uv` and `.bin/` wrappers:
    - `.bin/ruff`, `.bin/ty`, `.bin/pyright`, `.bin/mypy`, `.bin/django`,
      `.bin/pytest`.
  - Fallback to `uv run` or plain `python` / `pytest` / `ruff` where necessary.
  - Read local typing policy docs when present (for example:
    `docs/python-typing-3.14-best-practices.md`, `TY_MIGRATION_GUIDE.md`) and
    follow them over this default.

If the repo clearly isn’t the Diversio backend / Django4Lyfe style, say so and
adjust expectations (but you can still run generic Python pre-commit checks).

### Gate cache behavior (when available)

If `./.security/gate_cache.sh` exists, treat it as the canonical wrapper for
heavy deterministic checks. Use it by default for type gates and Django checks.

```bash
./.security/gate_cache.sh --gate ty-check --scope index -- .bin/ty check .
./.security/gate_cache.sh --gate django-system-check --scope index -- uv run python manage.py check --fail-level WARNING
```

Use `scope=index` for commit-focused gating and `scope=working` when results are
expected to depend on unstaged edits. Do not bypass cache unless explicitly
requested or debugging:

```bash
CHECK_CACHE_BUST=1 ./.security/gate_cache.sh --gate ty-check --scope index -- .bin/ty check .
./.security/gate_cache.sh --clear-this-checkout
```

For Ruff/local-import diff helpers, call the scripts directly. They already use
cache-aware execution internally and include local staged/unstaged tracked files.
Prefer running them through pre-commit hooks first; call scripts directly only
for targeted diagnosis or when a matching hook is missing/disabled.

## Checks in Both Modes

In **both** `pre-commit` and `atomic-commit` modes, follow this pipeline:

1. **Scope changed files**
  - Start from files reported by `git status` and `git diff --cached`:
    - Distinguish staged vs unstaged vs untracked.
   - Categorize by type:
     - Python (src vs tests; `optimo_*`, `dashboardapp`, `survey`, etc.).
     - Templates (Django HTML).
     - Config (YAML, JSON, `.pre-commit-config.yaml`, `pyproject.toml`,
       `requirements*.txt`).
     - Docs/markdown.

2. **Run pre-commit first (primary execution path)**
   - If `.pre-commit-config.yaml` exists, run hooks on the intended file set
     before any direct per-tool commands.
   - `atomic-commit` mode:
     - run on staged files only:
     ```bash
     pre-commit run --files $(git diff --cached --name-only --diff-filter=ACMR)
     ```
   - `pre-commit` mode:
     - run on modified tracked + untracked files:
     ```bash
     CHANGED_FILES="$(
       {
         git diff --name-only --diff-filter=ACMR
         git ls-files --others --exclude-standard
       } | sed '/^$/d' | sort -u
     )"
     pre-commit run --files $CHANGED_FILES
     ```
   - If pre-commit already executed a gate successfully, do not rerun the same
     gate directly in the same pass.

3. **Direct command fallback (targeted, non-duplicative)**
   - Run direct commands only when:
     - a corresponding hook failed and you need focused diagnosis/fix loops, or
     - the repository does not expose that gate via pre-commit