RowanJu/subs

subs — Analyseur de dépenses d'abonnement SaaS

Analysez les dépenses récurrentes d'abonnement de l'utilisateur à partir d'exportations CSV de relevés bancaires/cartes et de reçus email. Produisez un résumé des dépenses, signalez le gaspillage, suivez les renouvellements et recommandez des économies.

Le registre est la colonne vertébrale

subscriptions.yaml dans l'espace de travail est la source unique de vérité. Chaque exécution reconcilie les nouvelles données dans ce fichier — il ne dérive jamais tout à partir de zéro. C'est ce qui rend le suivi des renouvellements et la cohérence entre les exécutions réels, et cela rend le "gaspillage" calculable (un abonnement facturé pendant des mois puis soudainement absent = interrompu ou à annuler). Ne jamais écraser le registre en bloc ; reconciliez-y.

Schéma d'une entrée du registre (une entrée par abonnement) :

- vendor: GitHub               # nom canonique
  amount: 4.00                 # dernier montant facturé
  currency: USD
  cycle: monthly               # weekly | monthly | quarterly | semiannual | annual
  category: Dev tools
  first_seen: 2025-01-12       # date ISO de la première facturation connue
  last_seen: 2026-06-03        # date ISO de la facturation la plus récente
  next_renewal: 2026-07-03     # last_seen + un cycle
  status: active               # active | price_hike | lapsed? | cancelled
  notes: "was 4.00 since signup"

Prérequis : un connecteur Gmail

Cette compétence lit les reçus d'abonnement depuis Gmail via un connecteur Gmail / MCP disponible pour votre agent de codage (par exemple le connecteur Gmail de Claude Code). Avant l'étape 1, confirmez que votre agent dispose d'outils de recherche/lecture Gmail (une paire search_threads / get_thread, ou l'équivalent). Si aucune intégration Gmail n'est disponible, arrêtez-vous et demandez à l'utilisateur d'en activer une, puis relancez la compétence. Détails et requêtes dans email-receipts.md.

Processus

Suivez ces étapes dans l'ordre. Ne faites pas de rapport avant l'étape 5.

0. Localiser l'espace de travail

Utilisez le répertoire de travail actuel comme espace de travail. Assurez-vous que data/statements/, data/receipts/ et reports/ existent (créez-les s'ils manquent). Chargez subscriptions.yaml s'il existe ; sinon, considérez le registre comme vide. Terminé quand : les répertoires de l'espace de travail existent et le registre est chargé (éventuellement vide). Si data/statements/ est vide ET aucun subscriptions.yaml n'existe encore ET l'utilisateur n'utilise pas Plaid (section suivante), demandez à l'utilisateur de déposer ses exportations CSV de relevés bancaires/cartes dans data/statements/ et arrêtez-vous — les CSV constituent la base de la détection de récurrence.

1. Rassembler les entrées

Données bancaires via le CLI Plaid (méthode privilégiée — pas d'export CSV manuel) : assurez-vous que le CLI est prêt et récupérez les transactions dans data/statements/plaid-transactions.csv selon plaid.md. Sinon, utilisez les CSV déposés par l'utilisateur dans data/statements/.

Ensuite, listez chaque CSV dans data/statements/. Récupérez les reçus d'abonnement depuis Gmail selon email-receipts.md, et lisez également tous les fichiers supplémentaires .eml/.txt dans data/receipts/. Terminé quand : chaque CSV dans data/statements/ est énuméré, et la recherche de reçus Gmail a abouti (ou l'exécution s'est arrêtée sur un connecteur manquant).

2. Détecter les charges récurrentes

Exécutez le détecteur déterministe sur chaque CSV de relevé (y compris celui dérivé de Plaid) — ne regardez pas les lignes manuellement. <skill-dir> est le propre répertoire de cette compétence (dans Claude Code : ~/.claude/skills/subs/) :

python3 <skill-dir>/scripts/detect_recurring.py data/statements/*.csv

Pour les candidats à low confiance et les cas particuliers de normalisation des marchands, consultez recurrence-detection.md. Combinez ces candidats avec les reçus Gmail rassemblés à l'étape 1 — les reçus permettent de détecter les abonnements annuels qu'un relevé court manque et d'identifier les descripteurs vagues. Terminé quand : chaque candidat récurrent a un marchand, une cadence, un montant et une date de dernière facturation.

3. Reconcilier dans le registre

Reconciliez les candidats dans subscriptions.yaml :

• Nouveau marchand → ajoutez une entrée ; catégorisez selon categories.md.
• Existant → rafraîchissez last_seen et next_renewal ; si le montant a augmenté, définissez status: price_hike et enregistrez l'ancien montant dans notes.
• Présent dans le registre mais absent des données récentes (aucune facturation depuis environ 1,5 cycles par rapport à aujourd'hui) → définissez status: lapsed?.

Terminé quand : le status de chaque entrée du registre est l'un de active | price_hike | lapsed? | cancelled, et chaque candidat correspond à exactement une entrée du registre.

4. Analyser

À partir du registre reconcilié, calculez les quatre éléments suivants :

• (a) Résumé des dépenses — total mensuel et total annualisé, regroupés par catégorie, par fournisseur et par cycle de facturation. Normalisez chaque entrée en un montant mensuel ($/mois) : annuel ÷ 12, semestriel ÷ 6, trimestriel ÷ 3, mensuel × 1, bimensuel × 2,17, hebdomadaire × 4,33, semi-mensuel × 2. Les rapports réutilisent ce $/mois (source unique de vérité).
• (b) Gaspillage — doublons (même service deux fois), outils qui se chevauchent (deux produits dans la même catégorie faisant le même travail), hausses de prix (status: price_hike), et abonnements interrompus/inutilisés (status: lapsed?).
• (c) Renouvellements à venir — entrées dont next_renewal se situe dans les 60 prochains jours, les plus proches en premier.
• (d) Recommandations d'économies — passages annuel vs mensuel, rétrogradations, consolidations et annulations. Chacune doit citer une entrée du registre et un impact financier.

Terminé quand : les quatre éléments sont produits et chaque recommandation cite une entrée et un montant en dollars.

5. Rapporter

Sauvegardez le registre, puis écrivez les deux rapports à partir de celui-ci :

• un rapport Markdown reports/<YYYY-MM-DD>-subscriptions.md selon report-template.md ;
• un tableau de bord HTML autonome reports/<YYYY-MM-DD>-subscriptions.html selon html-report.md, et ouvrez-le (open <chemin>).

Ensuite, présentez un résumé concis dans le chat (totaux principaux + 3 premières actions). Terminé quand : les deux rapports contiennent le résumé des dépenses, les indicateurs de gaspillage, les renouvellements à venir et les recommandations classées, et subscriptions.yaml est sauvegardé.