Skill organisation-documents

Skill maison du domaine comptable. Réception → extraction → validation → classement → indexation → rapport. Détails techniques dans references/ (chargés à la demande, pas à chaque invocation).

Quand utiliser ce skill

Règle d'or : c'est le réflexe par défaut de l'assistant face à tout document entrant. L'assistant ne demande PAS « voulez-vous que je classe cette facture ? » — il classe et il rapporte. Si le comptable doit demander explicitement « utilise le skill », c'est un échec d'invocation.

Déclencheurs :

1. E-mail avec PJ sur gog ou agentmail → traitement immédiat.
2. Dépôt manuel dans l'inbox (Drive ou local) → idem.
3. Import en masse (commande explicite du comptable).
4. Reclassement : correction client/nature → propage le déplacement et met à jour l'index.

Pré-requis automatiques (silencieux, sans poser la question) :

• Si clients.json n'existe pas → le créer vide.
• Nouveau domaine d'expéditeur → fiche client en draft auto-créée (cf. Étape 2).

Ne pas utiliser pour : factures sortantes (→ facturation), FEC (→ fec-parser), relances (→ relances).

Mode d'exécution

Inline only par défaut

Pour 1 à 3 documents (cas standard : 1 e-mail = 1 PJ), exécution inline obligatoire. Pas de subagent, pas de délégation, pas de TaskFlow secondaire. Le subagent rajoute 30-60 s d'overhead inutile et risque le timeout 180 s.

Subagent autorisé uniquement pour import-en-masse (> 10 documents en une fois) — et encore, par batch de 20.

Fast-path : court-circuiter les étapes inutiles

Si l'index global est vide ou ne contient pas le client cible :

• Skipper étape 1 (dédup hash global) → forcément unique.
• Skipper étape 7 (doublons métier) → l'index client est vide.

Si mode = auto ET client identifié dès l'étape 2.a (pas d'auto-création) ET extraction confiance ≥ 0.9 :

• Étapes 4 (validation FR) et 5 (catégorisation) en un seul passage combiné, pas deux.

Time budget

• 1 document inline : ≤ 30 s entre réception et classement.
• Au-delà, dégrader en needs_review + signaler le ralentissement au comptable.

Workflow (10 étapes)

Détails dans references/validation-fr.md (étapes 3, 4, 5, 7), references/contrat-io.md (étapes 1, 9) et references/structure-cible.md (étapes 5, 6).

Étape 2 — Identification du client (cascade + auto-création + escalade)

Tous les documents traités appartiennent à un client connu ou auto-créé. Pas de slug magique pour l'utilisateur lui-même : les frais perso du comptable ne sont pas dans le scope de ce skill. Si la cascade échoue à attribuer, le document part en .pending-attribution/ et l'utilisateur est questionné en fin de batch.

Cascade de détection (ordre de priorité)

1. Adresse e-mail expéditeur matchée contre contact.email d'un client.
2. Domaine de l'expéditeur matché contre domains d'un client.
3. SIREN extrait du document matché contre siren d'un client.
4. Raison sociale fuzzy (Levenshtein ≤ 3) contre raisonSociale d'un client.
5. Auto-création si un signal exploitable existe (cf. ci-dessous).
6. Sinon → .pending-attribution/ : escalade utilisateur en fin de batch.

Auto-création (étape 5)

Par défaut, le skill crée une fiche client en draft et classe normalement, sans demander confirmation. Config flag clientCreation: "confirm" désactive ce comportement : l'auto-création devient une proposition à valider avant exécution.

Slug dérivé du premier signal exploitable, par préférence :

Procédure :

• Insérer dans clients.json : statut: "draft-auto-created", aValider: true, confiance dégradée selon la qualité du signal.
• raisonSociale candidate : extraite du PDF si possible, sinon humanisée depuis le slug.
• Classer normalement dans le dossier nouvellement créé.
• Notifier dans le rapport batch (un seul message en fin de run, pas un par étape).

Cas non attribuable (étape 6)

Signaux insuffisants : expéditeur générique (@gmail.com, @outlook.com, @yahoo.fr) ET aucun SIREN ET aucune raison sociale exploitable → escalade utilisateur.

Procédure :

1. Déplacer le fichier dans ~/.openclaw/workspace/.pending-attribution/ (zone technique, hors clients/).
2. Renommer en <AAAA-MM-JJ-réception>_<hash-court>.<ext> pour la traçabilité.
3. Enregistrer une entrée dans pending-attribution.json avec les bribes extraites (montant, date, émetteur si dispo, sujet email, ID source).
4. En fin de batch, lister tous les pending dans le rapport avec une question explicite (« À quel client rattacher ces N documents ? »).
5. Sur réponse, déplacer vers le chemin cible définitif et purger l'entrée.

Étape 6 — Convention de chemin

Spec exhaustive dans references/structure-cible.md. Résumé ici pour les cas courants.

Arbo cible

clients/<slug>/
├── contrats/                                  # contrats — niveau client, pas mois
│   └── <AAAA-MM-JJ>_<Type>_<Contrepartie>.<ext>
├── <AAAA>/
│   └── <MM>/
│       ├── bank-statements/                   # toujours un dossier (multi-comptes possible)
│       │   └── <AAAA-MM>_<BanqueOuCompte>.<ext>
│       ├── invoices/
│       │   ├── in/                            # achats — factures reçues
│       │   │   └── <AAAA-MM-JJ>_<Émetteur>_<MontantTTC>.<ext>
│       │   └── out/                           # ventes — factures émises
│       │       └── <AAAA-MM-JJ>_<Destinataire>_<MontantTTC>.<ext>
│       ├── notes-de-frais/
│       │   └── <AAAA-MM-JJ>_<Collaborateur>_<Émetteur>_<MontantTTC>.<ext>
│       ├── autres/
│       │   └── <AAAA-MM-JJ>_<Description>.<ext>
│       ├── relances.md                        # maintenu par skill `relances`
│       └── followup.md                        # maintenu par skill `facturation`
├── index.json
└── audit.log

Pourquoi un dossier par mois : c'est le grain de travail du comptable (clôture mensuelle, TVA, rapprochement). L'année est conservée pour la conservation 10 ans.

Pourquoi <slug> dérivé du domaine et pas de l'e-mail :

• 1 client = souvent plusieurs e-mails → on veut un seul dossier.
• @ casse les URLs et passe mal sur certains FS.
• L'email est un attribut de la fiche client, pas l'identifiant du dossier.

Pourquoi invoices/in + invoices/out : un compta ne mélange jamais achats et ventes — TVA, comptes PCG et rapports différents. Coût zéro de séparer dès le classement.

Pourquoi contrats/ au niveau client (pas mois) : un contrat est pluriannuel et lu hors cycle mensuel. Le mettre dans un mois donné l'enterre.

Pourquoi relances.md / followup.md au mois : ce sont les artefacts du cycle de relance courant, lus en début de chaque clôture. Ils ne sont pas produits par ce skill (relances et facturation s'en chargent) mais leur emplacement est imposé ici pour que tous les skills convergent.

Normalisation des composants

• slug : lowercase, accents retirés, espaces → -.
• Émetteur / Destinataire / Collaborateur : 10 premiers caractères significatifs, sans accents ni espaces.
• MontantTTC : sans séparateur de milliers, point décimal, sans symbole.
• AAAA / MM / AAAA-MM-JJ : dérivés de dateEmission du document, pas de la date de réception.

Exemples

clients/acme-sa/2026/04/invoices/in/2026-04-15_OrangePro_348.50.pdf
clients/trendex-tech/2026/03/invoices/in/2026-03-26_Anthropic_21.60.pdf
clients/acme-sa/2026/04/invoices/out/2026-04-01_TrendexTech_2400.00.pdf
clients/acme-sa/2026/04/bank-statements/2026-04_BNP-courant.pdf
clients/acme-sa/2026/04/notes-de-frais/2026-04-12_Marie_SNCF_84.50.pdf
clients/acme-sa/contrats/2024-01-15_MSA_TrendexTech.pdf

Aucun slug réservé dans clients/. Tout dossier sous clients/ correspond à un client réel (existant ou auto-créé en draft-auto-created).

Le parking technique .pending-attribution/ vit hors de clients/, à la racine du workspace :

~/.openclaw/workspace/
├── clients/
│   └── …
└── .pending-attribution/
    ├── 2026-04-29_a7b2c3d4.pdf
    └── pending-attribution.json

Étape 8 — Décision finale

Cascade (première règle qui matche s'applique) :

Calendrier mode par défaut : 14 jours post-onboarding = draft forcé. Après 14 jours + ≥ 80 % de plans validés sans correction → bascule auto.

Le mode auto ne court-circuite jamais la sécurité métier : doublon probable, non conforme, non attribuable, montant incertain → toujours needs_review.

Communication avec le comptable

L'utilisateur est un comptable, pas un développeur. Règles strictes.

Silence par défaut

Pendant le traitement : une ligne au début, une ligne à la fin. Pas de narration par étape.

✅ Bon :

Je traite la facture Anthropic du dernier mail.

(traitement silencieux 10-30 s)

✅ Classée : Trendex Tech / 2026 / Mars / Achats — 21,60 € TTC. Nouveau client, fiche à valider.

❌ Mauvais (ce qui s'est passé au test du 2026-04-29) :

Je vais analyser le mail… Je télécharge la pièce jointe… Je calcule un hash… Je vérifie l'index global… Je lance pdftotext… J'extrais les champs… (10 lignes de plus)

Vocabulaire interdit

pdftotext, nano-pdf, gog, agentmail, taskflow, OCR, regex, mod 97, SHA-256, pipeline, parser, webhook, attachment ID, paths absolus système, IDs JSON internes, scores numériques bruts (« confidence 0.92 »).

Vocabulaire métier

Facture, pièce, dossier client, mois en cours, échéance, classement, doublon, mention obligatoire, conformité, brouillon, à valider.

Format du rapport final

Tableau lisible. Pas de chemins techniques (clients/acme-sa/2026/04/... → « ACME SA / Avril / Achats »). Pas de score numérique (« extraction fiable » / « extraction à vérifier »).

Quand demander une validation

Uniquement : multi-clients ambigus, non-conforme > 1000 €, doublon probable. Tout le reste s'auto-classe avec récap final.

Garde-fous (sécurité, RGPD, secret pro)

• Aucune donnée client ne quitte le container LXD du user. Pas d'OCR cloud sans consentement explicite.
• Logs sans PII : numéroFacture, emetteur, montantTTC, cheminDrive autorisés ; IBAN, contenu textuel, e-mails clients interdits.
• Sources externes en lecture seule : gog et agentmail jamais modifiés. Pas de delete, mark as read, move to folder. Inbox source intacte.
• Conservation 10 ans minimum (art. L123-22 Code de commerce). Skill ne supprime jamais.
• Suppression RGPD : déclenchée uniquement par le comptable. Soft-delete vers <client>/_archive-suppression/ + grâce 30 j.
• Audit trail : chaque déplacement / renommage loggé dans ~/.openclaw/workspace/clients/<slug>/audit.log (UTC + acteur).
• Philosophie : « mieux vaut escalader que mal classer ». En cas de doute → needs_review.

Références complémentaires

• references/structure-cible.md — arbo complète, conventions de nommage, mapping type → dossier, schéma de relances.md et followup.md
• references/contrat-io.md — schémas JSON Input/Output, sources acceptées, enum alerts[], schéma de l'index
• references/validation-fr.md — champs d'extraction, seuils confidence, validations FR détaillées, règles de doublons, données embarquées
• references/roadmap.md — tools (sous-skills), critères de succès, roadmap v0.1→v0.4, questions ouvertes