cognito-user-analysis

$npx mdskill add ClipboardHealth/core-utils/cognito-user-analysis

Resolve Cognito login failures by detecting and fixing duplicate accounts.

  • Identifies duplicate user accounts sharing phone numbers or email addresses.
  • Integrates with AWS Cognito and backend user databases for data comparison.
  • Analyzes account status to determine which duplicates to retain or delete.
  • Outputs detailed analysis reports and executes safe deletion scripts.

SKILL.md

.github/skills/cognito-user-analysisView on GitHub ↗
---
name: cognito-user-analysis
description: Use when looking up Cognito user details by sub UUID, finding duplicate accounts sharing phone or email, analyzing which duplicates to keep vs delete, or fixing orphaned UNCONFIRMED signups. Symptoms include 403 Forbidden on login, multiple accounts for same phone, backend sync issues.
---

# Cognito User Analysis

Analyze and fix duplicate Cognito users in clipboard-production by comparing against backend data.

**Skill directory:** This skill's scripts are in `scripts/` relative to this file.

## When to Use

- User reports "403 Forbidden" or can't log in (possible duplicate blocking)
- Need to look up Cognito user details from sub UUIDs
- Finding accounts sharing same phone/email
- Cleaning up orphaned UNCONFIRMED signups
- Backend `cbh_user_id` doesn't match Cognito

**Not for:** Single user attribute updates (use AWS CLI directly)

## Quick Start

```bash
# 1. Verify prerequisites
scripts/check-prerequisites.sh

# 2. Create input file (one sub per line)
echo "68e1e380-d0c1-7028-4256-3361fd833080" > subs.txt

# 3. Pipeline: lookup → find duplicates → analyze → fix
scripts/cognito-lookup.sh subs.txt results.csv
scripts/cognito-find-duplicates.sh results.csv duplicates.csv
scripts/cognito-analyze-duplicates.sh duplicates.csv analysis.csv

# 4. Review analysis.csv, then fix (ALWAYS dry-run first!)
scripts/cognito-fix-duplicates.sh analysis.csv --dry-run
scripts/cognito-fix-duplicates.sh analysis.csv
```

## Prerequisites

Run `scripts/check-prerequisites.sh` to verify. Requirements:

| Requirement                           | Setup                                                       |
| ------------------------------------- | ----------------------------------------------------------- |
| AWS profile `cbh-production-platform` | `aws sso login --profile cbh-production-platform`           |
| `~/.cbh_token`                        | Get from web app dev tools → Network → Authorization header |

See [references/setup.md](references/setup.md) for detailed setup.

## Scripts

All scripts support `--help`. Run `<script> --help` for full usage.

| Script                                  | Purpose                                     |
| --------------------------------------- | ------------------------------------------- |
| `scripts/check-prerequisites.sh`        | Verify AWS + API token are valid            |
| `scripts/cognito-lookup.sh`             | sub → user details CSV                      |
| `scripts/cognito-find-duplicates.sh`    | Find accounts sharing phone/email           |
| `scripts/cognito-analyze-duplicates.sh` | Compare against backend, assign KEEP/DELETE |
| `scripts/cognito-fix-duplicates.sh`     | Execute deletions and updates               |

## Scoring (Analysis)

Compares Cognito accounts against backend to determine which to keep:

| Score | Meaning                                                |
| ----- | ------------------------------------------------------ |
| 185   | Perfect match: cbh_user_id + email + phone + CONFIRMED |
| 100+  | cbh_user_id matches (high confidence)                  |
| 25-99 | Partial match (email or phone only)                    |
| 0-24  | Orphaned signup (UNCONFIRMED, no backend link)         |

Highest score = `KEEP_AND_UPDATE`. Others = `DELETE`.

## Common Mistakes

| Mistake                | Fix                                            |
| ---------------------- | ---------------------------------------------- |
| 403 Forbidden from API | Token expired → get fresh token from web app   |
| Skipping --dry-run     | Always dry-run first. Deletes are permanent.   |
| Wrong AWS profile      | Run `scripts/check-prerequisites.sh` to verify |

## Detailed Docs

- [references/setup.md](references/setup.md) - Prerequisites setup guide
- [references/analysis-workflow.md](references/analysis-workflow.md) - Pipeline details
- [references/fix-workflow.md](references/fix-workflow.md) - Fix execution details

More from ClipboardHealth/core-utils

SkillDescription
adversarial-reviewPerform an adversarial review of proposed work. Use ONLY when the user explicitly types /adversarial-review. Never auto-trigger, even if the user mentions reviewing, questioning, or challenging their approach.
clipboard-testingEnd-to-end testing playbook for Clipboard Health changes. Use when the user wants to verify, exercise, or set up test data for a backend or frontend change against a live environment — "test my change end-to-end", "verify this works in dev", "create a test workplace / worker / shift", "get a shift through to paid / invoiced", "prove the API change works". Defaults to the `development` AWS environment, API-first (cbh CLI tokens + curl). The skill knows enough to run the core happy-path flow (workplace → worker → shift → clock in/out → pay → invoice) autonomously; for anything else, it orients around the codebase and asks the user for missing directories.
datadog-investigateInvestigate production issues by querying Datadog logs, metrics, and APM traces, then correlating findings with the codebase. Use this skill whenever the user mentions production errors, Datadog, observability, log investigation, latency spikes, error rate increases, 500s, trace IDs, monitor alerts, or wants to debug any service issue in a deployed environment.
flaky-test-debuggerDebug and fix flaky tests including Playwright E2E, NestJS service/integration, React component, and unit tests. Use this skill when investigating intermittent test failures, triaging flaky tests, or fixing test instability.
interview-featureUse when clarifying requirements for a feature ticket. Iteratively researches and interviews the user until the problem is well-understood, then produces a structured problem brief. Dispatched by write-feature-ticket when context is insufficient.
investigate-ticketUse when investigating a bug, incident, or issue before implementation. Researches codebase, queries Datadog, and presents structured findings with handoff options. Also use when asked to "look into" or "investigate" something.
local-packageUse Clipboard's internal CLI to link and unlink @clipboard-health packages across repositories for local development. Use when testing local package changes, linking @clipboard-health packages between repos, or using the cbh CLI local-package command.
seed-dataTrigger seed data generation for test environments via GitHub Actions. Use when asked to seed, create test data, or set up HCPs/facilities/shifts.
write-bug-ticketUse when creating a Linear bug report ticket from conversation context, investigation findings, or user-provided evidence. Focuses on structuring and writing — not investigating.
write-feature-ticketUse when creating a Linear feature request ticket from conversation context, a brief description, or code/PR analysis. Interviews the user for clarity when context is insufficient.