Clerk Expo Skill Audit

Audit transversal de skills/mobile/clerk-expo/ dans ce dépôt par rapport à la source réelle du SDK @clerk/expo et au contenu clerk-docs qu'il cite. La source du SDK fait autorité pour la forme de l'API ; clerk-docs fait autorité pour les modèles recommandés ; la skill doit suivre les deux. Quand les deux divergent sur un fait (une API existe, une signature, une valeur par défaut, une version plancher), la source du SDK gagne — toujours. Les docs gagnent seulement sur les questions prescriptives que la source ne peut pas répondre (quel flux recommander, placement des props dans les exemples, prérequis du dashboard).

La skill forcode intentionnellement des snippets de code vérifiés (voir sa gate de fraîcheur). Cet audit est la moitié maintenance de ce contrat : il s'exécute après les releases du SDK pour que les snippets restent vérifiés plutôt que de devenir du folklore.

Entrées

Source de vérité du SDK : un checkout clerk/javascript contenant packages/expo/ (et packages/shared/src/types/ pour les types de ressources sign-in/sign-up).
Source de vérité des docs : un checkout clerk/clerk-docs contenant docs/getting-started/quickstart.expo.mdx, docs/guides/development/custom-flows/authentication/*.mdx, et docs/reference/expo/**.
Skill cible : skills/mobile/clerk-expo/SKILL.md, references/*.md, et evals/evals.json.
Corroboration optionnelle : un checkout clerk/clerk-expo-quickstart (trois apps exemple exerçant l'API actuelle).

Résolution des checkouts source

Résous chaque checkout dans cet ordre :

Utilise --sdk <chemin> / --docs <chemin> quand fournis. Le chemin du SDK doit contenir packages/expo/package.json ; le chemin des docs doit contenir docs/getting-started/quickstart.expo.mdx.
Cherche les checkouts frères de ce dépôt : ../javascript et ../clerk-docs (disposition standard des projets Clerk), et ../clerk-expo-quickstart pour corroboration.
Si CLERK_JAVASCRIPT_REPO / CLERK_DOCS_REPO sont définis, utilise ces chemins.
Si un checkout manque et l'accès réseau est acceptable, clone peu profondément dans .context/ :

mkdir -p .context && cd .context
git clone --depth 1 https://github.com/clerk/javascript.git
git clone --depth 1 https://github.com/clerk/clerk-docs.git

Si ni l'un ni l'autre n'est disponible, arrête-toi et demande les chemins à l'utilisateur. N'audit pas de mémoire ou d'une copie installée node_modules seule ; l'audit existe précisément parce que la mémoire s'éloigne.

Flux de travail

1. Établis le delta de version

Lis la version estampillée de la skill depuis le frontmatter de SKILL.md (compatibility:) et son texte de gate de fraîcheur.
Lis la version actuelle depuis packages/expo/package.json plus peerDependencies (plage d'Expo SDK, plancher React Native, plage React) et les versions de SDK natif bundlées (clerk-ios, clerk-android dans dependencies).
Lis les entrées packages/expo/CHANGELOG.md entre la version estampillée et la version actuelle. C'est la queue de travail principale : chaque entrée du changelog affecte la skill ou est explicitement sans pertinence.

Si la version estampillée égale la version actuelle et le changelog ne montre rien de nouveau, rapporte « pas de dérive » et arrête-toi.

2. Inventorie la surface du SDK

Construis un inventaire structuré à partir de la source (préfère src/ à dist/) :

Carte d'exports : packages/expo/package.json exports — chaque sous-chemin (/native, /web, /token-cache, /resource-cache, /secure-store, /local-credentials, /passkeys, /google, /apple, /legacy, /experimental, …), en notant les ajouts et suppressions.
Hooks : tout ce qui est réexporté depuis src/hooks/index.ts et les hooks spécifiques à Expo (useSSO, extensions useAuth, useSignInWithGoogle, useSignInWithApple, useLocalCredentials). Capture les signatures, les formes de retour, et les tags @deprecated.
Ressources de flux personnalisés : la surface de méthodes de SignInFutureResource / SignUpFutureResource dans packages/shared/src/types/signInFuture.ts et signUpFuture.ts (noms de méthode, formes de paramètres, enums de statut). La référence custom-flows de la skill reflète cette surface.
Composants natifs : exports de src/native/index.ts et les types de props de chaque composant (AuthView.types.ts, UserProfileView, UserButton). Signale toute prop que la skill nomme mais qui n'existe plus, et toute prop publique nouvelle.
Plugin de configuration : src/plugin/withClerkExpo.ts — variables env requises, schéma d'option de thème, effets secondaires de plateforme (cibles de déploiement, schémas d'URL).
Provider : props de src/provider/ClerkProvider.tsx, spécialement les expérimentaux (__experimental_passkeys, __experimental_resourceCache) et tous les noms récemment stabilisés.
Avertissements dev / signaux de migration : grep pour @deprecated, console.warn, et avis de migration de package (p. ex. la scission @clerk/expo-google-signin). Ceux-ci deviennent des notes « changements à venir » dans la skill.

3. Inventorie les affirmations des docs

Pour chaque URL docs canonique citée dans les références de la skill :

Confirme que le fichier .mdx correspondant existe toujours dans clerk-docs à cette route (chemin URL → chemin docs/). Les citations cassées sont de la dérive.
Relis l'onglet/section Expo de chaque guide de flux personnalisé cité et le quickstart Expo. Où le modèle recommandé des docs a changé (nouvelle étape requise, placement de prop changé, nouveau prérequis dashboard), le snippet correspondant de la skill est de la dérive même s'il compile toujours.

4. Extrait les affirmations de la skill

Lis SKILL.md, chaque references/*.md, et evals/evals.json. Extrait chaque affirmation concrète :

Estampilles de version et plages peer.
Chaque snippet de code (imports, appels de méthode, props, noms de variables env).
Chaque gate et pitfall qui nomme une API (useSSO vs useOAuth, resourceCache vs secureStore, point de montage captcha, placement de treatPendingAsSignedOut).
La matrice de capacité (Expo Go / dev build / web).
Les attentes d'eval qui assurent les chaînes de l'API.

5. Diff et classement

Produis un diff structuré avec quatre buckets :

Manquant de la skill : nouveaux exports, hooks, props, flux, ou prérequis dans le SDK/docs que la skill devrait couvrir (ou explicitement délimiter).
Obsolète dans la skill : affirmations contredites par la source ou les docs — APIs renommées/supprimées, valeurs par défaut changées, planchers peer changés, props déplacées, URLs docs mortes, evals assurant des chaînes obsolètes.
Fin dans la skill : couverte mais sous-spécifiée par rapport à la surface réelle de pitfall (p. ex. un nouveau code d'erreur que les développeurs vont rencontrer).
Sur-spécifiée : détaille ce que les docs ou .d.ts installés couvrent mieux ; propose un rétrécissement où il réduit le risque de dérive.

Cite le fichier source et la ligne pour chaque entrée bucket-1/2/3, plus l'emplacement de la skill cible.

6. Propose des édits

Émets une proposition prête pour review groupée par fichier cible. Pour chaque changement inclus la sévérité (drift, gap, ou polish), la citation source, l'emplacement cible, et un diff unifié ou un concis avant/après. Inclus toujours, quand n'importe quel changement est appliqué :

L'estampille compatibility: et la version de gate de fraîcheur dans SKILL.md mise à jour vers la version du SDK auditée.
Les mises à jour d'eval quand les attentes référencent des APIs changées.

Ne réécris pas les sections voisines exactes. Le rétrécissement de la skill est une proposition valide.

7. Applique ou remets

Par défaut : présente la proposition et arrête-toi pour review.

Avec --apply : applique les édits drift et gap, met à jour les estampilles de version, énumère polish pour review, puis valide — les fichiers JSON parsent, chaque chemin de référence relative dans SKILL.md se résout, et chaque URL docs canonique mappe vers un fichier clerk-docs existant.

Garde-fous

N'invente jamais de surface d'API. Sur les conflits factuels entre docs et source du SDK, sois du côté de la source et écris la skill en conséquence ; énumère la discordance sous « Questions ouvertes » comme un bug probable clerk-docs digne d'être signalé upstream. Seulement l'ambiguïté véritablement prescriptive (la source soutient les deux modèles, docs flou sur lequel recommander) va à la review humaine.
Les snippets doivent rester minimaux (forme d'API et flux de contrôle, pas d'écrans stylisés) et garder leur citation URL docs canonique.
Préserve la structure et la voix de la gate d'exécution de la skill ; les édits s'insèrent dans les sections existantes.
L'interdiction de l'API legacy (Gate : flux basés sur méthode, jamais prepareFirstFactor/setActive pour le nouveau code) ne peut être assouplie que si le SDK lui-même ré-légitime la surface legacy — traite tout tel changement comme une découverte majeure, pas un edit de routine.
N'audit pas contre une copie installée node_modules comme autorité ; elle reflète ce que la dernière installation a tiré, pas la release auditée.
Ne committe pas ; laisse la mise en staging et le commit au mainteneur sauf demande explicite.

Forme de sortie

# audit de skill clerk-expo - <YYYY-MM-DD>

## Résumé
<version estampillée vs version actuelle, entrées changelog révisées, comptages par bucket, plus grande dérive>

## skills/mobile/clerk-expo/SKILL.md
### <section>
- [drift|gap|polish] <description sur une ligne>
  - source: packages/expo/src/<...>:<ligne> (ou docs/<...>.mdx:<ligne>)
  - cible: skills/mobile/clerk-expo/SKILL.md:<ligne>
  - changement: <diff ou concis avant/après>

## skills/mobile/clerk-expo/references/<fichier>.md
...

## skills/mobile/clerk-expo/evals/evals.json
...

## Questions ouvertes
...

Garde le résultat skimmable pour qu'un mainteneur puisse approuver, rejeter, ou appliquer chaque entrée indépendamment.

audit-expo-skill