92946d3203
- Created a new tech and AI monitoring report template for weekly updates. - Added an employment and developer trends report template to analyze market conditions. - Updated CLAUDE.md to include new directories for sources and templates. - Introduced a detailed structure for capturing key signals, OKR alignment, and actionable insights.
216 lines
11 KiB
Markdown
216 lines
11 KiB
Markdown
# Mantis Story Ticket Generator - Skill Documentation
|
|
|
|
## Métadonnées du Skill
|
|
|
|
- **Nom:** mantis-ticket
|
|
- **Description:** Generate well-structured Mantis bug tracking tickets in story format from user requirements. Use when the user requests ticket creation, bug report formatting, or needs to transform requirements into Mantis-compatible JSON. Produces narrative-style tickets that are human and AI readable.
|
|
|
|
---
|
|
|
|
# Mantis Story Ticket Generator
|
|
|
|
Generate professional Mantis tickets with a narrative, story-driven style that's easy to understand for both humans and AI.
|
|
|
|
## Output Format
|
|
|
|
Always produce a JSON array containing one or more ticket objects:
|
|
|
|
```json
|
|
[
|
|
{
|
|
"summary": "Clear, action-oriented title",
|
|
"description": "Story-formatted description using Mantis BBCode tags"
|
|
}
|
|
]
|
|
```
|
|
|
|
## Story Writing Principles
|
|
|
|
**Narrative tone**: Write as if explaining the ticket to a colleague, not a robot
|
|
- Use natural language flow
|
|
- Connect ideas with context
|
|
- Explain the "why" not just the "what"
|
|
|
|
**Be concrete and specific**:
|
|
- Avoid vague terms like "improve", "optimize", "enhance"
|
|
- Use real examples and scenarios
|
|
- Include actual values, screens, or user actions when relevant
|
|
|
|
**Structure with purpose**:
|
|
- Each section should tell part of the story
|
|
- Start with context (where are we?)
|
|
- Move to action (what needs to happen?)
|
|
- End with validation (how do we know it's done?)
|
|
|
|
## Mantis BBCode Tags
|
|
|
|
**ONLY use these tags** (Mantis-compatible):
|
|
- `[b]text[/b]` - Bold text
|
|
- `[list][*] item[/list]` - Bullet lists (always use `[*]` inside `[list]`)
|
|
|
|
**NEVER use**: Markdown, HTML, hyphens for lists, asterisks outside `[list]`
|
|
|
|
## Description Structure
|
|
|
|
Use these sections in order (omit non-relevant sections for simple tickets):
|
|
|
|
### [b]Contexte[/b]
|
|
Paint the picture: Where are we? What's the current situation? Why does this matter?
|
|
|
|
Example:
|
|
```
|
|
Actuellement, les utilisateurs doivent copier-coller manuellement les informations d'un email vers Mantis pour créer un ticket. Cette tâche répétitive prend environ 5 minutes par ticket et génère des erreurs de saisie.
|
|
```
|
|
|
|
### [b]À faire[/b]
|
|
What needs to happen? Describe the journey from current to desired state.
|
|
|
|
Use `[list][*]` for action items:
|
|
```
|
|
[list]
|
|
[*] Ajouter un bouton "Créer ticket" dans le ruban Outlook
|
|
[*] Extraire automatiquement le sujet de l'email comme titre du ticket
|
|
[*] Pré-remplir la description avec le corps de l'email
|
|
[/list]
|
|
```
|
|
|
|
### [b]Règles / Détails[/b]
|
|
Important constraints, business rules, or technical details that guide implementation.
|
|
|
|
Example:
|
|
```
|
|
Le bouton doit être visible uniquement quand un email est sélectionné. Si l'email contient des pièces jointes, proposer de les inclure comme screenshots dans le ticket.
|
|
```
|
|
|
|
### [b]Critères de validation[/b]
|
|
How do we know it's done? Describe the success scenario.
|
|
|
|
```
|
|
[list]
|
|
[*] Un utilisateur peut sélectionner un email et cliquer sur "Créer ticket"
|
|
[*] Le ticket apparaît dans Mantis avec le bon projet et les bonnes informations
|
|
[*] Le temps de création passe de 5 minutes à moins de 30 secondes
|
|
[/list]
|
|
```
|
|
|
|
## Content Rules
|
|
|
|
**Ask questions when information is missing**:
|
|
- Title unclear? Ask for a concrete action verb
|
|
- Requirements vague? Request specific examples
|
|
- Multiple unrelated tasks? Confirm if they should be separate tickets
|
|
|
|
**Multiple independent requests**: Generate separate tickets, each with its own summary and description
|
|
|
|
**Keep it concise**:
|
|
- Short, factual sentences
|
|
- No invented information
|
|
- Skip sections that don't add value
|
|
|
|
## What NOT to Do
|
|
|
|
- Never explain your process or add meta-commentary
|
|
- Never include field names like "Projet:" or "Priorité:" in the output
|
|
- Never add sections beyond the four standard ones
|
|
- Never use Markdown syntax or HTML tags
|
|
- Never use hyphens or standalone asterisks for lists
|
|
|
|
---
|
|
|
|
# Exemples de Tickets Mantis en Mode Story
|
|
|
|
Ce document contient des exemples de tickets bien formatés qui illustrent l'approche narrative recommandée.
|
|
|
|
## Exemple 1 : Ticket Simple (Sections Minimales)
|
|
|
|
**User request:** "Il faut ajouter un bouton d'export CSV sur la liste des utilisateurs"
|
|
|
|
```json
|
|
[
|
|
{
|
|
"summary": "Ajouter l'export CSV sur la liste des utilisateurs",
|
|
"description": "[b]Contexte[/b]\nLes administrateurs consultent régulièrement la liste des utilisateurs dans le backoffice pour faire des analyses. Actuellement, ils doivent copier-coller manuellement les données dans Excel, ce qui est fastidieux et source d'erreurs quand il y a plus de 50 utilisateurs.\n\n[b]À faire[/b]\n[list]\n[*] Ajouter un bouton \"Exporter en CSV\" au-dessus du tableau des utilisateurs\n[*] Le fichier CSV doit contenir toutes les colonnes visibles : nom, email, date d'inscription, statut\n[*] Le nom du fichier doit suivre le format : utilisateurs_YYYY-MM-DD.csv\n[/list]\n\n[b]Critères de validation[/b]\n[list]\n[*] Le bouton est visible et cliquable par tous les administrateurs\n[*] Le téléchargement du CSV démarre immédiatement au clic\n[*] Le fichier s'ouvre correctement dans Excel avec l'encodage UTF-8\n[/list]"
|
|
}
|
|
]
|
|
```
|
|
|
|
## Exemple 2 : Ticket Complexe (Toutes les Sections)
|
|
|
|
**User request:** "On a besoin d'améliorer le système de notifications pour les tickets urgents"
|
|
|
|
```json
|
|
[
|
|
{
|
|
"summary": "Implémenter les notifications temps réel pour les tickets urgents",
|
|
"description": "[b]Contexte[/b]\nActuellement, les développeurs ne découvrent les tickets marqués comme \"urgents\" que lorsqu'ils consultent manuellement Mantis. Cela crée des délais de réaction pouvant aller jusqu'à plusieurs heures, ce qui est problématique pour les incidents de production.\n\n[b]À faire[/b]\n[list]\n[*] Envoyer un email immédiat aux développeurs assignés quand un ticket passe en priorité \"urgente\"\n[*] Afficher une notification dans l'interface web Mantis si l'utilisateur est connecté\n[*] Inclure dans la notification : titre du ticket, nom du projet, et lien direct vers le ticket\n[/list]\n\n[b]Règles / Détails[/b]\nLes notifications ne doivent être envoyées que pendant les heures ouvrables (9h-18h du lundi au vendredi). En dehors de ces horaires, les tickets urgents sont mis en file d'attente et les notifications sont envoyées dès 9h le jour ouvrable suivant. Exception : les tickets du projet \"Production\" déclenchent toujours une notification immédiate, même le week-end.\n\n[b]Critères de validation[/b]\n[list]\n[*] Un développeur reçoit l'email dans les 2 minutes suivant le passage en \"urgent\"\n[*] La notification web apparaît instantanément si le développeur est connecté\n[*] Aucune notification n'est envoyée en dehors des heures ouvrables (sauf projet Production)\n[*] Le lien dans l'email mène directement au ticket concerné\n[/list]"
|
|
}
|
|
]
|
|
```
|
|
|
|
## Exemple 3 : Requêtes Multiples (Plusieurs Tickets)
|
|
|
|
**User request:** "Il faut corriger le bug d'affichage des dates et aussi ajouter une recherche par statut"
|
|
|
|
```json
|
|
[
|
|
{
|
|
"summary": "Corriger l'affichage des dates au format FR",
|
|
"description": "[b]Contexte[/b]\nLes dates s'affichent actuellement au format US (MM/DD/YYYY) dans l'interface, ce qui crée de la confusion pour nos utilisateurs français qui attendent le format JJ/MM/AAAA.\n\n[b]À faire[/b]\n[list]\n[*] Modifier le format d'affichage des dates en JJ/MM/AAAA partout dans l'interface\n[*] Vérifier que les dates de création, modification et échéance sont toutes concernées\n[/list]\n\n[b]Critères de validation[/b]\n[list]\n[*] Toutes les dates affichées respectent le format JJ/MM/AAAA\n[*] Le tri par date fonctionne toujours correctement\n[/list]"
|
|
},
|
|
{
|
|
"summary": "Ajouter un filtre de recherche par statut de ticket",
|
|
"description": "[b]Contexte[/b]\nLes utilisateurs doivent actuellement parcourir manuellement la liste complète des tickets pour identifier ceux dans un statut particulier (nouveau, en cours, résolu, etc.). Avec plus de 200 tickets dans certains projets, cette recherche manuelle devient chronophage.\n\n[b]À faire[/b]\n[list]\n[*] Ajouter un menu déroulant \"Filtrer par statut\" au-dessus de la liste des tickets\n[*] Inclure tous les statuts possibles : nouveau, assigné, résolu, fermé, rejeté\n[*] Ajouter une option \"Tous les statuts\" pour désactiver le filtre\n[/list]\n\n[b]Critères de validation[/b]\n[list]\n[*] La sélection d'un statut filtre instantanément la liste affichée\n[*] Le nombre de tickets affichés correspond au statut sélectionné\n[*] Le filtre peut être combiné avec la recherche textuelle existante\n[/list]"
|
|
}
|
|
]
|
|
```
|
|
|
|
## Exemple 4 : Ticket Technique avec Détails Spécifiques
|
|
|
|
**User request:** "L'API REST renvoie une erreur 500 quand on essaie de créer un ticket avec une pièce jointe de plus de 5MB"
|
|
|
|
```json
|
|
[
|
|
{
|
|
"summary": "Gérer les pièces jointes volumineuses dans l'API REST",
|
|
"description": "[b]Contexte[/b]\nL'API REST actuelle de Mantis retourne une erreur 500 (Internal Server Error) lorsqu'un utilisateur tente de créer un ticket avec une pièce jointe supérieure à 5MB. Cette limite n'est documentée nulle part et l'erreur n'est pas explicite, ce qui complique le débogage pour les développeurs qui intègrent l'API.\n\n[b]À faire[/b]\n[list]\n[*] Augmenter la limite de taille des pièces jointes à 20MB dans la configuration du serveur\n[*] Retourner une erreur 413 (Payload Too Large) avec un message explicite si la limite est dépassée\n[*] Documenter cette limite dans la documentation de l'API REST\n[/list]\n\n[b]Règles / Détails[/b]\nLe message d'erreur doit être en JSON et contenir : le code d'erreur (413), un message clair (\"File size exceeds 20MB limit\"), et la taille maximale autorisée. Le header Content-Type doit rester application/json même en cas d'erreur.\n\n[b]Critères de validation[/b]\n[list]\n[*] Les pièces jointes jusqu'à 20MB sont acceptées et attachées correctement au ticket\n[*] Les fichiers > 20MB génèrent une erreur 413 avec un message JSON explicite\n[*] La documentation API mentionne cette limite de 20MB\n[*] Les tests unitaires couvrent les cas limites (19.9MB, 20MB, 20.1MB)\n[/list]"
|
|
}
|
|
]
|
|
```
|
|
|
|
## Bonnes Pratiques Illustrées
|
|
|
|
### Ton Narratif
|
|
❌ **Mauvais** : "Ajouter fonctionnalité export"
|
|
✅ **Bon** : "Les administrateurs consultent régulièrement la liste... ils doivent copier-coller..."
|
|
|
|
### Spécificité
|
|
❌ **Mauvais** : "Améliorer les performances"
|
|
✅ **Bon** : "Réduire le temps de chargement de 3 secondes à moins de 1 seconde"
|
|
|
|
### Contexte Significatif
|
|
❌ **Mauvais** : "Bug d'affichage"
|
|
✅ **Bon** : "Les dates s'affichent au format US, ce qui crée de la confusion pour nos utilisateurs français"
|
|
|
|
### Critères Mesurables
|
|
❌ **Mauvais** : "Ça doit bien fonctionner"
|
|
✅ **Bon** : "Le développeur reçoit l'email dans les 2 minutes", "Le fichier s'ouvre dans Excel"
|
|
|
|
---
|
|
|
|
## Installation du Skill
|
|
|
|
Pour utiliser ce skill dans Claude:
|
|
|
|
1. Créer la structure de dossiers:
|
|
```
|
|
mantis-ticket/
|
|
├── SKILL.md (contenu principal)
|
|
└── references/
|
|
└── examples.md (exemples détaillés)
|
|
```
|
|
|
|
2. Copier le contenu approprié dans chaque fichier
|
|
|
|
3. Packager avec: `scripts/package_skill.py mantis-ticket/`
|
|
|
|
4. Importer le fichier `.skill` généré dans Claude
|