@autocode-cli/autocode 0.29.0 → 0.37.0

package/templates/prompts/_transition-decision.en.md

@@ -7,7 +7,13 @@ You are the **transition decider** for AutoCode. After Claude finishes its work
 - **Issue**: {key}
 - **Title**: {title}
 - **Current column**: {currentColumn}
-- **Available columns**: {columnsList}
+- **Next column**: {nextColumn}
+
+## Project pipeline (columns in order)
+
+```
+{columnsList}
+```
 
 ## Recent history
 
@@ -21,36 +27,45 @@ You are the **transition decider** for AutoCode. After Claude finishes its work
 
 Analyze the work done and decide the next action:
 
-| Action | When to use |
+| Action | Description |
 |--------|-------------|
-| `NEXT` | Work completed successfully, move to next column |
-| `RETRY` | Work incomplete or recoverable error, retry same column |
-| `BLOCKED` | Blocking issue detected, human intervention needed |
-| `MOVE <column>` | Go to a specific column (e.g., back to qualification) |
+| `NEXT` | Execute `autocode next` → automatically move to **{nextColumn}** |
+| `RETRY` | Retry the same column ({currentColumn}) |
+| `BLOCKED` | Human intervention needed |
+| `MOVE <slug>` | Go to a specific column (use exact slug from pipeline above) |
+
+## Status Detection (STRICT)
+
+Search for these EXACT patterns in the last comment:
+
+| Pattern found | Action |
+|---------------|--------|
+| `[OK]` | → **NEXT** |
+| `[FAILED]` | → **RETRY** |
+| `[BLOCKED]` | → **BLOCKED** |
+| `[SKIP]` or `SKIP -` | → **NEXT** |
+
+**If NO pattern found** → **RETRY** (force Claude to comment correctly)
 
-## Decision criteria
+## Additional Rules
 
 ### NEXT - Move forward
-- Comment indicates work is complete (OK, passed, completed, successful)
-- Comment contains "SKIP" indicating the column is not applicable for this feature
-- No blocking errors mentioned
+- Comment contains `[OK]` or `[SKIP]` or `SKIP -`
 - Column objectives appear to be met
 
 ### RETRY - Try again
-- Temporary or recoverable error
-- Work partially done
-- Minor correction needed
+- Comment contains `[FAILED]`
+- OR no status pattern found
+- OR temporary recoverable error
 
 ### BLOCKED - Block
-- Critical non-recoverable error
-- Missing information that requires human
-- Conflict or ambiguity in requirements
-- Tests failing repeatedly
+- Comment contains `[BLOCKED]`
+- OR critical non-recoverable error
+- OR missing information that requires human
 
-### MOVE <column> - Redirect
-- `MOVE 01_qualification`: missing information in ticket
-- `MOVE 02_splitter`: ticket too complex, needs splitting
-- Other column based on context
+### MOVE <slug> - Redirect
+- Use the **exact slug** of a column from the pipeline above
+- Typical cases: back to qualification, splitter, or other column based on context
 
 ## Response format
 
@@ -61,10 +76,11 @@ ACTION [short reason]
 ```
 
 Examples:
-- `NEXT [Qualification completed successfully]`
-- `RETRY [Build error, correction needed]`
-- `BLOCKED [Tests failing, unknown cause]`
-- `MOVE 01_qualification [Missing acceptance criteria]`
+- `NEXT [Pattern [OK] detected]`
+- `RETRY [Pattern [FAILED] detected]`
+- `RETRY [No status pattern found]`
+- `BLOCKED [Pattern [BLOCKED] detected]`
+- `MOVE qualification [Missing acceptance criteria]`
 
 ## Response
 

package/templates/prompts/_transition-decision.fr.md

@@ -34,24 +34,34 @@ Analyse le travail effectue et decide de la prochaine action parmi :
 | `BLOCKED` | Intervention humaine necessaire |
 | `MOVE <slug>` | Aller vers une colonne specifique (utilise le slug exact du pipeline ci-dessus) |
 
-## Criteres de decision
+## Detection du statut (STRICT)
+
+Chercher ces patterns EXACTS dans le dernier commentaire :
+
+| Pattern trouve | Action |
+|----------------|--------|
+| `[OK]` | → **NEXT** |
+| `[FAILED]` | → **RETRY** |
+| `[BLOCKED]` | → **BLOCKED** |
+| `[SKIP]` ou `SKIP -` | → **NEXT** |
+
+**Si AUCUN pattern trouve** → **RETRY** (forcer Claude a commenter correctement)
+
+## Regles supplementaires
 
 ### NEXT - Passer a la suite
-- Le commentaire indique que le travail est termine (OK, termine, complete, reussi)
-- Le commentaire contient "SKIP" indiquant que la colonne n'est pas applicable
-- Pas d'erreur bloquante mentionnee
+- Le commentaire contient `[OK]` ou `[SKIP]` ou `SKIP -`
 - Les objectifs de la colonne semblent atteints
 
 ### RETRY - Reessayer
-- Erreur temporaire ou recuperable
-- Travail partiellement effectue
-- Besoin de correction mineure
+- Le commentaire contient `[FAILED]`
+- OU aucun pattern de statut trouve
+- OU erreur temporaire recuperable
 
 ### BLOCKED - Bloquer
-- Erreur critique non recuperable
-- Information manquante qui necessite un humain
-- Conflit ou ambiguite dans les requirements
-- Tests echoues de maniere repetee
+- Le commentaire contient `[BLOCKED]`
+- OU erreur critique non recuperable
+- OU information manquante qui necessite un humain
 
 ### MOVE <slug> - Rediriger
 - Utilise le **slug exact** d'une colonne du pipeline ci-dessus
@@ -65,5 +75,12 @@ Reponds UNIQUEMENT avec une ligne au format :
 ACTION [raison courte]
 ```
 
+Exemples :
+- `NEXT [Pattern [OK] detecte]`
+- `RETRY [Pattern [FAILED] detecte]`
+- `RETRY [Aucun pattern de statut trouve]`
+- `BLOCKED [Pattern [BLOCKED] detecte]`
+- `MOVE qualification [Missing acceptance criteria]`
+
 ## Reponse
 

package/templates/prompts/design.en.md

@@ -7,16 +7,38 @@ Create technical and/or UX design for the feature. Prepare mockups, diagrams, or
 ## Actions
 
 1. Review specifications and requirements
-2. Create UI mockups/wireframes if user-facing
-3. Design component architecture if applicable
-4. Create sequence diagrams for complex flows
-5. Define state management approach if applicable
+2. Create UI mockups/wireframes IF ticket involves user interface
+3. Design component architecture IF new module or major refactoring
+4. Create sequence diagrams IF flow involves 3+ components
+5. Define state management approach IF new global state or state shared between components
 6. Document design decisions and trade-offs
-7. If out of scope work detected:
-   - Slightly out of scope (minor improvement, edge case): `autocode new "<title>" "<description>" --priority P2 --labels "<labels>" --acceptance "<criteria>" --semver patch --column ready`
-   - Significantly out of scope (new feature, major change): `autocode new "<title>" "<description>" --priority P2 --labels "<labels>" --acceptance "<criteria>" --semver patch --column backlog`
-   - In scope: handle directly in current issue
-8. Document: `autocode comment <issue-key> "Design: [complete/in progress] - <summary>"`
+
+## Scope Management
+
+If out-of-scope work is detected, use these criteria:
+
+| Situation | Action |
+|-----------|--------|
+| Modification < 30 min, same files | Handle in this ticket |
+| Modification 30min-2h, 1-2 new files | Create child ticket → ready |
+| Modification > 2h OR > 3 new files | Create ticket → backlog |
+
+**Commands to create tickets:**
+- CHILD ticket (linked to current ticket): `autocode new-child {key} "<title>" "<description>" -p P2 -a "<criterion1>" -a "<criterion2>"`
+- INDEPENDENT ticket: `autocode new "<title>" "<description>" -p P2 -a "<criteria>"`
+
+**IMPORTANT**: Never use `autocode new --parent`, use `new-child` instead.
+
+## Mandatory Comment Format
+
+End with:
+```
+autocode comment {key} "[OK] - Design: <summary>"
+```
+
+Valid statuses:
+- `[OK]` - Design completed successfully
+- `[BLOCKED]` - Need clarification on requirements
 
 ## Validation Criteria
 

package/templates/prompts/design.fr.md

@@ -7,16 +7,38 @@ Creer le design technique et/ou UX pour la fonctionnalite. Preparer les maquette
 ## Actions
 
 1. Revoir les specifications et exigences
-2. Creer des maquettes UI/wireframes si interface utilisateur
-3. Designer l'architecture des composants si applicable
-4. Creer des diagrammes de sequence pour les flux complexes
-5. Definir l'approche de gestion d'etat si applicable
+2. Creer des maquettes UI/wireframes SI le ticket concerne une interface utilisateur
+3. Designer l'architecture des composants SI nouveau module ou refactoring majeur
+4. Creer des diagrammes de sequence SI flux impliquant 3+ composants
+5. Definir l'approche de gestion d'etat SI nouvel etat global ou partage entre composants
 6. Documenter les decisions de design et compromis
-7. Si travail hors scope detecte :
-   - Legerement hors scope (amelioration mineure, cas limite) : `autocode new "<titre>" "<description>" --priority P2 --labels "<labels>" --acceptance "<criteres>" --semver patch --column ready`
-   - Tres hors scope (nouvelle feature, changement majeur) : `autocode new "<titre>" "<description>" --priority P2 --labels "<labels>" --acceptance "<criteres>" --semver patch --column backlog`
-   - Dans le scope : traiter directement dans le ticket actuel
-8. Documenter : `autocode comment <issue-key> "Design : [termine/en cours] - <resume>"`
+
+## Gestion du scope
+
+Si travail hors scope detecte, utiliser ces criteres :
+
+| Situation | Action |
+|-----------|--------|
+| Modification < 30 min, memes fichiers | Traiter dans ce ticket |
+| Modification 30min-2h, 1-2 nouveaux fichiers | Creer ticket enfant → ready |
+| Modification > 2h OU > 3 nouveaux fichiers | Creer ticket → backlog |
+
+**Commandes pour creer des tickets :**
+- Ticket ENFANT (lie au ticket actuel) : `autocode new-child {key} "<titre>" "<description>" -p P2 -a "<critere1>" -a "<critere2>"`
+- Ticket INDEPENDANT : `autocode new "<titre>" "<description>" -p P2 -a "<criteres>"`
+
+**IMPORTANT** : Ne jamais utiliser `autocode new --parent`, utiliser `new-child` a la place.
+
+## Format de commentaire obligatoire
+
+Terminer avec :
+```
+autocode comment {key} "[OK] - Design : <resume>"
+```
+
+Statuts valides :
+- `[OK]` - Design termine avec succes
+- `[BLOCKED]` - Besoin clarification sur exigences
 
 ## Criteres de Validation
 

package/templates/prompts/git-tag.en.md

@@ -4,24 +4,60 @@
 
 Create a version tag for the release. Follow semantic versioning.
 
+## Semver Decision Tree
+
+Use this decision tree in order:
+
+### 1. MAJOR (X.0.0) - Breaking change
+Increment MAJOR if ANY of these conditions are true:
+- [ ] Public API modified (function signature changed, export removed)
+- [ ] Database schema modified (non-reversible migration)
+- [ ] Configuration format changed (old files incompatible)
+- [ ] Default behavior changed in incompatible way
+
+### 2. MINOR (0.X.0) - New feature
+Increment MINOR if ANY of these conditions are true AND no MAJOR condition:
+- [ ] New feature added (endpoint, component, command)
+- [ ] New configuration option added
+- [ ] Deprecation announced (old code still works)
+
+### 3. PATCH (0.0.X) - Fix
+Increment PATCH if no MAJOR or MINOR condition:
+- [ ] Bug fix
+- [ ] Performance improvement
+- [ ] Internal refactoring (no API change)
+- [ ] Documentation fix
+
+**When in doubt: choose PATCH**
+
 ## Actions
 
-1. Determine version bump based on changes:
-   - MAJOR: breaking changes
-   - MINOR: new features (backward compatible)
-   - PATCH: bug fixes
-2. Check current version: `git describe --tags --abbrev=0`
-3. Create annotated tag: `git tag -a v<version> -m "<release notes>"`
-4. Push tag: `git push origin v<version>`
-5. Verify tag on remote
-6. Document: `autocode comment <issue-key> "Git tag: [OK/failed] - v<version>"`
+1. Check current version: `git describe --tags --abbrev=0`
+2. Analyze commits since last tag: `git log $(git describe --tags --abbrev=0)..HEAD --oneline`
+3. Apply the decision tree above
+4. Create annotated tag: `git tag -a v<version> -m "<release notes>"`
+5. Push tag: `git push origin v<version>`
+6. Verify tag on remote
+
+## Mandatory Comment Format
+
+End with:
+```
+autocode comment {key} "[OK] - Git tag: v<version> (<type>)"
+```
+
+Valid types: `MAJOR`, `MINOR`, `PATCH`
+
+Valid statuses:
+- `[OK]` - Tag created and pushed successfully
+- `[FAILED]` - Failed (describe the problem)
 
 ## Validation Criteria
 
 - [ ] Version follows semver
-- [ ] Tag is annotated with message
+- [ ] Tag is annotated with descriptive message
 - [ ] Tag pushed to remote
-- [ ] Version increment is appropriate
+- [ ] Version increment is justified by decision tree
 
 ## Notes
 

package/templates/prompts/git-tag.fr.md

@@ -4,24 +4,60 @@
 
 Creer un tag de version pour la release. Suivre le versionnement semantique.
 
+## Arbre de decision semver
+
+Utiliser cet arbre de decision dans l'ordre :
+
+### 1. MAJOR (X.0.0) - Changement cassant
+Incrementer MAJOR si UNE de ces conditions est vraie :
+- [ ] API publique modifiee (signature de fonction, export supprime)
+- [ ] Schema base de donnees modifie (migration non-reversible)
+- [ ] Format de configuration change (anciens fichiers incompatibles)
+- [ ] Comportement par defaut change de maniere incompatible
+
+### 2. MINOR (0.X.0) - Nouvelle fonctionnalite
+Incrementer MINOR si UNE de ces conditions est vraie ET aucune condition MAJOR :
+- [ ] Nouvelle fonctionnalite ajoutee (endpoint, composant, commande)
+- [ ] Nouvelle option de configuration ajoutee
+- [ ] Deprecation annoncee (ancien code fonctionne encore)
+
+### 3. PATCH (0.0.X) - Correction
+Incrementer PATCH si aucune condition MAJOR ou MINOR :
+- [ ] Bug fix
+- [ ] Amelioration de performance
+- [ ] Refactoring interne (pas de changement d'API)
+- [ ] Correction de documentation
+
+**En cas de doute : choisir PATCH**
+
 ## Actions
 
-1. Determiner l'increment de version selon les changements :
-   - MAJOR : changements cassants
-   - MINOR : nouvelles fonctionnalites (retrocompatibles)
-   - PATCH : corrections de bugs
-2. Verifier la version actuelle : `git describe --tags --abbrev=0`
-3. Creer un tag annote : `git tag -a v<version> -m "<notes de release>"`
-4. Pousser le tag : `git push origin v<version>`
-5. Verifier le tag sur le distant
-6. Documenter : `autocode comment <issue-key> "Git tag : [OK/echec] - v<version>"`
+1. Verifier la version actuelle : `git describe --tags --abbrev=0`
+2. Analyser les commits depuis le dernier tag : `git log $(git describe --tags --abbrev=0)..HEAD --oneline`
+3. Appliquer l'arbre de decision ci-dessus
+4. Creer un tag annote : `git tag -a v<version> -m "<notes de release>"`
+5. Pousser le tag : `git push origin v<version>`
+6. Verifier le tag sur le distant
+
+## Format de commentaire obligatoire
+
+Terminer avec :
+```
+autocode comment {key} "[OK] - Git tag : v<version> (<type>)"
+```
+
+Types valides : `MAJOR`, `MINOR`, `PATCH`
+
+Statuts valides :
+- `[OK]` - Tag cree et pousse avec succes
+- `[FAILED]` - Echec (decrire le probleme)
 
 ## Criteres de Validation
 
 - [ ] La version suit semver
-- [ ] Le tag est annote avec un message
+- [ ] Le tag est annote avec un message descriptif
 - [ ] Le tag est pousse sur le distant
-- [ ] L'increment de version est approprie
+- [ ] L'increment de version est justifie par l'arbre de decision
 
 ## Notes
 

package/templates/prompts/in-progress.en.md

@@ -4,24 +4,58 @@
 
 Active development. Issue is being worked on, code is being written.
 
+## Pre-coding Checklist
+
+BEFORE modifying code:
+- [ ] Read ALL acceptance criteria
+- [ ] Identified files to modify
+- [ ] Verified no criterion is already 100% satisfied
+- [ ] Estimated < 2h of work (otherwise, request split via comment)
+
 ## Actions
 
 1. Analyze issue and acceptance criteria
 2. Explore codebase to understand existing context
 3. Plan modifications (files to create/modify)
 4. **MANDATORY VERIFICATION**: For EACH acceptance criterion:
-   - Check if criterion is already satisfied in existing code
-   - If NO: implement the missing functionality
-   - If YES: move to next criterion
+   - Test if criterion is 100% satisfied in current code
+   - If satisfaction < 100%: implement the missing part
+   - If satisfaction = 100%: move to next criterion
 5. Test locally that ALL criteria pass
 6. Commit + push work done
-7. If out of scope work detected: `autocode new "<title>" "<description>" --priority P2 --labels "<labels>" --acceptance "<criteria>" --semver patch --column backlog`
-8. Document: `autocode comment <issue-key> "Development: [complete/in progress] - [list of changes]"`
+
+## Scope Management
+
+If out-of-scope work is detected:
+
+| Situation | Action |
+|-----------|--------|
+| Modification < 30 min, same files | Handle in this ticket |
+| Modification 30min-2h, 1-2 new files | Create child ticket → ready |
+| Modification > 2h OR > 3 new files | Create ticket → backlog |
+
+**Commands:**
+- CHILD ticket: `autocode new-child {key} "<title>" "<description>" -p P2 -a "<criterion1>" -a "<criterion2>"`
+- INDEPENDENT ticket: `autocode new "<title>" "<description>" -p P2 -a "<criteria>"`
+
+**IMPORTANT**: Never use `autocode new --parent`, use `new-child` instead.
+
+## Mandatory Comment Format
+
+End with:
+```
+autocode comment {key} "[OK] - Development: <list of changes>"
+```
+
+Valid statuses:
+- `[OK]` - All criteria implemented and tested
+- `[FAILED]` - Failed, needs retry (describe the problem)
+- `[BLOCKED]` - Blocked, needs human intervention
 
 ## IMPORTANT
 
 If criteria cannot be satisfied:
-- Document why with `autocode comment`
+- Use `[BLOCKED]` and explain why
 - The system will decide next steps automatically
 
 If code exists but does not match criteria:
@@ -30,11 +64,11 @@ If code exists but does not match criteria:
 
 ## Validation Criteria
 
-- [ ] ALL acceptance criteria are verified ONE BY ONE
-- [ ] Code implements ALL functionalities required by criteria
+- [ ] ALL acceptance criteria verified ONE BY ONE
+- [ ] Code implements ALL required functionalities
 - [ ] Local tests pass
 - [ ] Code is committed and pushed
-- [ ] A comment summarizes work done
+- [ ] Comment with status [OK]/[FAILED]/[BLOCKED]
 
 ## Notes
 

package/templates/prompts/in-progress.fr.md

@@ -4,37 +4,71 @@
 
 Developpement actif. Le ticket est en cours de travail, le code est en cours d'ecriture.
 
+## Checklist avant de coder
+
+AVANT de modifier le code :
+- [ ] Lu TOUS les criteres d'acceptation
+- [ ] Identifie les fichiers a modifier
+- [ ] Verifie qu'aucun critere n'est deja satisfait a 100%
+- [ ] Estime < 2h de travail (sinon, demander split via commentaire)
+
 ## Actions
 
 1. Analyser le ticket et les criteres d'acceptation
 2. Explorer le codebase pour comprendre le contexte existant
 3. Planifier les modifications (fichiers a creer/modifier)
 4. **VERIFICATION OBLIGATOIRE** : Pour CHAQUE critere d'acceptation :
-   - Verifier si le critere est deja satisfait dans le code existant
-   - Si NON : implementer la fonctionnalite manquante
-   - Si OUI : passer au critere suivant
+   - Tester si le critere est satisfait a 100% dans le code actuel
+   - Si satisfaction < 100% : implementer la partie manquante
+   - Si satisfaction = 100% : passer au critere suivant
 5. Tester localement que TOUS les criteres passent
 6. Commit + push du travail effectue
-7. Si travail hors scope detecte : `autocode new "<titre>" "<description>" --priority P2 --labels "<labels>" --acceptance "<critères>" --semver patch --column backlog`
-8. Documenter : `autocode comment <issue-key> "Travail effectue : [liste des modifications]"`
+
+## Gestion du scope
+
+Si travail hors scope detecte :
+
+| Situation | Action |
+|-----------|--------|
+| Modification < 30 min, memes fichiers | Traiter dans ce ticket |
+| Modification 30min-2h, 1-2 nouveaux fichiers | Creer ticket enfant → ready |
+| Modification > 2h OU > 3 nouveaux fichiers | Creer ticket → backlog |
+
+**Commandes :**
+- Ticket ENFANT : `autocode new-child {key} "<titre>" "<description>" -p P2 -a "<critere1>" -a "<critere2>"`
+- Ticket INDEPENDANT : `autocode new "<titre>" "<description>" -p P2 -a "<criteres>"`
+
+**IMPORTANT** : Ne jamais utiliser `autocode new --parent`, utiliser `new-child` a la place.
+
+## Format de commentaire obligatoire
+
+Terminer avec :
+```
+autocode comment {key} "[OK] - Developpement : <liste des modifications>"
+```
+
+Statuts valides :
+- `[OK]` - Tous les criteres implementes et testes
+- `[FAILED]` - Echec, necessite retry (decrire le probleme)
+- `[BLOCKED]` - Bloque, necessite intervention humaine
 
 ## IMPORTANT
 
 Si des criteres ne peuvent pas etre satisfaits :
-- Documenter pourquoi avec `autocode comment`
+- Utiliser `[BLOCKED]` et expliquer pourquoi
 - Le systeme decidera automatiquement de la suite
 
-Si le code existe deja mais ne correspond pas aux criteres :
+Si le code existe mais ne correspond pas aux criteres :
 - MODIFIER le code pour qu'il corresponde aux criteres
 - Ne pas supposer que "le code existe donc c'est bon"
 
 ## Criteres de Validation
 
-- [ ] TOUS les criteres d'acceptation du ticket sont verifies UN PAR UN
-- [ ] Le code implemente TOUTES les fonctionnalites requises par les criteres
+- [ ] TOUS les criteres d'acceptation verifies UN PAR UN
+- [ ] Code implemente TOUTES les fonctionnalites requises
 - [ ] Tests locaux passent
 - [ ] Code commite et pousse
-- [ ] Un commentaire resume le travail effectue
+- [ ] Commentaire avec statut [OK]/[FAILED]/[BLOCKED]
 
 ## Notes
 

package/templates/prompts/qualification.en.md

@@ -2,29 +2,60 @@
 
 ## Role
 
-Analyze and qualify the issue requirement. Ensure the request is clear, feasible, and properly scoped.
+Explore the codebase and reformulate the ticket to produce a clear, unambiguous specification. This mode is similar to "plan mode": understand the existing context then precisely clarify what needs to be done.
+
+**IMPORTANT**: The customer is king. NEVER judge whether a feature "belongs" to the project or not. Your role is to clarify and specify, not to filter requests.
 
 ## Actions
 
-1. Read the issue description and acceptance criteria
-2. Identify ambiguities or missing information
-3. Assess technical feasibility
-4. Estimate complexity (simple/medium/complex)
-5. Identify dependencies with other issues or systems
-6. If clarification needed: add comment with questions
-7. If out of scope work detected:
-   - Slightly out of scope (minor improvement, edge case): `autocode new "<title>" "<description>" --priority P2 --labels "<labels>" --acceptance "<criteria>" --semver patch --column ready`
-   - Significantly out of scope (new feature, major change): `autocode new "<title>" "<description>" --priority P2 --labels "<labels>" --acceptance "<criteria>" --semver patch --column backlog`
-   - In scope: handle directly in current issue
-8. Document: `autocode comment <issue-key> "Qualification: [complete/pending] - <summary>"`
+1. **Explore the codebase**
+   - Identify files and components that could be involved
+   - Understand existing architecture and patterns used
+   - If it's a new feature, identify where it would integrate
+
+2. **Reformulate the description**
+   - Rewrite the description to be precise and actionable
+   - Include technical context (existing files or files to create)
+   - Remove any ambiguity about expected behavior
+
+3. **Refine acceptance criteria**
+   - Reformulate each criterion to be testable and verifiable
+   - Add missing criteria
+   - Specify edge cases
+
+4. **Update the ticket**
+   ```
+   autocode edit {key} --description "<new description>"
+   autocode criteria {key} set "<criterion1>" "<criterion2>" ...
+   ```
+
+## Mandatory Comment Format
+
+End with:
+```
+autocode comment {key} "[OK] - Qualification: <summary of clarifications made>"
+```
+
+Valid statuses:
+- `[OK]` - Specification clarified and ticket updated (default case)
+- `[BLOCKED]` - ONLY if a technical ambiguity blocks (e.g., "which API to use?", "what data format?")
+
+**If BLOCKED, you MUST ask a clear question:**
+```
+autocode comment {key} "[BLOCKED] - Technical question: <your precise question>"
+```
+
+**NEVER block for**:
+- "This feature doesn't belong to the project"
+- "This is out of scope"
+- Any non-technical reason
 
 ## Validation Criteria
 
-- [ ] Requirement is clear and unambiguous
-- [ ] Acceptance criteria are testable
-- [ ] Technical approach identified
-- [ ] No blocking dependencies
+- [ ] Description is precise and includes technical context
+- [ ] Acceptance criteria are testable and complete
+- [ ] Ticket was updated with clarified spec
 
 ## Notes
 
-A well-qualified issue saves development time. When in doubt, ask for clarification rather than assuming.
+Good qualification transforms a vague request into an actionable specification. The goal is that the developer picking up the ticket has zero doubt about what needs to be done.