---
name: documentation
description: |
  Automatically generates technical documentation for SmartStack.
  Use this skill when:
  - User asks to create/generate documentation
  - User mentions "document", "documentation", "doc", "ERD", "schema"
  - User wants to document a module, table, tool, or test
  - After implementing a feature to generate its documentation
  Types: user module, developer tools, database ERD, testing tools
argument-hint: "<module-name> [--type user|developer|database|testing|update]"
model: sonnet
---

<objective>
Generate and maintain technical documentation integrated into SmartStack web app.
Works in synergy with the `/documentation module` command.

**Reference:** [_shared.md](../_shared.md) for architecture, i18n
</objective>

<quick_start>
## WHEN THIS SKILL ACTIVATES

### PREREQUISITE — ONLY post-implementation
This skill requires the feature page to already exist (generated by /business-analyse-develop).
It reads real TSX pages, controllers, and entities. Without them, nothing to document.

→ For reviewing/editing the analysis BEFORE implementation: use ba-interactive.html (/business-analyse step-05)

Claude automatically invokes this skill when it detects:

| Trigger | Example |
|---------|---------|
| ❌ NEVER during BA | Before /business-analyse-develop — feature page does not exist yet |
| Explicit request | "Document the SLA module" |
| Documentation mention | "We should create the doc for..." |
| After implementation | "The feature is done, generate the doc" |
| Structure question | "How is the documentation organized?" |
| Keywords | "ERD", "schema", "diagram", "document" |
| **Update request** | "Update the doc", "refresh documentation", "doc is outdated" |
| **Drift detected** | "The SLA documentation is stale" |
</quick_start>

<parameters>
## DOCUMENTATION TYPES

| Type | Description | Output |
|------|-------------|--------|
| `user` | User module (Mock UI) | `docs/business/{application}/{module}/index.tsx` (standalone TSX with Mock UI) |
| `developer` | Development tool guide | `docs/developer/tools/{Tool}Page.tsx` |
| `database` | Schema with ERD diagram | `docs/developer/database/{Schema}SchemaPage.tsx` |
| `testing` | Testing tool | `docs/developer/testing/{Tool}TestingPage.tsx` |
| `update` | Update existing documentation | Updates `doc-data.ts` + i18n FR |

### Available Developer tools

| Category | Tools |
|----------|-------|
| Local Environment | Docker Compose, MailDev, VS Code, Environment variables |
| API Testing | Postman, REST Client, Swagger/OpenAPI |
| E2E Testing | Microsoft Playwright, Inspector, Trace Viewer |
| Load Testing | NBomber (.NET), k6, Azure Load Testing |
| Security Testing | OWASP ZAP, Security Code Scan, Snyk, OWASP ASVS |
</parameters>

<workflow>
## WORKFLOW EXECUTION SEQUENCE

The documentation skill executes in 4 progressive steps, each loaded on-demand:

1. **[Step 00: Init](steps/step-00-init.md)** — Detect documentation type and gather context
2. **[Step 01: Scan](steps/step-01-scan.md)** — Scan source code and extract data
3. **[Step 02: Generate](steps/step-02-generate.md)** — Generate documentation content
4. **[Step 03: Validate](steps/step-03-validate.md)** — Validate and integrate into SmartStack

### Quick Reference

| Type | Key Actions |
|------|-----------|
| `user` | Read real page TSX → Extract API/BR → Generate standalone annotated Mock UI TSX → Generate i18n (4 lang, FLAT) → Register routes/DocPanel |
| `developer\|database\|testing` | Extract tool data → Generate doc-data.ts → Generate DocRenderer wrapper → Generate i18n (4 lang, nested) → Register routes |
| `update` | Re-read real page TSX → Refresh API endpoints and business rules → Update i18n files (4 lang) → Update docs-manifest.json timestamps |

</workflow>

<entry_point>
## SKILL ENTRY POINT

**Start with:** [steps/step-00-init.md](steps/step-00-init.md)

All execution flows through this progressive loading architecture. Each step file contains:
- Clear execution sequence
- Success metrics
- Next step reference
</entry_point>

<execution_rules>
## ABSOLUTE RULES

1. **NEVER** hardcoded text → `useTranslation('namespace')`
2. **NEVER** ASCII art → React/HTML components for ERD
3. **ALWAYS** read the REAL page TSX before generating Mock UI
4. **ALWAYS** read the controller to extract real API endpoints
5. **ALWAYS** annotate every Mock UI section with `Annotation` components
6. **ALWAYS** generate i18n in ALL 4 languages (FR, EN, DE, IT)
7. **ALWAYS** use FLAT JSON (no root key) for standalone `user` type pages
8. **ALWAYS** update App.tsx, docs-manifest.json, i18n/config.ts
9. **ALWAYS** add module in `UserIndexPage.tsx` (IF type == `user`)
10. **ALWAYS** update `DocPanelContext.tsx` mapping (IF type == `user`)
11. **For `user` type:** Generate a standalone annotated Mock UI TSX page. **DO NOT use DocRenderer.**
12. **For `developer|database|testing` types:** Use DocRenderer with `doc-data.ts` + `index.tsx` wrapper, pass `i18nNamespace` prop.
13. **NEVER** include "Benefices" or "Avant/Apres" sections — this is documentation, not sales.
</execution_rules>

<step_files>
## Step Files

| Step | File | Purpose |
|------|------|---------|
| 00 | [steps/step-00-init.md](steps/step-00-init.md) | Detect documentation type and gather context |
| 01 | [steps/step-01-scan.md](steps/step-01-scan.md) | Scan source code and extract data |
| 02 | [steps/step-02-generate.md](steps/step-02-generate.md) | Generate documentation content |
| 03 | [steps/step-03-validate.md](steps/step-03-validate.md) | Validate and integrate into SmartStack |
</step_files>

<success_criteria>
- Documentation page renders correctly in React app
- Mock UI faithfully reproduces the real page interface (not generic KPI/table)
- Every Mock UI section has `Annotation` components explaining each visual element
- i18n files created in ALL 4 languages (FR, EN, DE, IT) with correct JSON format
- Route registered in App.tsx
- docs-manifest.json updated
- i18n/config.ts updated with new namespace
- Module appears in UserIndexPage (if type = user)
- DocPanelContext.tsx mapping updated (if type = user)
- BookOpen edge button opens correct doc for the module's routes
- NO "Benefices" or "Avant/Apres" sections present
</success_criteria>
