naming_skill

Overview

This skill defines a compact, context-aware naming convention for a Python Discord bot project. It prioritizes brevity and relies on module paths, type hints, and IDE/AI tooling to provide missing context. The core philosophy is to make names only as long as needed to be unambiguous in their immediate context. Rules cover domain nouns, suffix usage, parameter naming, and verb-first function names.

How this skill works

When invoked during new code creation, renaming, or code review, the skill inspects the target symbol and its module path, type annotations, and usage sites. It suggests shorter alternatives that avoid redundant context, preserves domain-root names (Trade, Fund, Nav, etc.), and applies specific suffix conventions only when necessary. It also offers parameter and function naming patterns that reduce verbosity while keeping clarity.

When to use it

• Creating classes, functions, or variables
• Renaming existing symbols or simplifying long names
• Reviewing code for naming consistency in PRs
• Designing new modules to determine name scope
• Responding to comments like 'name too long' or 'simplify naming'

Best practices

• Keep domain root nouns intact (Trade, Fund, Nav, Policy, Service).
• Avoid repeating module path information in class or function names.
• Use suffixes (Result, Facts, Draft, Check, Flag) only to disambiguate roles.
• Prefer minimal parameter names when type hints provide meaning (repo, code, day).
• Make function names verb-first and include the object only if context is unclear.

Example use cases

• Rename src/core/models/fund_restriction.FundRestrictionFact to Restriction or Fact in that module.
• Shorten dca_backfill.DcaDayCheck to DayCheck and BackfillDaysResult to BackfillResult inside the dca_backfill module.
• Replace long parameter names like fund_code and trade_date with code and day when types are annotated.
• Change build_dca_facts_for_batch() to build_facts(batch_id) and get_dca_day_checks() to checks() or day_checks().
• Choose DcaFacts on a package __init__ export but keep Facts inside the module to avoid cross-module ambiguity.