Skip to content

DexForce/EmbodiChain / .agents/skills/pre-commit-check

pre-commit-check

Verified

Use before committing or creating a PR for EmbodiChain to select proportional validation and verify affected code style, tests, headers, annotations, exports, and docstrings

FileKindSize
SKILL.mdskill md9.6 KB
agents/openai.yamlconfig103 B
---
name: pre-commit-check
description: Use before committing or creating a PR for EmbodiChain to select proportional validation and verify affected code style, tests, headers, annotations, exports, and docstrings
---

# Pre-Commit Check

Run proportional local checks for the files being changed, catching relevant
issues before pushing without defaulting to the full test suite.

## When to Use

- Before creating a commit or PR
- User says "check my changes", "pre-commit", "verify before commit", "ready to push"
- After making any code changes to `.py` files

## Steps

### 1. Identify Changed Files

```bash
git diff --name-only HEAD
git diff --name-only --cached
git status --short
```

Collect all changed/added `.py` files.

Classify the change by affected area: workflow, docs, agent skill, packaged
configuration, isolated Python module, package-wide behavior, or cross-cutting
infrastructure.

### 2. Run Black Formatting Check

This is the **first CI gate** and will cause immediate failure:

```bash
black --check --diff --color ./
```

If it fails, run `black .` and review the formatting changes.

### 3. Check Public API Documentation Coverage

Run the same read-only gate used by CI:

```bash
python docs/scripts/check_api_docs.py
```

If it reports missing exports, use `$update-api-docs` to add useful Sphinx
entries and descriptions. Do not change `__all__` solely to make this check
pass.

### 4. Check Apache 2.0 Copyright Header

Every `.py` file must begin with the 15-line copyright block. For each changed/new `.py` file, verify the first line is:

```
# ----------------------------------------------------------------------------
```

The full header template:

```python
# ----------------------------------------------------------------------------
# Copyright (c) 2021-2026 DexForce Technology Co., Ltd.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
# ----------------------------------------------------------------------------
```

### 5. Check `from __future__ import annotations`

Every `.py` file must have this import (after the header, before other imports). This enables `A | B` syntax and forward references.

### 6. Check `__all__` in Public Modules

For any new or modified module under `embodichain/`, verify it defines `__all__` listing all public symbols. Example:

```python
__all__ = ["MyClass", "my_function"]
```

Skip this check for `__init__.py` files that only re-export via `from . import *`.

### 7. Check Docstrings on Public APIs

For any new public function, class, or method:
- Must have a Google-style docstring
- Must include `Args:` section if it takes parameters
- Must include `Returns:` section if it returns a value
- Use `.. attention::` or `.. tip::` directives for non-obvious behavior

### 8. Check Type Annotations

For any new public API:
- All parameters must have type hints
- Return type must be annotated
- Use `A | B` over `Union[A, B]`
- Use `TYPE_CHECKING` guard for imports that would cause circular dependencies

### 9. Check `@configclass` Usage

For any new configuration class:
- Must use `@configclass` decorator (not bare `@dataclass`)
- Must use `from dataclasses import MISSING` for required fields
- Import from `embodichain.utils import configclass`

### 10. Select and Run Relevant Tests

Do not treat the CI test job as a requirement to run `pytest tests` locally for
every change. Choose the smallest command set that exercises the affected
behavior:

| Change scope | Default validation |
|---|---|
| `.github/workflows/**` only | `actionlint` on changed workflows; run related script tests only when workflow scripts changed |
| Human-facing docs content only | Relevant Sphinx build or docs-specific tests |
| `agent_context/**` or its routing helper | Run `context.py check` and `tests/test_agent_context_{map,tools}.py`; use advisory `stats --base REF` and representative overview-to-owner lookups when restructuring; exercise representative routes when routing changes |
| `.agents/skills/**` and thin adapters | Run `quick_validate.py` for each changed canonical skill; compile/run any bundled scripts |
| Task Program components/deployments | Run the `$add-task-program` static deployment inspector plus the closest configured-integration/package-data tests |
| Other packaged JSON/YAML | Parse through the production loader and run the closest config/layout tests |
| One Python module | Matching `tests/**/test_<module>.py` |
| One package/subsystem | Tests for that package plus focused integration tests |
| Packaging/release code | Package build and artifact validation |
| Shared core, global test config, or multiple subsystems | Broader affected tests; full suite only when narrow coverage is not credible |

Skip runtime tests when no executable behavior is affected, but still run the
appropriate syntax or configuration validator. Run the full suite only when:

- the change affects shared core behavior used throughout the repository;
- global dependencies, test configuration, or environment initialization changed;
- several subsystems are modified together;
- a release-critical behavior cannot be validated narrowly; or
- the user explicitly requests it.

For changes identified as performance-sensitive during task analysis, follow
[implement-performance](../implement-performance/SKILL.md) and select focused
correctness checks for the algorithm, batch, memory or concurrency contracts
being changed. Validate material performance claims using
[benchmark](../benchmark/SKILL.md), comparing equivalent workloads and quality
settings, including relevant small-batch behavior and peak memory. Report
measured gains, tradeoffs and regressions with hardware and timing scope. If
required hardware is unavailable, state what remains unvalidated; passing CPU
tests does not establish GPU performance. Ordinary edits do not require a
benchmark run.

Before starting a command likely to take more than two minutes, report the
selected scope and why narrower validation is insufficient. Honor explicit user
instructions to skip or narrow tests.

For canonical skill directories, use:

```bash
python "${CODEX_HOME:-$HOME/.codex}/skills/.system/skill-creator/scripts/quick_validate.py" \
  .agents/skills/<skill>
```

If the personal skill installation differs, locate the available `skill-creator`
validator through the session skill catalog instead of assuming a username.

Thin `.claude/skills/` and `.github/copilot/` adapters should point back to
the canonical `.agents/skills/<skill>/SKILL.md`; do not duplicate the full
instructions in adapters.

### 11. Check Test Coverage and Necessity

Apply the shared
[test necessity review](../add-test/SKILL.md#test-necessity-review) to the changed
behavior and any added or extended cases. Confirm that observable behavior and
real regressions have meaningful coverage; reuse sufficient existing tests
without requiring a new test file for every public module or function.

Report an actual unverified contract or regression when coverage is missing.
Review additions for redundancy and verification value, and briefly identify
the existing coverage relied upon or why runtime tests are unnecessary. Check
test file headers with the other changed Python files in step 4.

### 12. Summary Report

Output a pass/fail summary:

```
Pre-Commit Check Results
========================
[PASS] Black formatting
[PASS] Public API docs coverage
[PASS] Apache 2.0 headers (5/5 files)
[FAIL] from __future__ import annotations — missing in: foo.py
[PASS] __all__ exports
[PASS] Docstrings on public APIs
[PASS] Type annotations
[PASS] @configclass usage
[PASS] Targeted tests — tests/foo/test_bar.py
[N/A] Full test suite — isolated change covered by targeted tests
[PASS] Coverage and test necessity — existing coverage reused; no redundant additions

Fix the above issues before committing.
```

## What CI Checks

The project's CI pipeline (`.github/workflows/main.yml`) runs:

1. **lint** job: `black --check --diff --color ./`
2. **lint** job: `python docs/scripts/check_api_docs.py`
3. **test** job: proportional pytest groups after lint passes
4. **build** job: Sphinx docs build after lint passes

This skill always covers the relevant lint and structural checks, then selects
tests proportionally. It does not require reproducing the entire CI pipeline for
every local change.

## Common Mistakes

| Mistake | Fix |
|---------|-----|
| Running `black` on only one file | Run `black .` on the whole project — CI checks everything |
| Forgetting test Apache header | Test files also need the 15-line copyright block |
| Using `Union[A, B]` | Use `A \| B` (with `from __future__ import annotations`) |
| Using bare `@dataclass` | Use `@configclass` from `embodichain.utils` |
| Missing `__all__` in new module | Add `__all__` with all public symbols |

## Quick Reference

| Check | Command/Method |
|-------|---------------|
| Black formatting | `black --check --diff --color ./` |
| Auto-fix formatting | `black .` |
| Public API docs | `python docs/scripts/check_api_docs.py` |
| Header check | Verify first line is `# ---...---` |
| `__future__` import | Grep for `from __future__ import annotations` |
| `__all__` export | Grep for `__all__` in module |
| Run targeted tests | `pytest tests/<affected-path>` |
| Run full tests | `pytest tests` only when the full-suite criteria above apply |
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall