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.
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 repo rules first – treat AGENTS.md and CLAUDE.md as the source of truth when present; this Skill is a default baseline.
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 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

   • 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. Static formatting/linting

   • Ruff:
     • Run ./.security/ruff_pr_diff.sh if present.
     • Run .bin/ruff check --fix on changed Python files.
     • Run .bin/ruff format on those files.
   • 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.

3. Backend-specific .security gates

   • Run .security scripts where present:
     • ./.security/ruff_pr_diff.sh – Ruff on changed files vs base branch.
     • ./.security/local_imports_pr_diff.sh – check for local imports.
   • Treat failures as at least [SHOULD_FIX] and usually [BLOCKING] for atomic-commit.

4. Type checking with ty

   • Run ty on modified Python files only to catch type errors before CI:

     # 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