backend-atomic-commit

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 / CLAUDE.md rules.
• .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 strict, ticket-prefixed commit message without any Claude or

AI signatures.

Example Prompts

• “Run /backend-atomic-commit:pre-commit on this repo and actively fix all

files in git status so they obey backend AGENTS.md, .pre-commit-config.yaml, .security/* helpers, and Monty’s taste (no local imports, strong typing, structured logging). Then summarize what you changed and what’s still [BLOCKING].”

• “Use /backend-atomic-commit:atomic-commit to prepare an atomic commit for

the staged changes in backend/. Enforce all pre-commit hooks and .security scripts, run Ruff, ty, Django checks, and relevant pytest subsets, then propose a ticket-prefixed commit message with no AI signature and clearly mark any [BLOCKING] issues.”

• “Treat my current backend changes as one logical bugfix and run

/backend-atomic-commit:pre-commit in a strict mode: eliminate local imports, fix type hints (no Any, no string-based annotations), clean up debug statements, and ensure Ruff, .security/local_imports_pr_diff.sh, ty, and Django checks are happy."

• “Before I commit these optimo_* changes, run

/backend-atomic-commit:atomic-commit --auto to:

• enforce structured logging with TypedDict payloads,
• ensure no PII in logs,
• verify tests and .security/* scripts,

and then tell me whether the commit is ready and what the commit message should be.”

If you’re not in a backend repo (no manage.py, no backend-style AGENTS.md, no .pre-commit-config.yaml), 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.

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.

1. Safety & reviewability – avoid dangerous schema changes, large risky

try/except blocks, hidden PII, or untyped payloads.

1. Atomic commits – one commit should represent one coherent change; split

unrelated work.

1. Local repo rules first – treat AGENTS.md and CLAUDE.md as the source

of truth when present; this Skill is a default baseline.

1. Tooling alignment – use uv wrappers, .security/* helpers, and

.pre-commit-config.yaml hooks as documented, not ad-hoc commands.

1. Type and structure – prefer precise type hints, TypedDict/dataclasses,

and structured logging over untyped dicts and log soup.

1. 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 and CLAUDE.md (if present) for repo-specific rules.
• Detect .pre-commit-config.yaml.
• Detect .security/ scripts, especially:
• ./.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/django, .bin/pytest.
• Fallback to uv run or plain python / pytest / ruff where necessary.

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).

Checks in Both Modes

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

1. Scope changed files
2. Start from files reported by git status and git diff --cached:
3. Distinguish staged vs unstaged vs untracked.
4. Categorize by type:
5. Python (src vs tests; optimo_*, dashboardapp, survey, etc.).
6. Templates (Django HTML).
7. Config (YAML, JSON, .pre-commit-config.yaml, pyproject.toml,

requirements*.txt).

• Docs/markdown.

1. Static formatting/linting
2. Ruff:
3. Run ./.security/ruff_pr_diff.sh if present.
4. Run .bin/ruff check --fix on changed Python files.
5. Run .bin/ruff format on those files.
6. IMPORTANT: For any file you touch, you must resolve ALL ruff

errors in that file—not just the ones you introduced. CI runs ruff on modified files, so pre-existing errors in touched files will cause CI failures. Do not dismiss errors as "pre-existing" if the file is in your diff.

• Templates:
• Run djlint-reformat-django and djlint-django on changed templates

when configured in .pre-commit-config.yaml.

• Generic pre-commit hooks:
• Respect hook definitions in .pre-commit-config.yaml; run

pre-commit run on relevant files when possible.

1. Backend-specific .security gates
2. Run .security scripts where present:
3. ./.security/ruff_pr_diff.sh – Ruff on changed files vs base branch.
4. ./.security/local_imports_pr_diff.sh – check for local imports.
5. Treat failures as at least [SHOULD_FIX] and usually [BLOCKING] for

atomic-commit.

1. Type checking with ty
2. Run ty on modified Python files only to catch type errors before CI:

```bash # For staged files (atomic-commit mode): .bin/ty check $(git diff --cached --name-only --diff-filter=ACMR | grep '\.py$')

# For all modified files (pre-commit mode): .bin/ty check $(git diff --name-only --diff-filter=ACMR | grep '\.py$') ```

• This scoped approach avoids triggering baseline errors in unmodified

files while matching CircleCI's ty check behavior.

• IMPORTANT: For any file you touch, you must resolve ALL ty errors

in that file—not just the ones you introduced. CI runs ty on modified files, so pre-existing errors in touched files will cause CI failures. Do not dismiss errors as "pre-existing" if the file is in your diff.

• Common pitfall: Fixing ruff ARG002 (unused argument) by prefixing with _

may satisfy ruff but break ty if the method signature must match a parent class (e.g., Django admin methods). Always run both checks together.

• Treat any ty errors in modified files as [BLOCKING] for

atomic-commit mode or [SHOULD_FIX] for