docs

What this skill does

# README Generator

Generates (or updates) a README.md oriented Product Owner, written in French, concise and illustrated with Mermaid diagrams. Reviews and improves all technical documentation in the `docs/` directory. Also generates CLAUDE.md and AGENT.md if they don't exist.

---

## When to Use

- No README.md exists at the project root
- The existing README.md is outdated after major changes
- After a significant feature addition or architectural change
- Onboarding a Product Owner or new stakeholder on the project

---

## The Job

### Step 1: Explore the Codebase

Thoroughly explore the project to understand its purpose, architecture, and tech stack:

- **Package manifest:** Read `package.json`, `composer.json`, `pyproject.toml`, `Cargo.toml`, or equivalent at root and in sub-packages (monorepo)
- **Project structure:** List top-level directories and key files to understand the architecture
- **Documentation:** Check for `docs/` directory. **Read the first 20-30 lines of each `.md` file in `docs/`** to deduce a short French description (one line) for each — this will be used in the Table of Contents
- **CI/CD:** Look for `.github/workflows/`, `.gitlab-ci.yml`, `Jenkinsfile`, `Dockerfile`, `docker-compose.yml`
- **Database:** Look for migrations, schemas, Prisma/TypeORM/Sequelize config
- **Routes/Controllers:** Scan for route definitions, API endpoints, controllers
- **Git info:** Run `git log --oneline -10` and `git remote -v` to understand recent activity and hosting
- **Environment:** Look for `.env.example`, environment configuration files

### Step 2: Create or Update

- Check if `README.md` exists at the project root
- **If it does NOT exist:** Create it from scratch using the template below
- **If it DOES exist:** Read the existing content, update factual sections (stack, architecture, features), and **preserve any custom sections** added by the team

### Step 3: Generate the Content

Follow the template defined in the "README Template" section below. All content must be in French, following the writing guidelines.

### Step 4: Write the File

Save `README.md` at the project root.

### Step 5: Generate CLAUDE.md and AGENT.md

**Only if these files do NOT exist at the project root.** If they already exist, do not touch them.

- **CLAUDE.md** — Generate instructions for Claude Code based on codebase exploration (see dedicated section below)
- **AGENT.md** — Generate instructions for autonomous AI agents based on codebase exploration (see dedicated section below)

### Step 6: Review Technical Documentation

Review every `.md` file in the `docs/` directory and propose improvements following the **Documentation Quality Rules** defined below.

For each file:

1. **Read the entire file**
2. **Evaluate** against each rule in the Documentation Quality Rules section
3. **Propose concrete improvements** — rewrite sections that violate the rules
4. **Apply changes** directly to the files
5. **Report** a summary of changes per file to the user

**Do NOT delete or remove existing documentation files.** Only improve their content.

### Step 7: Identify Missing Documentation

Cross-reference the codebase exploration (Step 1) with the existing `docs/` files to detect **critical or important features that are not documented**.

1. **Inventory documented topics** — List what each `docs/*.md` file covers
2. **Inventory codebase features** — From Step 1, list key features, modules, APIs, integrations, workflows, and architectural decisions found in the code
3. **Gap analysis** — Compare the two lists. Flag any feature that is:
   - Used in production code but has no corresponding documentation
   - A core business workflow (e.g., authentication, data pipeline, external integrations)
   - An architectural decision that would confuse a new team member without context
   - A complex module with non-obvious behavior
4. **Propose new documentation files** — For each gap, present to the user:
   - Suggested file name (e.g., `docs/authentication-flow.md`)
   - One-line description of what it would cover
   - Priority: **Critique** (blocks understanding of the system) or **Important** (significantly helps onboarding)
5. **Ask the user** which proposed files to create
6. **Generate approved files** following the Documentation Quality Rules — in French, concise, PO-oriented, with Mermaid diagrams where useful

### Step 8: Confirm

Summarize to the user what was done:
- Which files were created vs. updated
- Key sections included
- Any information that could not be determined and was left as placeholder
- **Documentation review:** list of `docs/` files reviewed with a one-line summary of improvements applied per file
- **Missing documentation:** list of new doc files proposed, which were approved and created

---

## README Template

The generated README.md must follow this structure:

### `# [Project Name]`

Short description (1-2 sentences, non-technical). Explain what the product does and who it's for.

### `## Table des matières`

Auto-generated table of contents listing all README sections with anchor links. Include a sub-section for technical documentation:

```markdown
## Table des matières

- [À quoi sert ce produit ?](#à-quoi-sert-ce-produit-)
- [Fonctionnalités principales](#fonctionnalités-principales)
- [Comment ça fonctionne](#comment-ça-fonctionne)
- [Environnements](#environnements)
- [Déploiement](#déploiement)
- [Stack technique](#stack-technique)
- [Documentation complémentaire](#documentation-complémentaire)

### Documentation technique

| Document | Description |
|----------|-------------|
| [Architecture REST & WebSocket](docs/REST-WebSocket-Architecture.md) | Description de l'architecture API |
| [Schéma de base de données](docs/database-schema.md) | Structure des tables et relations |
```

**Important:** The description for each doc file must be deduced from actually reading the file content (Step 1), not invented.

### `## À quoi sert ce produit ?`

Business value explanation. 3-5 bullet points describing what the product enables, from the user's perspective.

### `## Fonctionnalités principales`

List of features oriented toward user benefit. Use bullet points. Focus on what the user can do, not how it's implemented.

### `## Comment ça fonctionne`

High-level architecture diagram using Mermaid `graph LR` or `graph TD`, followed by a short textual explanation.

```markdown
```mermaid
graph LR
    A[Utilisateur] --> B[Application Web]
    B --> C[API Backend]
    C --> D[Base de données]
    C --> E[Services externes]
`` `

L'utilisateur interagit avec l'application web, qui communique avec l'API backend. Le backend gère la logique métier et stocke les données en base.
```

### `## Environnements`

Table with environment information:

```markdown
| Environnement | URL | Description |
|---------------|-----|-------------|
| Développement | `http://localhost:3000` | Environnement local |
| Staging | `https://staging.example.com` | Pré-production |
| Production | `https://app.example.com` | Environnement de production |
```

Use actual URLs if found in config, otherwise use realistic placeholders.

### `## Déploiement`

CI/CD pipeline as a Mermaid `graph LR` diagram, followed by a short explanation.

### `## Stack technique`

Categorized tech stack in 3-5 lines:

```markdown
- **Frontend :** React, TypeScript, TailwindCSS
- **Backend :** Node.js, NestJS, TypeORM
- **Base de données :** PostgreSQL
- **Hébergement :** Docker, GitLab CI/CD
```

### `## Documentation complémentaire`

Links to `docs/` files if they exist. If no docs folder exists, omit this section.

---

## Mermaid Diagram Rules

1. **Labels in French** — All node labels and edge labels must be in French
2. **Maximum 8-10 nodes** per diagram — Keep diagrams readable and high-level
3. **Allowed types:** `graph`, `flowchart`, `sequenceDiagram`
4. **Forbidden types:** `classDiagram`, `erDiagram`, `stateDiagram` (too technical for PO audience)
5. **Textual explanation** under every dia