login-cta-attribution-skill

name	login-cta-attribution-skill
description	CTA login attribution implementation skill for Django4Lyfe: guides adding new CTA sources, button/tab attribution, enum registration, and tests.
allowed-tools	Bash Read Edit Write Glob Grep
argument-hint	[platform] [action] (e.g., slack survey_complete)

Login CTA Attribution Skill

When to Use This Skill

Use this Skill in Django4Lyfe backend repos when implementing or updating login CTA attribution for Slack, Teams, or Email.

Primary command:

• /login-cta-attribution-skill:implement - add or update a CTA source with correct enum registration, attribution plumbing, and tests.

Example Prompts

• "Run /login-cta-attribution-skill:implement slack survey_complete."
• "Add a new Teams CTA source for weekly digest."
• "Implement email CTA attribution for our new campaign."

Architecture Overview

High-level flow:

CTA URL (?source=...) ->
CTA view parses source ->
magic link stores attribution metadata ->
auth exchange copies attribution to token ->
Mixpanel receives attribution fields

Button attribution has two valid layers:

1. Layer 1 (URL generation time): use stable URL builders with button/tab params.
2. Layer 2 (render time): append button/tab params to a base URL in formatters.

Use exactly one layer per CTA path to avoid double-attribution.

For concrete signatures and deeper architecture notes, read:

• references/architecture-and-signatures.md

Environment & Context Gathering

Before coding:

git branch --show-current
git status --porcelain

Read these files first:

• optimo_core/models/login_attribution.py
• optimo_core/utils/source_attribution.py
• optimo_integrations/utils/platform_magic_links.py

Also read local policy docs when present:

• AGENTS.md
• docs/python-typing-3.14-best-practices.md
• TY_MIGRATION_GUIDE.md

Type Gate Detection (Mandatory)

This is a Python code-touching skill. Use this precedence unless target repo docs/CI define a different order:

1. ty
2. pyright
3. mypy

Detect active checker:

• ty is active if any of:
  • [tool.ty] in pyproject.toml
  • ty.toml
  • .bin/ty
  • CI or pre-commit runs ty
• pyright is active if any of:
  • pyrightconfig.json
  • [tool.pyright] in pyproject.toml
  • CI or pre-commit runs pyright
• mypy is active if any of:
  • mypy.ini or .mypy.ini
  • [tool.mypy] in pyproject.toml
  • CI or pre-commit runs mypy

Command resolution order:

1. .bin/<tool>
2. uv run <tool>
3. <tool>

Examples:

# ty
.bin/ty check <changed python files>
uv run ty check <changed python files>

# pyright
.bin/pyright <changed python files>
uv run pyright <changed python files>

# mypy
.bin/mypy <changed python files>
uv run mypy <changed python files>

Strictness:

• Touched files must pass the active type gate with zero diagnostics.
• Do not accept "baseline acceptable" on touched files.
• Do not use blanket suppressions as default behavior.

Quality Checks

Run on changed files (or stricter if repo policy requires):

• .bin/ruff check --fix <changed files>
• .bin/ruff format <changed files>
• Active type gate (ty or pyright or mypy)
• Django checks (.bin/django check if available, else python manage.py check)
• Targeted pytest for attribution paths

Implementation Workflow

Step 1: Identify Platform and Action

From user request, resolve:

• platform: slack, teams, or email
• action: e.g. weekly_digest, survey_complete, dashboard_cta

Ask for clarification if either is ambiguous.

Step 2: Add Action Enum (if needed)

File: optimo_core/models/login_attribution.py

If action is new, add it to LoginSourceDetailChoices and keep the project's existing enum conversion pattern consistent.

Step 3: Add CTA Source Constant

File: optimo_core/models/login_attribution.py

Use enum composition and Final[str]:

CTA_SOURCE_{PLATFORM}_{ACTION}: Final[str] = (
    f"{LoginSourceChoices.{PLATFORM}.value}_{LoginSourceDetailChoices.{ACTION}.value}"
)

Step 4: Register the Source

File: optimo_core/models/login_attribution.py

Register in both:

• ALLOWED_CTA_SOURCES
• VALID_DETAILS_BY_SOURCE

Missing either commonly causes parse_cta_source() fallbacks.

Step 5: Add Platform-Specific Button/Tab Choices (if applicable)

• Slack: add or reuse SlackButtonChoices and SlackTabChoices.
• Teams: add or reuse TeamsButtonChoices and TeamsTabChoices.
• Email: no button/tab attribution enums.

Enum values are analytics identifiers. For static buttons (e.g., "Go to Dashboard") the label typically matches UI text. For dynamic links (e.g., employee profile) the identifier is generic — the UI renders context-specific text.

Step 6: Choose Attribution Layer Correctly

• Layer 1 (single-button contexts): pass button/tab directly into stable URL builders.
• Layer 2 (multi-button contexts like digests): append button/tab at render time with update_slack_cta_url_with_button_info() / update_teams_cta_url_with_button_info().

Never apply both layers on the same CTA path.

Step 7: Wire URL + Magic Link Usage

Use typed enums for source and detail where required, and keep button/tab value types aligned with the function signature you are calling.

Example (Slack, Layer 1):

from optimo_core.models.login_attribution import CTA_SOURCE_{PLATFORM}_{ACTION}
from optimo_core.models import SlackButtonChoices, SlackTabChoices
from optimo_integrations.utils.platform_magic_links import build_stable_slack_cta_url

url = build_stable_slack_cta_url(
    slack_user_uuid=user_uuid,
    source=CTA_SOURCE_{PLATFORM}_{ACTION},
    slack_tab=SlackTabChoices.HOME,
    slack_button=SlackButtonChoices.VIEW_ALL_ALERTS,
)

Example (Teams, Layer 1):

from optimo_core.models.login_attribution import CTA_SOURCE_{PLATFORM}_{ACTION}
from optimo_core.models import TeamsButtonChoices, TeamsTabChoices
from optimo_integrations.utils.platform_magic_links import build_stable_teams_cta_url

url = build_stable_teams_cta_url(
    teams_user_uuid=user_uuid,
    source=CTA_SOURCE_{PLATFORM}_{ACTION},
    teams_button=TeamsButtonChoices.GO_TO_DASHBOARD,
    teams_tab=TeamsTabChoices.OPTIMO_PULSE,
)

Example (direct magic-link builder):

from optimo_core.models.login_attribution import (
    LoginSourceChoices,
    LoginSourceDetailChoices,
)
from optimo_core.models import SlackButtonChoices, SlackTabChoices
from optimo_integrations.utils.platform_magic_links import build_login_magic_link_for_user

url = build_login_magic_link_for_user(
    user=user,
    login_cta_source=LoginSourceChoices.SLACK,
    login_cta_source_detail=LoginSourceDetailChoices.WEEKLY_DIGEST,
    slack_button=SlackButtonChoices.OPEN_IN_OPTIMO,
    slack_tab=SlackTabChoices.HOME,
)

Step 8: Update Tests and Supporting Docs

Add or update tests to cover:

• parser behavior (parse_cta_source)
• allowlist/detail registration
• button/tab propagation in URL + token metadata
• platform-specific behavior (Slack/Teams/Email differences)

Use enum values in tests, not raw magic strings.

Update local docs/guides in the target repo if new attribution behavior was introduced.

Critical Rules (Do Not Violate)

• No hardcoded source strings where constants/enums exist.
• Always register new sources in both allowlist and valid-details mapping.
• Keep Slack and Teams button/tab enums isolated by platform.
• Do not add button/tab semantics to Email.
• Maintain Slack/Teams attribution parity (if Slack has slack_tab, Teams must have teams_tab through all 9 chain points).
• Respect the selected attribution layer (Layer 1 or Layer 2, not both).
• Touched files must pass the active type gate.

Validation Checklist

Before completion:

• Action enum exists (if new action).
• CTA_SOURCE_* constant added with enum composition.
• Source is in ALLOWED_CTA_SOURCES.
• Source detail is in VALID_DETAILS_BY_SOURCE for the right platform.
• Platform button/tab handling is correct (Slack/Teams/Email rules).
• Correct attribution layer chosen and applied once.
• Magic-link attribution metadata path is preserved.
• Tests use enum values and cover parser + attribution flow.
• Ruff, active type gate, Django checks, and relevant tests pass.

Output Format

When reporting work, include:

1. What changed:
   • files touched
   • enums/constants/registrations added or modified
2. Validation executed:
   • lint, type checker used, Django checks, tests
3. Risk notes:
   • any fallback behavior or edge case not yet covered

If blocked, explicitly report the blocker with file-level context and exact failing command output summary.

References

For detailed signatures, metadata schema notes, parser behavior, and extended file map:

• references/architecture-and-signatures.md

Compatibility Notes

This Skill is designed to work with both Claude Code and OpenAI Codex.

• Claude Code: install plugin and invoke /login-cta-attribution-skill:implement.
• Codex: install skill directory and invoke name: login-cta-attribution-skill.