aitbc/ai-memory/failure-archive/regulatory-shadowing-trap.md

Failure Archive Entry

Issue

Related to PR #10 (aitbc1/fix-imports-docs) – initial attempt before fixing.

Attempt

Branch: aitbc1/fix-imports-docs (first version) Author: aitbc1

Approach

Fixed CLI import errors by adding numpy, pandas, aiohttp, fastapi, uvicorn to pyproject.toml and modifying main.py to conditionally import enterprise integration.

Did not rename the shadowed functions in regulatory.py.

Failure Mode

Running aitbc regulatory test resulted in:

KeyError: slice(None, 1, None)

The Click command function generate_sar was shadowing the imported generate_sar from regulatory_reporting. When the command body called generate_sar(...), it actually invoked the command function recursively or accessed the Click command object's subscript, causing a crash.

Root Cause

Name collision between imported service function and CLI command function.

Detection

Reproduced by running the regulatory test command after the branch was merged into a local main. Failure trace showed the command function being called with wrong arguments.

Resolution

Renamed imported functions in regulatory.py with _svc suffix:

• generate_sar → generate_sar_svc
• generate_compliance_summary → generate_compliance_summary_svc
• list_reports → list_reports_svc

Updated all internal calls accordingly.

Useful Artifacts

• The pattern of shadowing is now documented in ai-memory/bug-patterns.md.
• The fix (aliasing service imports) should be applied to any command module where names overlap.

Prevention

• When writing CLI command groups, avoid naming command functions identically to any imported callables from service modules.
• Consider static analysis rule: flag functions that define a name already imported at module scope.
• Alternatively, always import service functions with a distinct suffix (e.g., _svc) as a coding standard.

Recommendation

Future implementations of CLI commands should adopt the naming convention: service imports end with _svc. Example:

from regulatory_reporting import generate_sar as generate_sar_svc
...
def generate_sar(...):
    return generate_sar_svc(...)

---

Archived on 2026-03-15.