script-quality-gate

name	script-quality-gate
description	Apply when adding or modifying runnable scripts/entrypoints. Ensures docstring, argparse, __main__, logging, and import/path conventions are correct.

script-quality-gate

Use this skill when creating or changing a runnable script / CLI entrypoint.

When to use

• New script added anywhere in the repo
• Changes to an existing runnable script or CLI flags
• Any time documentation references a new/changed entrypoint

Goal

Ensure runnable scripts are predictable, documented, and consistent across the repository.

Checklist (must pass)

Location & packaging

• Put runnable scripts in the intended scripts location for this repository.
  • If the repo has an established pattern (e.g. a root entrypoint like run_app.py / cli.py), follow it.
  • Do not introduce a new script folder pattern unless necessary; prefer consistency.
• Ensure any code directory is a Python package (has __init__.py) when it must be importable as a module.

Docstring (top-level, required)

Add/maintain a top-level module docstring matching this template:

"""
Brief: <one-liner description>

Inputs:
- CLI args: list each `--flag` with a short “what it does” plus expected format (and defaults when non-obvious).
  - Example: `--input-dir`: Directory containing JSON outputs from the previous pipeline step.
  - Example: `--dry-run`: Validate only; skip writes.
- Files/paths: describe expected structure (file types, patterns, required subfolders).
- Env vars: list required environment variables and what they control (never include secret values).

Outputs:
- <files, stdout, DB writes, API responses, etc.>

Usage (from project root):
- python -m <module.path> --arg1 ...
"""

CLI conventions

• Use argparse.
• Provide --help descriptions that match README examples.
• Do work inside main(); avoid side effects at import time.
• Include:
  • def parse_args() -> argparse.Namespace:
  • def main() -> None:
  • if __name__ == "__main__": ...

Logging

• Use logging (not print), except intentional CLI UX cases.
• Ensure logger setup follows the repository logging conventions (do not duplicate logger setup code).

Imports & paths

• Prefer absolute imports.
• Prefer pathlib.Path for filesystem paths.

After the checklist

• Run the docs-after-change skill to ensure README/architecture references stay correct.