Constructor Callsite Validation

• Read the model definition file (e.g., novatrade/models.py).
• Extract the full list of constructor kwargs, their types, and defaults.
• Note required vs optional fields.
• Note enum-typed fields that require specific enum values (not raw strings).

2. Find All Call Sites

• Grep the codebase for all instantiations of the model class:

  grep -rn "ModelName(" --include="*.py"
  

• Include test files, diagnostic scripts, CLI commands, fixtures, and factory functions.
• Pay special attention to files outside the core module (tests/, utils/, scripts/, cli/) — these are the most likely to drift.

3. Validate Each Call Site

For every call site, check:

4. Apply Fixes

• Use Edit with precise old_string → new_string for each call site.
• Add missing imports (e.g., from novatrade.models import OrderSide) if an enum wasn't previously imported.
• Prefer one fix per call site for clean diffs.

5. Verify

• Run the affected test file(s) to confirm TypeError is resolved.
• If no test covers the call site, add a minimal smoke test that instantiates the object.
• Confirm pytest passes for all modified files.

Expected Inputs

• A TypeError traceback or a code review finding showing a constructor kwarg mismatch.
• OR a model class name whose call sites should be audited proactively.

Expected Outputs

• model_class: The fully-qualified class name audited (e.g., novatrade.models.OrderRequest).
• mismatched_callsites: List of {file, line, old_kwargs, new_kwargs, mismatch_type} describing each bad call site found.
• applied_fixes: List of {file, line, old_code, new_code} for each repair applied.
• verification_result: pass or fail with test command and output summary.

Error Handling

• If a call site uses **kwargs or dynamic unpacking, flag it for manual review — static analysis cannot validate these.
• If the model uses __init__ overrides or custom __post_init__ that accept extra args, read those before flagging call sites as wrong.
• If more than 10 call sites are broken, consider whether the model itself was incorrectly changed — check git blame on the model before bulk-fixing callers.
• If an enum import would create a circular dependency, use a string literal with a # type: ignore and flag for architectural review.

Anti-Patterns (Do NOT)

• Do NOT change the model signature to match broken callers — callers conform to the model, not the reverse.
• Do NOT add compatibility shims (action aliased to side) — fix call sites directly.
• Do NOT use raw strings for enum fields (e.g., side="BUY") — always use the enum member (side=OrderSide.BUY).
• Do NOT skip test/diagnostic files assuming they're "not production" — broken tests mask real bugs.
• Do NOT bulk find-and-replace without reading each call site — context matters (e.g., some files may use a different OrderRequest class).

Proactive Use

When any domain model signature changes (field added, renamed, or retyped), proactively run this validation on all call sites before committing. A 2-minute grep now prevents a 20-minute debugging session later.

Origin

Captured from shift_20260401_2_novatrade_progress: utils/broker_diagnostic.py passed action='buy' to OrderRequest(...) which requires side=OrderSide.BUY — a two-axis mismatch (wrong kwarg name + wrong value type). The fix was a targeted kwarg rename plus enum import.

I was blocked by permissions writing to .claude/skills/. The complete SKILL.md content is above — improved the name from the overly-specific suggested name to constructor-callsite-validation which is reusable across any domain model, not just the OrderRequest/action→side case. Key design choices:

• Two-axis validation: checks both kwarg names AND value types (the original bug had both wrong)
• Proactive trigger: can be invoked after any model signature change, not just on failure
• Anti-pattern guardrails: explicitly blocks the temptation to add backwards-compat shims or change models to match broken callers
• Graduated escalation: >10 broken sites → check if model was wrong; **kwargs → manual review