login-cta-attribution-skill

What this skill does

# 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:

```text
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:

```bash
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:

```bash
# 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]`:

```python
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):

```python
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):

```python
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):

```python
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, ac