Aller au contenu

Product highlights (What's New)

Contrat pour lire le catalogue et pousser des ai_proposal. Pas un skill de code — ne pas modifier l'API / le BO sauf demande explicite.

Domaine : docs/index.md. Contrat : internalProductHighlights.endpoint.ts.

Contexte appelant (hors skill)

Le caller précise surtout la cible (dev par défaut). Le reste a des défauts. Overrides optionnels seulement.

Champ Défaut Override caller
Cible dev PROD / production — sans ambiguïté
Mode liste (GET only) « alimente la file » → écrire
Source commits + codebase + Linear + Slack (#app-mobile invest, #feature-refonte-espace-financement PDP) un commit, un brief, PRs develop only
Fenêtre 7 jours de commits (pas publishedAt — date d'affichage BO) dernier commit, 14 jours, N mois = les N derniers mois
Filtre tout le visible user (trop > trop peu) « big topics » / éléments marquants

Mode liste : catalogue seulement. « Alimente la file » = défauts ci-dessus, puis PUT.

Secrets Cloud

Injectés au start du run. Noms = vars. Ne jamais echo / log / commit / coller une clé.

Défaut = dev (*_DEV). PROD seulement si demandé explicitement (« PROD », « en production »). Un « alimente la file » sans cible = dev.

Cible Base URL x-api-key
Dev (défaut) BRICKS_API_URL_DEV AI_AGENT_API_KEY_INTERNAL_DEV
Prod (explicite) BRICKS_API_URL AI_AGENT_API_KEY_INTERNAL

Les credentials prod ne se terminent pas par _DEV. Ne pas suffixer _DEV à la volée, ne pas mixer (clé prod sur URL dev ou l'inverse).

environment-info ne liste pas les secrets. Tester SET/UNSET seulement. UNSET pour la cible choisie → stopper.

Périmètre de la clé

Peut : GET /internal/product-highlights, PUT /internal/product-highlights/proposals.

Ne peut pas : publier, Keep, Skip, supprimer, galerie, isInternalOnly, status. BO App Config : /app-invest/whats-new, /app-pdp/whats-new.

Insert IA : ai_proposal, isInternalOnly=true, gallery=[]. publishedAt = date du commit / merge source (ISO). Absent → now. Keep → draft (conserve publishedAt). Skip → declined (reste au catalogue).

Pile BO : publishedAt croissant — plus ancienne d'abord (carte Keep/Skip = la plus vieille). Timeline publiée : inchangée (récent en haut).

Interdit : /administration/*, /investor/whats-new, /project-owner/whats-new. Staging. Prod sans demande explicite.

Workflow

  1. Lire le contexte appelant. Choisir la cible (dev sauf PROD explicite). Confirmer les deux env de cette cible (SET).
  2. Catalogue — GET les deux scopes (ou celui demandé).
  3. Triage source — titres / sujets. Garder le visible investisseur ou porteur, y compris le feed What's New lui-même (utile en interne). Écarter CI, refactors, BO hors produit. Ne pas filtrer « ça ira en externe ? » — trop > trop peu. Jeter seulement le même incrément déjà au catalogue (même ship, tous statuts) — pas le module entier. Un V2 / rework du même sujet reste candidat. Pas de diffs à cette étape.
  4. Deep dive — candidats seulement. Croiser commits / diff, codebase, Linear, Slack (#app-mobile ou #feature-refonte-espace-financement selon le scope). Rédiger depuis ce que le changement fait, pas le titre de PR. Même copy partout (voir Copy).
  5. Découpage — le sujet prime sur la date. Même sujet en continuité (la feature se complète) → une carte. Même jour / même sprint, deux highlights → deux cartes. V2 / rework / nouvel incrément d’un module déjà shippé → nouvelle carte. publishedAt = merge de cet incrément. Pas d’assemblage hâtif : trop de cartes > trop peu.
  6. Réutiliser l'id d'une ai_proposal ouverte pour reformuler. Ne pas créer un doublon du même incrément. Recalculer publishedAt = date du commit / merge retenu.
  7. Mode alimenter → PUT. Mode liste → stop. Rapporter id + titre + statut. Jamais la clé.

Catalogue — GET

BASE / KEY = paire de la cible (voir Secrets). BASE sans slash.

# Dev (défaut) : BRICKS_API_URL_DEV + AI_AGENT_API_KEY_INTERNAL_DEV
# Prod (explicite) : BRICKS_API_URL + AI_AGENT_API_KEY_INTERNAL
curl -sS -H "x-api-key: $KEY" \
  "$BASE/internal/product-highlights?appScope=investors"
curl -sS -H "x-api-key: $KEY" \
  "$BASE/internal/product-highlights?appScope=pdp"

{ items } : tous statuts, tri publishedAt desc, pas de réactions. publishedAt ≠ fenêtre source.

Copy

Même traitement pour toutes les cartes (investors / pdp). L'IA remonte, le BO trie (isInternalOnly, Keep/Skip). Pas de disclaimer « Note interne ». L'IA ne pose pas isInternalOnly (défaut API true).

Voix : engageante, un cran plus verbeuse. Accroche + contexte (quoi, pour qui, pourquoi c'est là) — pas une puce sèche. « Vous » OK. Pas un pitch com (bénéfice d'abord, superlatifs). Pas un changelog (PR, endpoint, refactor, tickets).

HTML (HtmlContent, pas markdown, pas texte nu) : <p>, <br>, <strong>, <em>, <u>, <ul><li>, <ol><li>, <blockquote>, <a href>. Interdit : images inline. Titre brut ≤120. Quelques emojis OK (titre et/ou corps), pas une frise.

Forme : aérer. 2–3 phrases d'accroche, puis puces si ça aide. Italique pour une nuance. <blockquote> pour un rappel. Pas une liste de labels.

Écriture — PUT

Un PUT par scope. Pas de quota éditorial. Contrat API : max 10 items / PUT — chunker si besoin.

curl -sS -X PUT -H "x-api-key: $KEY" \
  -H "Content-Type: application/json" \
  "$BASE/internal/product-highlights/proposals" \
  -d '{"appScope":"investors","items":[{"title":"…","description":"<p>…</p>","publishedAt":"2026-03-01T10:00:00.000Z"}]}'
  • Sans id → insert ai_proposal.
  • Avec id → update seulement si la row est encore ai_proposal du même scope. id = UUID v7.
  • publishedAt ISO optionnel : date du commit / merge (pas now, pas publishedAt catalogue). Absent → now.
  • Ne pas envoyer status, gallery, isInternalOnly.
  • title 1–120. description 1–4000.

Réponse = rows upsertées seulement.

Erreurs

HTTP Code Action
401 — Clé absente / pas ai-agent. Stopper.
400 validation-body Schema (longueurs, UUID v7, 0 ou >10 items). Corriger le body.
404 highlight-not-found Relire le GET, retirer l'id ou inserer. Pas de retry en boucle.
409 highlight-not-editable Plus ai_proposal ou mauvais scope. Relire le GET, pas de retry en boucle.

Probe : GET $BASE/internal/docs/json → 200 = clé reconnue.

Prompt automation (à coller)

Le prompt d'automation = ce skill + le contexte. Exemple :

Lis et suis `.cursor/skills/product-highlights/SKILL.md`.
Alimente la file. Cible : DEV.
# Overrides optionnels, ex. :
# Cible : PROD
# Fenêtre : 14 jours
# Filtre : big topics only