RowanJu/subs

subs — Analisador de gastos com assinaturas SaaS

Analise os gastos recorrentes do usuário com assinaturas a partir de extratos bancários/cartão de crédito (CSV) e recibos de e-mail. Produza um resumo de gastos, identifique desperdícios, acompanhe renovações e recomende economias.

O ledger é a espinha dorsal

subscriptions.yaml no diretório de trabalho é a fonte única da verdade. Cada execução reconcilia dados novos nele — nunca recria tudo do zero. Isso torna o rastreamento de renovações e a consistência entre execuções reais, e permite calcular "desperdício" (uma assinatura cobrada por meses e de repente ausente = cancelada ou que vale a pena cancelar). Nunca sobrescreva o ledger por completo; reconcilie nele.

Esquema de entrada do ledger (uma entrada por assinatura):

- vendor: GitHub               # nome canônico
  amount: 4.00                 # cobrança mais recente
  currency: USD
  cycle: monthly               # weekly | monthly | quarterly | semiannual | annual
  category: Ferramentas Dev
  first_seen: 2025-01-12       # data ISO da cobrança mais antiga conhecida
  last_seen: 2026-06-03        # data ISO da cobrança mais recente
  next_renewal: 2026-07-03     # last_seen + um ciclo
  status: active               # active | price_hike | lapsed? | cancelled
  notes: "era 4.00 desde o cadastro"

Pré-requisito: um conector Gmail

Esta habilidade lê recibos de assinatura do Gmail através de um conector/MCP Gmail disponível para seu agente de codificação (ex.: conector Gmail do Claude Code). Antes do passo 1, confirme que seu agente tem ferramentas de pesquisa/leitura do Gmail (um par search_threads / get_thread, ou equivalente). Se não houver integração com Gmail disponível, pare e informe o usuário para ativar uma, depois execute novamente a habilidade. Detalhes e consultas em email-receipts.md.

Processo

Execute estas etapas em ordem. Não faça o relatório até a etapa 5.

0. Localizar o diretório de trabalho

Use o diretório de trabalho atual como diretório de trabalho. Garanta que data/statements/, data/receipts/ e reports/ existam (crie-os se estiverem faltando). Carregue subscriptions.yaml se existir; caso contrário, trate o ledger como vazio. Concluído quando: os diretórios de trabalho existem e o ledger está carregado (possivelmente vazio). Se data/statements/ estiver vazio E nenhum subscriptions.yaml existir ainda E o usuário não estiver usando Plaid (próxima seção), informe ao usuário para colocar seus extratos bancários/cartão CSVs em data/statements/ e pare — os CSVs são a espinha dorsal da detecção de recorrência.

1. Coletar entradas

Dados bancários via Plaid CLI (preferencial — sem exportação manual de CSV): certifique-se de que a CLI está pronta e puxe as transações para data/statements/plaid-transactions.csv conforme plaid.md. Caso contrário, use os CSVs que o usuário colocou em data/statements/.

Em seguida, liste cada CSV em data/statements/. Recolha recibos de assinatura do Gmail conforme email-receipts.md, e também leia quaisquer arquivos .eml/.txt suplementares em data/receipts/. Concluído quando: cada CSV em data/statements/ é enumerado, e a pesquisa de recibos do Gmail retornou (ou a execução parou por falta de conector).

2. Detectar cobranças recorrentes

Execute o detector determinístico em cada CSV de extrato (incluindo o derivado do Plaid) — não analise linhas manualmente. <skill-dir> é o diretório desta própria habilidade (no Claude Code: ~/.claude/skills/subs/):

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

Para candidatos com confiança baixa e casos limite de normalização de comerciante, consulte recurrence-detection.md. Combine esses candidatos com os recibos do Gmail coletados na etapa 1 — recibos capturam assinaturas anuais que um extrato curto perde e identificam descritores vagos. Concluído quando: cada candidato recorrente tem um comerciante, cadência, valor e data da última vez visto.

3. Reconciliar no ledger

Reconcilie os candidatos em subscriptions.yaml:

• Novo comerciante → adicione uma entrada; categorize conforme categories.md.
• Existente → atualize last_seen e next_renewal; se o valor aumentou, defina status: price_hike e registre o valor antigo em notes.
• No ledger mas ausente dos dados recentes (sem cobrança dentro de aproximadamente 1,5 ciclos a partir de hoje) → defina status: lapsed?.

Concluído quando: o status de cada entrada do ledger é um dentre active | price_hike | lapsed? | cancelled, e cada candidato mapeia exatamente uma entrada do ledger.

4. Analisar

A partir do ledger reconciliado, calcule todos os quatro:

• (a) Resumo de gastos — total mensal e total anualizado, agrupado por categoria, por fornecedor e por ciclo de cobrança. Normalize cada entrada para um valor mensal ($/mês): anual ÷ 12, semestral ÷ 6, trimestral ÷ 3, mensal × 1, quinzenal × 2,17, semanal × 4,33, bimensal × 2. Os relatórios reutilizam este $/mês (fonte única da verdade).
• (b) Desperdícios — duplicatas (mesmo serviço duas vezes), ferramentas sobrepostas (dois produtos na mesma categoria fazendo o mesmo trabalho), aumentos de preço (status: price_hike) e cancelados/não utilizados (status: lapsed?).
• (c) Próximas renovações — entradas cujo next_renewal cai nos próximos 60 dias, primeiro as mais próximas.
• (d) Recomendações de economia — trocas de anual para mensal, downgrades, consolidações e cancelamentos. Cada uma deve citar uma entrada do ledger e um impacto financeiro.

Concluído quando: todos os quatro são produzidos e cada recomendação cita uma entrada + um valor financeiro.

5. Relatório

Salve o ledger, depois escreva ambos os relatórios a partir dele:

• markdown reports/<YYYY-MM-DD>-subscriptions.md conforme report-template.md;
• um dashboard HTML autocontido reports/<YYYY-MM-DD>-subscriptions.html conforme html-report.md, e abra-o (open <caminho>).

Em seguida, apresente um resumo conciso no chat (totais principais + top 3 ações). Concluído quando: ambos os relatórios contêm o resumo de gastos, flags de desperdício, próximas renovações e recomendações ranqueadas, e subscriptions.yaml está salvo.