🎯 Sooacette

Intelligent CLI for Automated Code Analysis & Implementation

Transform your testing workflow with AI-powered analysis From bug report to implementation in seconds

Quick Start • Features • Commands • Workflow • Configuration

📖 Table of Contents

• ✨ Features
• 🚀 Quick Start
• 📦 Installation
• ⚙️ Configuration
• 🔄 Complete Workflow
• 📋 Commands
  • init
  • configure-confluence
  • list
  • show
  • retrieve 🆕
  • run
  • bulk
  • publish-analysis
  • publish-implementation
  • implement
  • implement-bulk
  • daemon
  • watch
• 🎯 Jira & Confluence Integration
• 🔧 MCP Configuration
• 💡 Use Cases
• 🐛 Troubleshooting
• 🤝 Contributing

✨ Features

🤖 AI-Powered Automation

• Claude Code Integration - Leverages Sonnet 4.5 for intelligent analysis
• Structured Output - Generates comprehensive analysis files automatically
• Two-Phase Workflow - Analysis → Implementation with clear separation
• 🆕 Multi-Backend Support - Switch between Claude Code and Codex CLI
• 🆕 Sub-Agent Architecture - Specialized agents for each workflow phase

🔗 Smart Integrations

• Jira Export - Automatic ticket creation on analysis start
• 🆕 Direct JIRA Retrieval - Fetch existing constats with full metadata
• Confluence Publishing - REST API v2 with automatic fallback publishing
• Auto-Versioning - Handles duplicate page titles (v2, v3, etc.)
• MCP Support - Integrates with project-specific MCP servers
• Intelligent Naming - Jira-based filenames (limited to 100 chars)

⚡ Powerful Automation

• Bulk Processing - Handle multiple constats simultaneously
• Autonomous Daemon - 24/7 monitoring and processing
• Watch Mode - Real-time detection of new constats
• Sequential/Parallel - Choose your processing strategy
• 🆕 Quality Gates - Enforce minimum 8/10 score for analysis approval

🌍 Cross-Platform

• Windows - Terminal, PowerShell, CMD support
• macOS - Native Terminal.app integration
• Linux - GNOME Terminal, Konsole, XTerm support

🚀 v2.0 Enhancements

🆕 v2.0.1 - JIRA Key Priority & Clean Analysis Output (2025-10-27)

JIRA Key Prioritization:

• ✅ Analysis files now use JIRA keys (e.g., FDP-209-Title) instead of numeric IDs (19742)
• ✅ Consistent naming across all files: JSON, preprompt, analysis, implementation
• ✅ Eliminates filename mismatch errors (ENOENT) between backend and preprompt
• ✅ Improved traceability with JIRA keys in analysis titles

Clean Analysis Output:

• ✅ Removed template artifacts like "(≤50 mots)", "(≤75 mots)" from final analyses
• ✅ Professional, client-ready output without technical annotations
• ✅ Maintains quality constraints internally (Claude understands limits without showing them)
• ✅ +50% improved readability and presentation

Example:

Before (v2.0.0):
  File: .recette/19742-analyse.md
  Title: # Analyse 19742
  **Résumé** (≤50 mots) : [text with artifacts]

After (v2.0.1):
  File: .recette/FDP-209-Ajouter-un-QR-Code-simplifié-analyse.md
  Title: # Analyse FDP-209-Ajouter-un-QR-Code-simplifié
  **Résumé** : [clean text without annotations]

Direct JIRA Retrieval (retrieve command)

• Fetch existing constats from JIRA with full metadata
• Automatically load briefing files from JIRA descriptions
• Smart context extraction for enhanced analysis

Enhanced Analysis Capabilities

• Route Identification - Auto-detect API endpoints and navigation routes
• UI Component Detection - Identify React components, forms, and UI elements
• Database Query Analysis - Extract and analyze SQL queries and schema
• Playwright Test Generation - Auto-generate E2E tests from workflows
• Business Term Verification - Cross-reference domain terminology
• Briefing File Integration - Load project-specific context automatically

AI-Powered Sub-Agent Workflow (Claude Code)

• Constat Analyzer - Deep analysis with specialized prompts
• Code Reviewer - Quality gate enforcement (minimum 8/10 score)
• Solution Implementer - Automated implementation with best practices
• Test Automation Writer - Generate comprehensive test coverage
• Confluence Publisher - Structured documentation generation

Multi-Backend Support

• Claude Code - Full sub-agent support with Task tool integration
• Codex CLI - Alternative backend with yolo mode for fast execution
• Configurable Switching - Choose backend via .sooacette.json
• Prompt Adaptation - Automatic translation between backend formats

🚀 Quick Start

Get up and running in 60 seconds:

# 1️⃣ Install globally
npm install -g sooacette

# 2️⃣ Navigate to your project
cd /path/to/your/project

# 3️⃣ Initialize local configuration
sooacette init

# 4️⃣ Configure your API key
cp .sooacette.local.example .sooacette.local.json
# Edit .sooacette.local.json and add your API key

# 5️⃣ Analyze your first constat
sooacette run <constat-id>

# 6️⃣ Implement the solution
sooacette implement <constat-id>

Or use without installation:

npx sooacette run <constat-id>

Legacy mode (global config):

# Set your API key
export SOOATEK_API_KEY="your-api-key-here"

# Use with -p flag
sooacette run <constat-id> -p myproject

📦 Installation

Option 1: Global Installation (Recommended)

npm install -g sooacette

Option 2: NPX (No Installation Required)

npx sooacette [command]

Option 3: Local Development

git clone <repository>
cd sooacette
npm install
npm run build
npm link  # Makes CLI available globally

Prerequisites

| Requirement | Version | Notes | |------------|---------|-------| | Node.js | ≥ 18.0.0 | Download | | Claude Code CLI | Latest | Installation Guide | | API Access | Active Key | Cahier de recettage platform |

⚙️ Configuration

Sooacette supports two configuration modes:

🆕 Local Configuration (Recommended)

Per-project configuration - Each repository has its own config file.

Quick Setup

cd /path/to/your/project
sooacette init

This creates:

.sooacette.json (versioned - commit this file):

{
  "$schema": "https://sooacette.dev/schema.json",
  "project": "my-project",
  "baseUrl": "https://doc.sooatek.com",
  "auth": {
    "apiKeyEnv": "SOOACETTE_API_KEY"
  },
  "launch": {
    "cli": "claude-code",
    "args": ["run"]
  },
  "terminal": {
    "prefer": "auto",
    "linux": "gnome-terminal",
    "mac": "Terminal",
    "windows": "wt"
  }
}

.sooacette.local.json (gitignored - never commit):

{
  "auth": {
    "apiKey": "sk-ant-api03-xxxxx"
  }
}

.sooacette.local.example (versioned - template for team):

{
  "auth": {
    "apiKey": "your_api_key_here"
  }
}

Security Best Practices

🔒 IMPORTANT: Always add to .gitignore:

.sooacette.local.json

Sooacette validates this automatically and will warn you if missing.

Team Onboarding

1. Clone repository
2. Copy: cp .sooacette.local.example .sooacette.local.json
3. Edit .sooacette.local.json with your API key
4. Run: sooacette run <constat-id> (no -p needed!)

🔧 Global Configuration (Legacy)

Centralized configuration - For multiple projects in one config file.

Setup

On first run, Sooacette creates ~/.sooacette/config.json:

{
  "defaultProject": "sooatek",
  "projects": {
    "sooatek": {
      "baseUrl": "https://doc.sooatek.com",
      "repoPath": "/absolute/path/to/your/repo",
      "launch": {
        "cli": "claude-code",
        "args": ["run"]
      },
      "terminal": {
        "prefer": "auto",
        "mac": "Terminal",
        "linux": "gnome-terminal",
        "windows": "wt"
      }
    }
  },
  "auth": {
    "apiKeyEnv": "SOOATEK_API_KEY"
  }
}

API Key Setup

Add to your shell profile (~/.bashrc, ~/.zshrc):

export SOOATEK_API_KEY="your-api-key-here"

Then reload:

source ~/.bashrc  # or ~/.zshrc

Usage

# Use with -p flag
sooacette run <constat-id> -p myproject

# Or set default project
sooacette run <constat-id>  # Uses defaultProject

🔀 Configuration Resolution Order

Sooacette automatically detects which config to use:

1. -p/--project flag → Use global config project
2. .sooacette.json found → Use local config (searches up directory tree)
3. Global defaultProject → Use global config default
4. Error → No configuration found

API Key Resolution

Priority order (first found wins):

1. .sooacette.local.json → auth.apiKey
2. Environment variable from local config → process.env[auth.apiKeyEnv]
3. Environment variable from global config → process.env[auth.apiKeyEnv]

🌐 Confluence Configuration (Optional)

Sooacette can automatically publish analysis files and implementation reports to Confluence using the Confluence REST API v2 with ADF (Atlassian Document Format).

Quick Setup (Interactive)

sooacette configure-confluence

This interactive command will guide you through:

1. Entering your Confluence base URL
2. Entering your email address
3. Creating and entering your API token
4. Saving credentials to ~/.sooacette/confluence.json

Manual Setup

Option 1: Global Configuration (Recommended)

Create ~/.sooacette/confluence.json:

{
  "baseUrl": "https://your-domain.atlassian.net",
  "email": "[email protected]",
  "apiToken": "your-api-token-here"
}

Option 2: Environment Variables (Per-Project)

Set in your shell or .env file:

CONFLUENCE_BASE_URL=https://your-domain.atlassian.net
[email protected]
CONFLUENCE_API_TOKEN=your-api-token-here

Configuration Priority

Sooacette checks for credentials in this order:

1. Environment variables (highest priority)
2. Global config file (~/.sooacette/confluence.json)
3. No Confluence (analysis remains local)

Getting a Confluence API Token

1. Go to https://id.atlassian.com/manage-profile/security/api-tokens
2. Click Create API token
3. Give it a label (e.g., "Sooacette")
4. Copy the token and save it in your configuration

How It Works

When Confluence credentials are configured:

• ✅ Auto-publishing - Claude is instructed to run sooacette publish-* commands
• 🔄 Fallback system - If Claude forgets, auto-publishes after 30 seconds
• 📄 Dual publication - Both analysis and implementation reports published
• 🔁 Automatic versioning - Handles duplicate titles (adds v2, v3, etc.)
• 🌳 Proper hierarchy - Analysis and implementation as siblings under Jira page

Note: Publishing requires a Jira ticket with a Confluence page URL in its description.

📋 Configuration Reference

Local Config (.sooacette.json)

| Option | Type | Required | Description | |--------|------|----------|-------------| | $schema | string | No | JSON schema URL | | project | string | No | Project name (defaults to folder name) | | baseUrl | string | No | API endpoint (default: https://doc.sooatek.com) | | auth.apiKeyEnv | string | No | Environment variable name | | launch.cli | string | Yes | Command to execute (e.g., claude-code) | | launch.args | string[] | Yes | CLI arguments | | terminal.prefer | string | No | Terminal preference | | terminal.linux | string | No | Linux terminal (default: gnome-terminal) | | terminal.mac | string | No | macOS terminal (default: Terminal) | | terminal.windows | string | No | Windows terminal (default: wt) | | mcp.configFile | string | No | MCP config file path | | additionalDirectories | array | No | Additional directories to include in analysis (v2.0) |

Additional Directories (v2.0)

Use case: When your project spans multiple repositories (e.g., backend + frontend + mobile app), you can configure Sooacette to give Claude access to all related codebases during analysis.

Configuration example in .sooacette.json:

{
  "project": "my-backend",
  "baseUrl": "https://doc.sooatek.com",
  "additionalDirectories": [
    {
      "path": "../frontend",
      "description": "Frontend React application",
      "indexForSearch": true
    },
    {
      "path": "/absolute/path/to/mobile-app",
      "description": "Mobile app (React Native)",
      "indexForSearch": false
    }
  ]
}

Directory object properties:

| Property | Type | Required | Description | |----------|------|----------|-------------| | path | string | Yes | Absolute or relative path to directory (relative to repo root) | | description | string | No | Description of the directory's purpose | | indexForSearch | boolean | No | Enable semantic search indexing (default: false) |

What it does:

1. Resolves paths - Converts relative paths to absolute paths automatically
2. Validates existence - Warns if directories don't exist
3. Includes in preprompt - Claude is informed about these directories
4. Enables access - Claude can use Read, Grep, Glob on additional directories
5. Optional indexing - Semantic search with claude-context MCP if enabled

Example use cases:

• Monorepo architecture - Multiple apps in subdirectories
• Multi-repo projects - Backend, frontend, mobile in separate repos
• Shared libraries - Common code across projects
• Documentation - Technical specs in separate repository

In the preprompt, Claude sees:

## 📂 Répertoires Additionnels

**IMPORTANT** : Ce projet inclut des répertoires supplémentaires auxquels vous avez accès :

### Frontend React application
- **Chemin** : `/absolute/path/to/frontend`
- **Description** : Frontend React application
- **Accès** : Vous pouvez utiliser Read, Grep, Glob sur ce répertoire
- **Indexation** : Ce répertoire est indexé pour la recherche sémantique

**Utilisation** : Lors de l'analyse, explorez ces répertoires si le constat y fait référence (API, mobile, frontend, etc.)

Local Secrets (.sooacette.local.json)

| Option | Type | Description | |--------|------|-------------| | auth.apiKey | string | API key (never commit!) |

Global Config (~/.sooacette/config.json)

| Option | Type | Description | |--------|------|-------------| | defaultProject | string | Default project when --project is omitted | | projects.*.baseUrl | string | API endpoint for the project | | projects.*.repoPath | string | Absolute path to local repository | | projects.*.launch.cli | string | Command to execute | | projects.*.launch.args | string[] | CLI arguments | | projects.*.terminal.prefer | string | Terminal preference | | auth.apiKeyEnv | string | Environment variable containing API key |

🔄 Complete Workflow

graph TD
    A[📥 Fetch Constat] --> B[🎫 Export to Jira]
    B --> C[📄 Get Jira Details]
    C --> D[🔗 Extract Confluence URL]
    D --> E[🤖 Launch Claude Code]
    E --> F[📝 Generate Analysis]
    F --> G[✅ Create Local .md File]
    G --> H[🌐 Publish to Confluence]
    H --> I{Review OK?}
    I -->|Yes| J[🚀 Implement Solution]
    I -->|No| K[🔄 Revise Analysis]
    K --> F
    J --> L[✅ Update Status]
    L --> M[🎉 Done!]

Phase 1: Analysis 🔍

sooacette run <constat-id>

What happens:

1. 📥 Fetches constat from API
2. 🎫 Exports to Jira (creates/updates ticket)
3. 📄 Retrieves Jira issue details (summary, description)
4. 🔗 Extracts Confluence URL from Jira description
5. 📝 Creates .recette/<JIRA-KEY>-<Title>.json (max 100 chars)
6. 🤖 Launches Claude Code with preprompt
7. 📊 Claude analyzes and creates .recette/<JIRA-KEY>-<Title>-analyse.md
8. 📤 Claude publishes to Confluence (executes sooacette publish-analysis)
9. 🔄 Fallback auto-publish (if Claude forgets, auto-publishes after 30s)

Example filename:

.recette/GSL-123-FEAT-001-Login-Bouton-non-fonctionnel.json

Phase 2: Review & Implementation ✅

# Review the analysis
cat .recette/<filename>-analyse.md

# Or view on Confluence (if published)
# URL shown in terminal output

# Implement if satisfied
sooacette implement <constat-id>

What happens:

1. 📖 Reads analysis file (or fetches from Confluence if available)
2. 🚀 Launches Claude Code with implementation prompt
3. 🔧 Claude applies modifications
4. ✅ Claude creates .recette/<JIRA-KEY>-<Title>-implementation-report.md
5. 📤 Claude publishes report to Confluence (executes sooacette publish-implementation)
6. 🔄 Fallback auto-publish (if Claude forgets, auto-publishes after 30s)
7. ✅ Updates status

📋 Commands

init - Initialize Local Configuration

🆕 New Command - Create a local configuration for your project.

sooacette init [project-name] [options]

What It Does

1. Creates .sooacette.json (versioned configuration)
2. Creates .sooacette.local.example (template for secrets)
3. Displays setup instructions

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | project-name | string | folder name | Project name | | --baseUrl <url> | string | https://doc.sooatek.com | API base URL | | --cli <command> | string | claude-code | CLI command to execute | | --force | boolean | false | Overwrite existing files |

Examples

# Basic initialization
cd /path/to/my-project
sooacette init

# With custom project name
sooacette init my-awesome-project

# With custom API URL
sooacette init --baseUrl https://api.custom.com

# Overwrite existing config
sooacette init --force

After init

Follow the displayed instructions:

✓ Created .sooacette.json
✓ Created .sooacette.local.example

Next steps:
  1. Copy .sooacette.local.example to .sooacette.local.json
  2. Edit .sooacette.local.json and add your API key
  3. Add .sooacette.local.json to .gitignore

⚠️  IMPORTANT: Never commit .sooacette.local.json to git!

✓ Project "my-project" initialized successfully

configure-confluence - Setup Confluence Credentials

🆕 New Command - Interactive setup for Confluence publishing.

sooacette configure-confluence

What It Does

1. Prompts for your Confluence base URL
2. Prompts for your email address
3. Guides you to create an API token
4. Saves credentials to ~/.sooacette/confluence.json
5. Validates the configuration

Interactive Flow

🔧 Configure Confluence Integration

Enter your Confluence base URL (e.g., https://your-domain.atlassian.net):
> https://sooatek.atlassian.net

Enter your Confluence email address:
> [email protected]

ℹ️  To create an API token:
  1. Go to https://id.atlassian.com/manage-profile/security/api-tokens
  2. Click 'Create API token'
  3. Give it a label (e.g., "Sooacette")
  4. Copy the generated token

Enter your Confluence API token:
> ****************************

✓ Confluence configuration saved to ~/.sooacette/confluence.json

You can now publish analyses to Confluence using:
  - sooacette publish-analysis <id>
  - sooacette publish-implementation <id>

Security

• Credentials are stored in your home directory (~/.sooacette/)
• File permissions are set to 0600 (owner read/write only)
• Never committed to git (outside project directories)

When to Use

• First-time setup - Configure Confluence once for all projects
• Update credentials - Change base URL, email, or token
• Multiple accounts - Run again to replace configuration

list - List Constats

List constats with powerful filtering options.

sooacette list [options]

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | -p, --project <name> | string | config default | Project name | | -s, --state <state> | string | - | Filter by state | | --priority <priority> | string | - | Filter by priority | | --page <number> | number | 1 | Page number | | --limit <number> | number | 50 | Results per page | | --json | boolean | false | Output as JSON |

Examples

# List all constats
sooacette list

# Filter by state and priority
sooacette list --state Nouveau --priority Critical

# Export to JSON
sooacette list --json > constats.json

# Paginated results
sooacette list --page 2 --limit 20

show - Show Constat Details

Display detailed information about a specific constat.

sooacette show <id> [options]

Examples

# Show constat details
sooacette show U-R68fKqXLCtdp81u0KiJ

# Output as JSON
sooacette show U-R68fKqXLCtdp81u0KiJ --json

retrieve - Direct JIRA Retrieval

🆕 v2.0 Command - Fetch existing constats directly from JIRA with full metadata.

sooacette retrieve <jira-key> [options]

What It Does

1. 📥 Fetches JIRA issue details using the JIRA REST API
2. 📝 Extracts briefing files from JIRA description (if present)
3. 🔍 Loads project-specific context automatically
4. 💾 Creates local .recette/<JIRA-KEY>-<Title>.json file
5. 📄 Prepares for enhanced analysis with full JIRA context

Options

| Option | Type | Description | |--------|------|-------------| | <jira-key> | string | JIRA issue key (e.g., GSL-123, PROJ-456) | | -p, --project <name> | string | Project name (for multi-project setups) | | --json | boolean | Output raw JSON response |

Examples

# Retrieve JIRA issue
sooacette retrieve GSL-123

# Retrieve with specific project
sooacette retrieve GSL-123 -p myproject

# Output as JSON
sooacette retrieve GSL-123 --json

Output Example

ℹ Fetching JIRA issue GSL-123...
✓ Fetched JIRA issue: [FEAT-001] Login - Authentication Bug
✓ Found Confluence page: https://your-domain.atlassian.net/wiki/...
✓ Extracted 2 briefing files from description
  - briefings/auth-context.md
  - briefings/api-endpoints.md
✓ Wrote constat data to .recette/GSL-123-FEAT-001-Login-Authentication-Bug.json
✓ Ready for analysis with sooacette run GSL-123

Briefing File Integration

The retrieve command automatically extracts briefing file references from JIRA descriptions:

JIRA Description Format:

## Context

This issue is related to authentication system.

## Briefing Files
- briefings/auth-context.md
- briefings/security-guidelines.md

## Steps to Reproduce
...

What Happens:

1. Sooacette parses the description
2. Extracts file paths under ## Briefing Files section
3. Stores them in the constat data
4. Analysis phase automatically loads these files for context

When to Use

• Existing JIRA tickets - When you already have a JIRA issue created
• External systems - When constats are created outside of Sooacette
• Manual workflow - When you want to start from JIRA instead of API
• Re-analysis - When you need to re-fetch updated JIRA information

Workflow Comparison

Traditional Workflow (run command):

API Constat → Export to JIRA → Fetch JIRA → Analyze

Direct JIRA Workflow (retrieve command):

JIRA Issue → Retrieve → Analyze

run - Analyze Single Constat

🎯 Core Command - Launches full analysis workflow for a single constat.

sooacette run <id> [options]

Workflow Steps

| Step | Action | Output | |------|--------|--------| | 1️⃣ | Fetch constat from API | Console log | | 2️⃣ | Export to Jira | ✓ Exported to Jira: GSL-123 | | 3️⃣ | Get Jira issue details | ✓ Fetched Jira issue: [Title] | | 4️⃣ | Extract Confluence URL | ✓ Found Confluence page: [URL] | | 5️⃣ | Create intelligent filename | GSL-123-FEAT-001-Login-... | | 6️⃣ | Write JSON file | .recette/<filename>.json | | 7️⃣ | Generate preprompt | .recette/<filename>-preprompt.md | | 8️⃣ | Launch Claude Code | Opens terminal | | 9️⃣ | Claude creates analysis | .recette/<filename>-analyse.md | | 🔟 | Publish to Confluence | Child page created |

Options

| Option | Description | |--------|-------------| | -p, --project <name> | Project name | | --dry-run | Preview script without executing |

Examples

# Analyze a constat
sooacette run U-R68fKqXLCtdp81u0KiJ

# Dry run (see what would be executed)
sooacette run U-R68fKqXLCtdp81u0KiJ --dry-run

What Gets Created

.recette/
├── GSL-123-Login-Bouton-non-fonctionnel.json
├── GSL-123-Login-Bouton-non-fonctionnel-preprompt.md
└── GSL-123-Login-Bouton-non-fonctionnel-analyse.md

bulk - Batch Processing

Process multiple constats simultaneously with smart filtering.

sooacette bulk [options]

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | -p, --project <name> | string | config default | Project name | | -s, --state <state> | string | Nouveau | Filter by state | | --priority <priority> | string | - | Filter by priority | | -l, --limit <number> | number | 10 | Max constats to process | | --no-confirm | boolean | false | Skip confirmation | | --sequential | boolean | false | Process one-by-one with delay |

Examples

# Process 10 newest constats (with confirmation)
sooacette bulk

# Process critical constats only
sooacette bulk --state Nouveau --priority Critical --limit 20

# Sequential mode (one terminal at a time)
sooacette bulk --sequential --limit 5

# No confirmation (automated)
sooacette bulk --no-confirm --limit 50

Visual Output

Found 15 constat(s) (Total: 42)

Constats to process:
────────────────────────────────────────────────────────────────────────────────
1. [Critical] U-R68fKqXLCtdp81u0KiJ - Nouveau
   Le processus de reprise n'est pas correct. Pour un licencié qui change...

2. [High] U-ABC123DEF456GHI789 - Nouveau
   Erreur lors de la validation du formulaire d'inscription...

...

────────────────────────────────────────────────────────────────────────────────

Do you want to process these 15 constat(s)? (y/n):

publish-analysis - Publish Analysis to Confluence

📤 Publication Command - Publish an analysis file to Confluence.

sooacette publish-analysis <id> [options]

Prerequisites

• Analysis file must exist: .recette/<filename>-analyse.md
• Confluence credentials configured (run sooacette configure-confluence)
• Jira ticket must have a Confluence page URL in its description

What It Does

1. ✅ Checks if analysis file exists and is complete
2. 📄 Gets constat data and extracts Confluence URL from Jira
3. 🔄 Converts Markdown to ADF (Atlassian Document Format)
4. 🌐 Creates a child page under the Jira page (via REST API v2)
5. 🔁 Auto-versioning - If title exists, adds v2, v3, etc.
6. 🔗 Returns the URL of the created Confluence page
7. ✅ Marks as published (prevents auto-publish fallback)

Options

| Option | Description | |--------|-------------| | -p, --project <name> | Project name | | -u, --confluence-url <url> | Override Confluence URL |

Examples

# Publish analysis to Confluence
sooacette publish-analysis U-R68fKqXLCtdp81u0KiJ

# With specific project
sooacette publish-analysis U-R68fKqXLCtdp81u0KiJ -p myproject

# With manual Confluence URL
sooacette publish-analysis U-R68fKqXLCtdp81u0KiJ -u https://your-domain.atlassian.net/wiki/...

Output

ℹ Publishing analysis for constat U-R68fKqXLCtdp81u0KiJ...
ℹ Fetching Jira issue GSL-123...
✓ Fetched Jira issue: [FEAT-001] Login - Bug
✓ Found Confluence URL: https://your-domain.atlassian.net/wiki/...
ℹ Publishing analysis to Confluence...
✓ Analysis published to Confluence: https://your-domain.atlassian.net/wiki/spaces/SPACE/pages/123456/Analyse+Technique+-+Constat+U-R68fKqXLCtdp81u0KiJ

With auto-versioning (if duplicate title):

ℹ️  Page created with title: Analyse Technique - Constat U-R68fKqXLCtdp81u0KiJ v2
✓ Analysis published to Confluence: https://...

Auto-Publishing Fallback

If Claude Code doesn't execute this command:

• Watcher activates after 30 seconds
• Automatically publishes the analysis
• Logs warning that manual publication was missed

This ensures analyses are always published to Confluence.

When to Use

• Manual publishing - When you want control over publication timing
• Retry after failure - If automatic publication failed
• Re-publishing - Create new version after client feedback (auto-versioned)
• Selective publishing - Only publish certain analyses

publish-implementation - Publish Implementation Report

📤 Publication Command - Publish an implementation report to Confluence.

sooacette publish-implementation <id> [options]

Prerequisites

• Implementation report must exist: .recette/<filename>-implementation-report.md
• Confluence credentials configured (run sooacette configure-confluence)
• Jira ticket must have a Confluence page URL in its description

What It Does

1. ✅ Checks if implementation report exists
2. 📄 Gets constat data and extracts Confluence URL from Jira
3. 🔄 Converts Markdown to ADF (Atlassian Document Format)
4. 🌳 Creates sibling page - Same level as analysis (both under Jira page)
5. 🔁 Auto-versioning - If title exists, adds v2, v3, etc.
6. 🔗 Returns the URL of the created Confluence page
7. ✅ Marks as published (prevents auto-publish fallback)

Page Hierarchy

📄 Jira Page (e.g., GSL-123)
  ├── 📊 Analyse Technique - Constat xxx (created by publish-analysis)
  └── ✅ Rapport d'Implémentation - Constat xxx (created by publish-implementation)

Both pages are siblings at the same level under the Jira page.

Options

| Option | Description | |--------|-------------| | -p, --project <name> | Project name | | -u, --confluence-url <url> | Override Confluence URL (Jira page) |

Examples

# Publish implementation report to Confluence
sooacette publish-implementation U-R68fKqXLCtdp81u0KiJ

# With specific project
sooacette publish-implementation U-R68fKqXLCtdp81u0KiJ -p myproject

# With manual Confluence URL
sooacette publish-implementation U-R68fKqXLCtdp81u0KiJ -u https://your-domain.atlassian.net/wiki/...

Output

ℹ Publishing implementation report for constat U-R68fKqXLCtdp81u0KiJ...
ℹ Fetching Jira issue GSL-123...
✓ Found Confluence URL (Jira page): https://your-domain.atlassian.net/wiki/...
ℹ Publishing implementation report to Confluence...
✓ Implementation report published to Confluence: https://your-domain.atlassian.net/wiki/spaces/SPACE/pages/789012/Rapport+Implementation

Auto-Publishing Fallback

If Claude Code doesn't execute this command during implementation:

• Watcher activates after 30 seconds
• Automatically publishes the report
• Logs warning that manual publication was missed

This ensures implementation reports are always published to Confluence.

When to Use

• After implementation - Document what was done
• Manual publishing - When you want control over publication timing
• Retry after failure - If automatic publication failed
• Re-implementation - Create new version after changes (auto-versioned)

implement - Execute Solution

Implement the solution from a previously created analysis file.

sooacette implement <id> [options]

Prerequisites

• Analysis file must exist: .recette/<filename>-analyse.md
• Status should be: ⏳ En attente d'implémentation

Examples

# Implement solution
sooacette implement U-R68fKqXLCtdp81u0KiJ

# Dry run
sooacette implement U-R68fKqXLCtdp81u0KiJ --dry-run

What Happens

1. 📖 Reads .recette/<filename>-analyse.md
2. 🚀 Generates implementation prompt
3. 💻 Opens Claude Code with instructions
4. 🔧 Claude applies modifications
5. ✅ Runs tests
6. 📝 Updates analysis status to ✅ Implémenté

implement-bulk - Batch Implementation

Implement multiple solutions from pending analysis files.

sooacette implement-bulk [options]

Options

| Option | Type | Description | |--------|------|-------------| | -p, --project <name> | string | Project name | | -l, --limit <number> | number | Max implementations | | --no-confirm | boolean | Skip confirmation | | --sequential | boolean | Process one-by-one |

Examples

# Implement all pending analyses
sooacette implement-bulk

# Sequential with limit
sooacette implement-bulk --sequential --limit 5

# Automated mode
sooacette implement-bulk --no-confirm

daemon - Autonomous Mode

🤖 Fully Automated - Runs continuously, monitoring and processing constats 24/7.

sooacette daemon [options]

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | -p, --project <name> | string | config default | Project name | | -s, --state <state> | string | Nouveau | Filter by state | | --priority <priority> | string | - | Filter by priority | | --interval <duration> | string | 1m | Polling interval | | --analysis-timeout <duration> | string | 10m | Max wait for analysis | | --auto-implement | boolean | false | Auto-implement after analysis |

Examples

# Basic daemon (analysis only)
sooacette daemon

# Full automation
sooacette daemon --auto-implement

# Custom settings
sooacette daemon --interval 30s --analysis-timeout 5m --priority Critical

# Production mode
sooacette daemon --interval 1m --auto-implement --state Nouveau

How It Works

┌─────────────────────────────────────────────────────────────┐
│  🤖 Sooacette Daemon - Autonomous Mode                      │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  [14:30:15] 🔄 Polling API...                               │
│  📥 Found 2 new constat(s)                                  │
│                                                              │
│  🔍 Starting analysis: U-R68fKqXLCtdp81u0KiJ                │
│  ℹ Exporting to Jira...                                     │
│  ✓ Exported to Jira: GSL-123                                │
│  ℹ Fetching Jira issue details for GSL-123...              │
│  ✓ Fetched Jira issue: [FEAT-001] Login - Bug              │
│  ✓ Found Confluence page: https://...                       │
│  ✓ Wrote constat data to .recette/GSL-123-...json          │
│  ✓ Wrote preprompt to .recette/GSL-123-...-preprompt.md    │
│  ℹ Opening terminal...                                      │
│  ✓ Launched analysis for U-R68fKqXLCtdp81u0KiJ             │
│                                                              │
│  [14:31:15] 🔄 Polling API...                               │
│  📊 Status: 1 analyzing, 0 analyzed, 0 implemented          │
│                                                              │
│  [14:32:15] 🔄 Polling API...                               │
│  📄 Analysis ready: U-R68fKqXLCtdp81u0KiJ                   │
│     Status: ⏳ En attente d'implémentation                   │
│  🚀 Auto-implementing solution...                           │
│  ✓ Launched implementation for U-R68fKqXLCtdp81u0KiJ       │
│                                                              │
│  📊 Status: 0 analyzing, 1 analyzed, 1 implemented          │
└─────────────────────────────────────────────────────────────┘

State Management

The daemon maintains state in ~/.sooacette/daemon-cache.json:

{
  "processedIds": ["U-R68fKqXLCtdp81u0KiJ", "U-ABC123..."],
  "analyzing": {
    "U-XYZ789...": {
      "startedAt": "2025-10-16T14:30:00.000Z",
      "checkedCount": 3
    }
  },
  "analyzed": ["U-R68fKqXLCtdp81u0KiJ"],
  "implemented": ["U-R68fKqXLCtdp81u0KiJ"]
}

Running as Service

Create /etc/systemd/system/sooacette-daemon.service:

[Unit]
Description=Sooacette Daemon - Automated Constat Analysis
After=network.target

[Service]
Type=simple
User=your-user
WorkingDirectory=/path/to/repo
Environment="SOOATEK_API_KEY=your-api-key"
ExecStart=/usr/local/bin/sooacette daemon --auto-implement --interval 1m
Restart=always
RestartSec=10
StandardOutput=append:/var/log/sooacette-daemon.log
StandardError=append:/var/log/sooacette-daemon.error.log

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl enable sooacette-daemon
sudo systemctl start sooacette-daemon
sudo systemctl status sooacette-daemon

# View logs
sudo journalctl -u sooacette-daemon -f

watch - Watch for New Constats

Continuously monitor for new constats and open terminals automatically.

sooacette watch [options]

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | -p, --project <name> | string | config default | Project name | | -s, --state <state> | string | Nouveau | Filter by state | | --priority <priority> | string | - | Filter by priority | | --interval <duration> | string | 30s | Polling interval | | --since <ISO date> | string | - | Only constats after date |

Examples

# Watch for new constats
sooacette watch

# Custom interval
sooacette watch --interval 1m

# With filters
sooacette watch --state Nouveau --priority Critical

# Since specific date
sooacette watch --since 2025-01-01T00:00:00Z

💡 Tip: Use daemon instead of watch for more advanced features like analysis detection and auto-implementation.

🎯 Jira & Confluence Integration

Automatic Jira Export

When you start analysis (via run, bulk, or daemon), Sooacette automatically:

1. Calls POST /api/constats/{id}/export-jira
2. Retrieves the Jira issue key (e.g., GSL-123)
3. Fetches full Jira issue details via GET /api/jira/issues/{key}
4. Extracts Confluence URL from Jira description
5. Uses Jira info for intelligent file naming

Example Output:

ℹ Exporting to Jira...
✓ Exported to Jira: GSL-123
ℹ Fetching Jira issue details for GSL-123...
✓ Fetched Jira issue: [FEAT-001] Login - Bouton non fonctionnel
✓ Found Confluence page: https://sooatek.atlassian.net/wiki/spaces/FDP/pages/12345/...
  Using filename: GSL-123-FEAT-001-Login-Bouton-non-fonctionnel

Confluence Page Creation

NEW: Sooacette publishes to Confluence using the Confluence REST API v2 with ADF (Atlassian Document Format).

How It Works

When Confluence credentials are configured (see Confluence Configuration):

1. Primary method - Claude Code executes sooacette publish-* commands
2. Fallback system - Auto-publishes after 30s if Claude forgets
3. Dual publication - Both analysis and implementation reports published
4. Child page creation - Creates pages under the Jira ticket's Confluence page
5. Markdown to ADF - Automatic conversion to Atlassian Document Format
6. Auto-versioning - Handles duplicate titles (adds v2, v3, etc.)

Publication Methods

Method 1: Claude Executes Commands (Preferred)

# Claude is instructed via preprompt to execute:
sooacette publish-analysis <id>
sooacette publish-implementation <id>

Method 2: Auto-Publish Fallback (Safety Net)

• Background watcher monitors for file creation
• Waits 30 seconds for Claude to publish
• Auto-publishes if marker file doesn't exist
• Prevents missed publications

Page Hierarchy

📄 Jira Page (e.g., GSL-123)
  ├── 📊 Analyse Technique - Constat xxx
  └── ✅ Rapport d'Implémentation - Constat xxx

Both pages are siblings at the same level under the Jira page.

Why This Structure?

• 📄 Preserves the main Jira page (may contain templates)
• 🗂️ Organized structure (Jira → Analysis + Implementation)
• 🔗 Easy navigation from Jira ticket
• 🔒 No risk of overwriting existing content
• 🔄 Analysis and implementation at same level (not parent-child)

Auto-Versioning

If a page title already exists (e.g., after re-analysis):

First publication:  "Analyse Technique - Constat xxx"
Second publication: "Analyse Technique - Constat xxx v2"
Third publication:  "Analyse Technique - Constat xxx v3"
...

This allows:

• 📝 Re-analysis after client feedback
• 🔄 Multiple implementation attempts
• 📜 Version history preservation
• ✅ No manual title management needed

Document Format

Pages are published in ADF (Atlassian Document Format), Confluence's native JSON-based format:

Key Features:

• ✅ Native Confluence format (REST API v2)
• 🎨 Rich formatting (headings, lists, code blocks, tables)
• 🔗 Proper hyperlinks and cross-references
• 📊 Structured document hierarchy
• ⚡ Better performance than Storage Format

Example ADF Structure:

{
  "version": 1,
  "type": "doc",
  "content": [
    {
      "type": "heading",
      "attrs": { "level": 1 },
      "content": [{ "type": "text", "text": "Analyse Technique" }]
    },
    {
      "type": "paragraph",
      "content": [{ "type": "text", "text": "Content..." }]
    }
  ]
}

Intelligent File Naming

Files are named using Jira information with a 100-character limit:

Pattern: {JIRA-KEY}-{Safe-Title}.{extension}
Max length: 100 characters total

Examples:

| Jira Summary | Generated Filename | |--------------|-------------------| | [FEAT-001] Login - Bouton non fonctionnel | GSL-123-FEAT-001-Login-Bouton-non-fonctionnel.json | | Bug d'affichage sur la page de connexion utilisateur avec des caractères spéciaux | GSL-456-Bug-daffichage-sur-la-page-de-connexion-utilisateur-avec-des-caracteres-spe.json | | Très long titre avec beaucoup de détails techniques supplémentaires qui dépassent largement la limite | GSL-789-Tres-long-titre-avec-beaucoup-de-details-techniques-supplementaires-qui-depas.json |

Fallback: If Jira export fails or no Jira key, uses constat ID:

U-R68fKqXLCtdp81u0KiJ.json

🔧 MCP Configuration

What is MCP?

Model Context Protocol (MCP) allows Claude to access project-specific tools and capabilities.

How Sooacette Uses MCP

1. Reads mcp.md from your repository root (if exists)
2. Includes it in preprompt sent to Claude Code
3. Claude uses MCP servers as documented
4. Enhanced analysis with project-specific context

Creating mcp.md

Create this file at your repository root to document available MCP servers.

Example mcp.md:

# MCP Configuration - Geslico

## Available MCP Servers

### 🔧 IDE MCP Server
**Name**: `mcp__ide__*`

**Capabilities**:
- Get code diagnostics (errors, warnings, suggestions)
- Execute Python code in Jupyter notebooks

### 🌐 Playwright MCP Server
**Name**: `mcp__playwright__*`

**Capabilities**:
- Browser automation for E2E testing
- Take screenshots and accessibility snapshots
- Interact with web elements (click, type, select)
- Monitor network and console logs

### 🔍 Claude Context MCP Server
**Name**: `mcp__claude-context__*`

**Capabilities**:
- Semantic codebase indexing
- Natural language code search
- Project structure analysis
- Identify duplicate code

### 🎫 Atlassian MCP Server (Optional)
**Name**: `mcp__atlassian__*`

**Note:** **No longer required for Confluence publishing!** Sooacette now uses the Confluence REST API directly.

**Capabilities**:
- List Confluence spaces
- Create and update Confluence pages (now handled by Sooacette directly)
- Search Confluence content
- Get Jira issue details (if needed for other purposes)

## Project Architecture

### Backend
- **Framework**: Symfony 7.2
- **PHP**: 8.3
- **API**: API Platform 4.0
- **Database**: MariaDB 10

### Frontend
- **Framework**: Vue.js 2
- **UI**: Bootstrap 5
- **Build**: Webpack Encore

## Analysis Guidelines

1. **Always check the database schema** before making assumptions
2. **Follow coding standards** documented in `docs/CONTRIBUTING.md`
3. **Run tests** before proposing solutions
4. **Document complex logic** with clear comments
5. **Use MCP Playwright** for E2E testing when modifying UI

MCP in Preprompts

The preprompt automatically includes MCP configuration when available:

• If mcp.md exists in your repository, its content is included in the preprompt
• Claude Code can use configured MCP servers for enhanced analysis
• Confluence publishing is handled by Sooacette directly (no MCP Atlassian required!)

Example preprompt section:

## Configuration MCP du Projet

[Content from your mcp.md file...]

## Mission

Analyser ce constat de recettage et proposer une solution appropriée.

Publishing Without MCP

Previous workflow (deprecated):

• Required MCP Atlassian server
• Claude had to use mcp__atlassian__createPage tool
• Complex setup and authentication

New workflow (current):

• ✅ Uses Confluence REST API v2 directly
• ✅ Claude executes sooacette publish-* bash commands
• ✅ Simple configuration with sooacette configure-confluence
• ✅ Auto-publish fallback ensures reliability
• ✅ No MCP server required for Confluence

This change makes Sooacette more reliable and easier to set up!

💡 Use Cases

🎯 Single Constat Analysis

Perfect for focused bug fixes or feature analysis.

# One-time setup (per project)
cd /path/to/project
sooacette init
cp .sooacette.local.example .sooacette.local.json
# Edit .sooacette.local.json with your API key

# Step 1: Analyze (no -p flag needed!)
sooacette run U-R68fKqXLCtdp81u0KiJ

# Step 2: Review
cat .recette/GSL-123-FEAT-001-Login-Bug-analyse.md

# Step 3: Implement
sooacette implement U-R68fKqXLCtdp81u0KiJ

Time saved: ~30 minutes per constat

📦 Batch Processing

Process multiple constats for sprint planning or backlog grooming.

# Step 1: Analyze all critical constats
sooacette bulk --state Nouveau --priority Critical --limit 20

# Step 2: Review all analyses
ls -la .recette/*-analyse.md

# Step 3: Implement approved solutions
sooacette implement-bulk

Time saved: ~2-3 hours for 10 constats

🤖 Fully Automated (24/7 Monitoring)

Set it and forget it - continuous monitoring and processing.

# Option 1: Run in foreground
sooacette daemon --auto-implement --interval 1m

# Option 2: Run in background
nohup sooacette daemon --auto-implement --interval 1m > daemon.log 2>&1 &

# Option 3: Systemd service (recommended)
sudo systemctl start sooacette-daemon

Benefits:

• 🕐 24/7 monitoring
• ⚡ Instant processing of new constats
• 📊 Automated analysis and implementation
• 🔄 Self-healing (restarts on errors)

🔍 Quality Assurance Workflow

Use for testing and QA processes.

# Morning: Process overnight constats
sooacette bulk --since "2025-10-16T00:00:00Z" --sequential

# Throughout day: Watch for new issues
sooacette watch --interval 5m

# Evening: Review and implement
sooacette implement-bulk --no-confirm

🐛 Troubleshooting

For local config:

# Create secrets file
cp .sooacette.local.example .sooacette.local.json

# Edit and add your API key
nano .sooacette.local.json

For global config:

export SOOATEK_API_KEY="your-api-key-here"

# Add to shell profile for persistence
echo 'export SOOATEK_API_KEY="your-api-key"' >> ~/.bashrc
source ~/.bashrc

Problem: You accidentally put your API key in .sooacette.json (versioned file)

Solution:

# 1. Remove API key from .sooacette.json
nano .sooacette.json
# Delete the "apiKey" field

# 2. Add it to .sooacette.local.json instead
nano .sooacette.local.json
{
  "auth": {
    "apiKey": "your-api-key-here"
  }
}

# 3. If already committed, remove from git history
git filter-branch --force --index-filter \
  'git rm --cached --ignore-unmatch .sooacette.json' \
  --prune-empty --tag-name-filter cat -- --all

Prevention:

• Always use .sooacette.local.json for secrets
• Add .sooacette.local.json to .gitignore
• Commit .sooacette.local.example instead

Problem: .sooacette.local.json is not in .gitignore

Solution:

# Add to .gitignore
echo ".sooacette.local.json" >> .gitignore

# Verify
grep "sooacette.local.json" .gitignore

Solution:

# Option 1: Initialize local config
cd /path/to/your/project
sooacette init

# Option 2: Use global config
sooacette run <constat-id> -p myproject

# Option 3: Create global config
mkdir -p ~/.sooacette
# Edit ~/.sooacette/config.json manually

Solution:

# Edit config
nano ~/.sooacette/config.json

# Set absolute path
{
  "projects": {
    "sooatek": {
      "repoPath": "/home/user/projects/geslico"
    }
  }
}

Causes:

• Incorrect API key
• Expired API key
• Wrong environment variable

Solution:

# Check current value
echo $SOOATEK_API_KEY

# Get new key from platform
# Update environment variable

For snap VSCode conflicts:

Sooacette automatically cleans snap environment variables. If still failing:

# Install gnome-terminal
sudo apt install gnome-terminal

# Or use different terminal
nano ~/.sooacette/config.json
# Set "terminal": { "linux": "konsole" }

Solution:

# Install Windows Terminal from Microsoft Store
# Or update config to use PowerShell
{
  "terminal": {
    "windows": "powershell"
  }
}

Solution:

export HTTP_PROXY="http://proxy.company.com:8080"
export HTTPS_PROXY="http://proxy.company.com:8080"
export NO_PROXY="localhost,127.0.0.1"

What it means:

• Jira export API returned ok: true but no jiraIssueKey
• Constat may have been already exported

What happens:

• Sooacette checks if constat already has Jira info
• Falls back to using existing jiraIssueKey if found
• Uses constat ID for filename if no Jira info available

Solution:

• Usually automatic (no action needed)
• Check .recette/ directory for created files
• Check Jira platform for the ticket

Causes:

• Jira export failed or returned no jiraIssueKey
• API issue or rate limiting

What files look like:

.recette/U-R68fKqXLCtdp81u0KiJ.json  (instead of GSL-123-Title.json)

Solution:

• Files still work correctly (constat ID is used)
• Check Jira export logs for errors
• Verify API connectivity: curl -H "Authorization: Bearer $SOOATEK_API_KEY" https://doc.geslico.sooatek.com/api/constats
• Run with manual Jira check: Re-run sooacette run <id> after fixing API issues

Possible causes:

• No Confluence credentials configured
• Invalid API token
• No Confluence URL in Jira description
• Network issues

Solution:

# Configure Confluence credentials
sooacette configure-confluence

# Verify configuration
cat ~/.sooacette/confluence.json

# Test connection manually
curl -u "[email protected]:api-token" \
  https://your-domain.atlassian.net/wiki/api/v2/pages

# Check if Jira has Confluence URL
sooacette show <constat-id> --json | grep confluenceUrl

# Manual publish
sooacette publish-analysis <constat-id> -u <confluence-url>

Error: "HTTP 400 - A page with this title already exists"

• This should not happen anymore (auto-versioning enabled)
• If it does, check Confluence API permissions
• Verify the page doesn't exist with exact same title

Error: "Confluence configuration not found"

# Run interactive setup
sooacette configure-confluence

# Or set environment variables
export CONFLUENCE_BASE_URL="https://your-domain.atlassian.net"
export CONFLUENCE_EMAIL="[email protected]"
export CONFLUENCE_API_TOKEN="your-token"

What to check:

1. File was created in .recette/ directory
2. File contains required sections
3. Confluence credentials are configured
4. Terminal output shows "Auto-publish watcher started"

Debug steps:

# Check if marker file exists (means already published)
ls -la .recette/.*published

# Check file completeness
grep "## 1. Résumé du problème" .recette/*-analyse.md
grep "## 3. Solution recommandée" .recette/*-analyse.md

# Manual publish to test
sooacette publish-analysis <constat-id>

How the fallback works:

• Checks every 5 seconds for file
• Waits 30 seconds after file is complete
• Publishes if no .${constat-id}-analysis.published marker
• Creates marker file after successful publish

Cause:

• Manual publication after auto-publish
• Running publish command multiple times

What happens:

• Auto-versioning creates "Title v2", "Title v3", etc.
• Each publication gets a unique title

Solution:

• Check marker files: ls .recette/.*published
• Delete marker to allow re-publishing: rm .recette/.${id}-analysis.published
• Archive old versions in Confluence manually

Prevention:

• Let auto-publish handle it automatically
• Only use manual commands for debugging
• Check marker files before re-publishing

🎓 Best Practices

✅ For Analysis

• Review before implementation - Always check analysis files
• Keep mcp.md updated - Document available tools
• Use descriptive constats - Better analysis from better input
• Check Confluence pages - Verify publications are formatted correctly

✨ Analysis Quality Improvements (v1.0.13 → v1.0.15)

Sooacette enforces strict quality rules with automatic validation:

🎯 Concision (Quantified - NEW v1.0.15)

• Résumé: MAX 50 words (objective metric)
• Cause: MAX 75 words with code citations
• Modification reason: MAX 15 words
• Risks: MAX 30 words or "None"
• Proportional to problem size

📋 Evidence Required (with examples)

• Format: file.ext:123-145 (mandatory)
• ✅ GOOD: "Status never set to 'inactive' (RepriseLicence.php:145)"
• ❌ BAD: "The system doesn't handle affiliations correctly"
• No speculation without verification

🔍 Context Verification (Adaptive)

Always check:

• ✅ .env.local configuration

If problem involves:

• ✅ Data → Database (schema + test SQL query)
• ✅ Logic → Business code (services/controllers)
• ✅ Display → Templates/CSS
• ✅ API → Routes/endpoints

🎨 Adaptive Format (NEW v1.0.15)

• Simple problems (< 10 lines, 1 file): Condensed template
• Complex problems (multiple files or DB): Full structure
• Proportional structure to avoid over-documentation

✅ Auto-Validation (NEW v1.0.15)

7-point checklist before file creation:

• Summary ≤ 50 words
• All references use file.ext:123-145 format
• At least 1 code citation in "Cause"
• Measurable/quantifiable impacts
• Before/after code (no prose)
• Tests with concrete data
• Modification reasons ≤ 15 words

Quality scoring (10 points):

• Goal: 10/10, Minimum: 8/10
• Self-regulation mechanism

🚫 Anti-Patterns (NEW v1.0.15)

Examples of what NOT to do:

• ❌ Verbose summaries
• ❌ Claims without evidence
• ❌ Vague impacts ("may cause issues")
• ❌ Prose instead of code

📊 Results (v1.0.15)

• ✅ Analyses 70% more concise (vs original)
• ✅ 100% factual with code references
• ✅ 8+ concrete examples in preprompt
• ✅ Objective metrics (word counts)
• ✅ Adaptive format (flexible but rigorous)
• ✅ Auto-validation (quality score 10/10)
• ✅ Quality +40% vs v1.0.14

Trade-off: Preprompt +37% longer (guidance examples) but analysis quality +40%

See AMELIORATIONS_QUALITE_ANALYSE.md for complete details.

✅ For Implementation

• Run tests after - Verify solution works
• Update analysis status - Keep documentation accurate
• Commit with references - Link to constat/Jira in commits

✅ For Daemon Mode

• Start with manual mode - Test workflow first
• Monitor logs initially - Catch issues early
• Use systemd for production - Better process management
• Set reasonable intervals - Avoid API rate limits (1m recommended)
• Enable auto-implement cautiously - Only after thorough testing

✅ For Confluence

• Run configure-confluence - Set up credentials once for all projects
• Check page hierarchy - Verify analysis and implementation are siblings
• Review auto-versioned pages - Check v2, v3 versions if re-analyzing
• Monitor fallback logs - Ensure auto-publish works if Claude forgets
• Link to Jira - Keep cross-references up to date

📊 Performance Metrics

| Metric | Manual Process | With Sooacette | Time Saved | |--------|---------------|----------------|------------| | Single analysis | 30-45 min | 5-10 min | ~35 min | | Batch (10 constats) | 5-7 hours | 1-2 hours | ~5 hours | | Daily monitoring | 2-3 hours | Automated | ~3 hours/day | | Jira ticket creation | 5 min | Automatic | 5 min/constat | | Confluence documentation | 10-15 min | Automatic | 15 min/constat |

Estimated productivity gain: 70-80%

🤝 Contributing

Contributions are welcome! Here's how you can help:

Development Setup

# Clone repository
git clone <repository>
cd sooacette

# Install dependencies
npm install

# Build
npm run build

# Run in development
npm run dev -- list

# Run tests
npm test

# Lint and format
npm run lint
npm run format

Contribution Guidelines

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Code Style

• TypeScript for all source files
• ESLint + Prettier for formatting
• Descriptive commit messages
• Tests for new features

📜 License

MIT License - See LICENSE file for details

🙏 Credits

Built with love using:

• Commander.js - Elegant CLI framework
• Undici - High-performance HTTP client
• Chalk - Terminal colors and styling
• Claude Code - AI-powered development assistant
• TypeScript - Type-safe JavaScript

🌟 Star History

If you find this project useful, please consider giving it a star ⭐

Made with ❤️ by Florent, for Sooatek

Report Bug • Request Feature • Documentation