chipsui/guided-portfolio-watch

Compétence Guide de Portefeuille Suivi

Ce que cette compétence construit

Pour tout portefeuille fourni par l'utilisateur, cette compétence produit :

1. MonitoringConfig — un objet JSON structuré écrit dans ALFS, la source unique de vérité pour la liste des tickers, l'horizon, le mode de guidance et la note de préférences.
2. Deux automatismes de flux — gpw-fundamentals (historique financier) et gpw-monitor (analyse quotidienne des événements + alertes push), les deux lisant la configuration à l'exécution.
3. Un Playbook — guided-portfolio-watch, accessible à https://alva.ai/u/{username}/playbooks/guided-portfolio-watch.
4. Alertes quotidiennes — notifications explicatives lors d'événements matériels.

La compétence est réutilisable : modifier config.json et ré-exécuter les flux produit un Playbook et un pipeline d'alertes complets pour tout nouveau portefeuille sans changement de code.

---

Étape 1 — Analyser l'intention de l'utilisateur

Appelez src/intent-to-config.js (ou appliquez sa logique) pour extraire un MonitoringConfig du message de l'utilisateur. Faites-le avant de poser des questions.

Extraction des tickers

Recherchez des séquences de 1 à 5 lettres majuscules ou des motifs comme BRK.B. Acceptez uniquement les actions américaines cotées. Rejetez les ETF, crypto-monnaies (ex. BTC, ETH, SOL), options et tickers non américains — informez l'utilisateur et continuez avec les symboles acceptés.

Liste de blocage des mots courants (rejeter même en majuscules) : I, A, AN, OR, FOR, AND, AT, IN, ON, MY, ME, THE.

Mode de guidance (inférence de préférence — pas une revendication d'expertise)

Appliquez cet ordre de priorité. Arrêtez-vous à la première correspondance.

1. PRÉFÉRENCE EXPLICITE (toujours prioritaire) :
   "en termes simples" / "expliquez-moi" / "je débute dans l'investissement"
   "je ne comprends pas" / "aidez-moi à comprendre" → guidé

   "Je veux des détails techniques" / "considérez que je connais la finance"
   "passez les bases" / "analyse technique" (en tant que préférence) → standard

2. SIGNAUX CONTEXTUELS (uniquement en l'absence de préférence explicite) :
   Utilisation correcte de : EBITDA, FCF, NIM, P/E, points de base, marge nette d'intérêt,
   levier opérationnel, CAGR → standard

   "Dois-je m'inquiéter ?" / "Qu'est-ce que ça signifie pour moi ?" / "Est-ce mauvais ?" → guidé

3. PAR DÉFAUT (signaux mixtes, contradictoires ou absents) :
   → neutre

Ne demandez jamais « Êtes-vous débutant ? » ou « Quel est votre niveau d'expérience ? ». Le mode NEUTRE utilise la mise en page guidée par défaut ; l'utilisateur peut changer via AGENTS.md.

Horizon

• Mots-clés : "long terme", "3–5 ans", "garder pour toujours", "retraite" → long-term
• Mots-clés : "moyen terme", "1–3 ans", "les prochaines années" → medium-term
• Mots-clés : "day trade", "swing trade", "court terme", "< 1 an" → non supporté. Informez l'utilisateur ; demandez si un suivi à long terme est acceptable avant de continuer.
• Par défaut (aucun signal) : long-term.

Classification de propriété

• "Je possède", "j'ai acheté", "ma position", "j'ai" → holding
• "je surveille", "je suis", "garder un œil sur" → watchlist
• Ambigu → holding (défaut plus sûr ; évite de dire à un détenteur qu'il ne possède pas ce titre)

La propriété n'affecte que le langage des alertes. Le pipeline traite tous les symboles de manière identique.

Poids (optionnel)

Analysez les motifs de pourcentage explicites : "50% NVDA, 30% TSLA, 20% AAPL". Si fournis, stockez-les comme objet weights (valeurs 0–1, doivent totaliser 1,0 ± 0,02 ; normalisez si l'écart est dû à l'arrondi). Si non fournis, omettez weights de la configuration.

---

Étape 2 — Clarifier si nécessaire (au maximum une question)

Ne demandez que si la réponse modifie substantiellement ce qui est construit :

Situation	Demander
Aucun ticker fourni	"Quelles entreprises souhaitez-vous suivre ?"
Conflit d'horizon (day trading)	Informer + confirmer que le long terme est acceptable

Ne demandez pas : nombre d'actions, prix de revient, objectifs financiers, niveau d'expérience. Ne posez pas une deuxième question.

---

Étape 3 — Assembler MonitoringConfig

Construisez l'objet MonitoringConfig complet (voir config/monitoring-config.schema.json).

sectorFocusAreas — récupérez les détails de l'entreprise pour chaque ticker via arrays-data-api-equity-fundamentals. Utilisez les champs sector + industry et la table de correspondance dans src/intent-to-config.js pour générer une note d'attention d'une phrase par ticker. Si l'appel API échoue ou que le secteur est inconnu, utilisez le fallback générique : "Surveiller : revenus, bénéfices et développements spécifiques à l'entreprise." N'inventez jamais de domaine d'attention.

preferencesNote — assemblez à partir des champs de configuration en utilisant ce modèle :

L'utilisateur [possède/suit] [LISTE DES TICKERS]. Horizon d'investissement : [HORIZON].

[Si GUIDÉ :] Utilisez un anglais simple, sans jargon. Définissez les termes financiers lorsqu'ils apparaissent pour la première fois.
Cadrez tout autour de ce à quoi l'utilisateur doit prêter attention et pourquoi.
[Si STANDARD :] Supposons une culture financière intermédiaire. Utilisez la terminologie financière standard.
[Si NEUTRE :] Utilisez un langage clair et accessible. Évitez le jargon non expliqué.

Politique d'alerte : Concentrez-vous uniquement sur les développements matériels à long terme.
Exclure : mouvements de prix purs, analyse technique, rumeurs non fondées.
Inclure : changements de résultats/guidance, événements réglementaires/juridiques, annonces stratégiques,
et changements de produits ou de chaîne d'approvisionnement ayant un impact commercial pluriannuel.

[Si des poids sont fournis :] Allocation illustrative : [TICKER] [PCT]%, ... (scénario fourni par l'utilisateur ; non vérifié comme poids actuels.)

[Domaines d'attention par ticker :]
[TICKER] : [sectorFocusArea]
...

[Si des entrées sont inconnues :] Les quantités, les prix de revient et la valeur totale du portefeuille ne sont pas connus. Ne calculez ni n'impliquez de mesures de performance au niveau du portefeuille.

---

Étape 4 — Écrire la configuration dans ALFS

# Sérialiser la config dans un fichier temporaire local, puis l'écrire dans ALFS
alva fs write --path '~/feeds/gpw-monitor/v1/config.json' --file /tmp/gpw-config.json --mkdir-parents

Confirmez que l'écriture a réussi avec :

alva fs read --path '~/feeds/gpw-monitor/v1/config.json'

Écrivez également la configuration dans ~/feeds/gpw-fundamentals/v1/config.json (même contenu — les deux flux lisent leur propre chemin pour rester découplés).

---

Étape 5 — Déployer les flux (nécessite l'approbation de l'utilisateur)

Lisez references/setup-workflow.md avant de déployer. Ne déployez pas avant que l'utilisateur n'ait confirmé que MonitoringConfig est correct.

Flux 1 : gpw-fundamentals (utilisez le modèle templates/gpw-fundamentals.stub.js)

• Cron : 15 6 * * *
• Sortie : fundamentals/snapshot (blob JSON)
• Pas de sortie d'alerte

Flux 2 : gpw-monitor (utilisez le modèle templates/gpw-monitor.stub.js)

• Cron : 30 6 * * *
• Sortie : analysis/decision + alerts/daily (V2 alertOutput)
• Déployer avec --push-notify

---

Étape 6 — Construire et publier le Playbook (nécessite l'approbation de l'utilisateur)

Utilisez le modèle templates/gpw-playbook.stub.html. Remplissez tous les marqueurs [GPW-*]. Suivez le cycle de vie complet : alva lint playbook → alva release playbook-draft → alva release playbook → alva screenshot.

---

Étape 7 — Activer la livraison des alertes (nécessite l'approbation de l'utilisateur)

La publication crée automatiquement une liaison d'alerte FEED pour le propriétaire. Confirmez la livraison :

alva alert history --automation gpw-monitor
# Attendu : au moins une ligne avec statut = "sent"

---

Critères d'acceptation

La compétence est terminée lorsque :

• alva lint playbook passe sans erreurs
• alva screenshot montre des données visibles (pas un cadre vide)
• alva alert history montre une ligne sent dans les 24h suivant une exécution planifiée
• Changer les tickers dans config.json et ré-exécuter gpw-fundamentals produit de nouvelles sections d'entreprise sans aucune référence aux anciens tickers

---

Ce que cette compétence NE construit PAS

• Graphiques de prix ou surveillance intraday des prix
• Recommandations d'achat / vente / conservation
• Calendrier des résultats
• Performance par rapport à un indice de référence
• Exécution d'ordres ou de transactions