---
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
allowed-tools: [Read, Glob, Grep, Bash]  # Bash: CLI invocation
---

<objective>
Generate and maintain technical documentation integrated into the SmartStack web app.

Two colocated CLIs do the deterministic work (`cli/extract-doc`, `cli/scaffold-doc`)
and the ui-polish CLI enforces theme tokens; you author the faithful Mock UI in between.

**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 /ba-develop).
It reads real TSX pages, controllers, and entities. Without them, nothing to document.

→ For reviewing/editing the analysis BEFORE implementation: use `/ba-audit-pre-dev`

Claude automatically invokes this skill when it detects:

| Trigger | Example |
|---------|---------|
| ❌ NEVER during BA | Before /ba-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/{group}/{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 | Re-run the CLIs (idempotent) |

### 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

Two colocated CLIs do the deterministic work; you author the faithful Mock UI in between.

1. **[Step 00: Init](steps/step-00-init.md)** — Detect type + target + application
2. **[Step 01: Scan](steps/step-01-scan.md)** — run **`extract-doc`** (real page, chart types, endpoints, rules, entity props)
3. **[Step 02: Generate](steps/step-02-generate.md)** — author the page + i18n content, then run **`scaffold-doc`** (writes i18n + manifest, returns a wiring plan you apply)
4. **[Step 03: Validate](steps/step-03-validate.md)** — run **ui-polish** (theme tokens) + verify wiring + typecheck

### CLIs

| CLI | Role |
|-----|------|
| `cli/extract-doc` | Read-only report: real page TSX, chart→Mock-UI mapping, API endpoints (resolved permissions), business rules, entity props, namespace/routes, **+ structure scan of the existing doc (`existingDoc.forbiddenSections` to strip, `existingDoc.missingRequired` = objective + header `summary` tagline to add)** |
| `cli/scaffold-doc` | Writes 4 i18n files (FLAT for user / nested for DocRenderer) + upserts `docs-manifest.json` + emits the wiring plan (config.ts / DocRoutes.tsx / DocPanelContext.tsx / UserIndexPage.tsx) |
| `development/frontend/ui-polish` | Enforces theme tokens (zero hardcoded colours) — replaces the old manual colour rules |

> Invoke CLIs with `npx tsx skills/documentation/cli/<cli>/index.ts --spec '<JSON>'`.
> On Windows PowerShell, call through the Bash tool (single-quoted JSON) or escape `"` as `\"`.

### Quick Reference

| Type | Key Actions |
|------|-----------|
| `user` | extract-doc → read real page → author standalone annotated Mock UI + FLAT i18n → scaffold-doc → apply wiring → ui-polish |
| `developer\|database\|testing` | extract-doc (thin) + tool/schema data → author doc-data.ts + DocRenderer wrapper + FLAT i18n → scaffold-doc → apply wiring → ui-polish |
| `update` | extract-doc (+ **strip any `existingDoc.forbiddenSections`, add any `existingDoc.missingRequired` = objective / header `summary`**) → refresh Mock UI / endpoints / rules → re-run scaffold-doc (idempotent) → ui-polish → §0 structure gate |
</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 (located by `extract-doc`) before writing Mock UI
4. **ALWAYS** use the real endpoints / business rules from the `extract-doc` report (curated, not dumped verbatim)
5. **ALWAYS** annotate every Mock UI section with the canonical `Annotation` component
6. **ALWAYS** author i18n in ALL 4 languages (FR, EN, DE, IT)
7. **i18n shape depends on type:** `user` = FLAT (no root key; resolved via `t('title')`); `developer/database/testing` = NESTED under the namespace key (resolved via `t('<namespace>.path')`). Author FLAT content — `scaffold-doc` wraps it for the DocRenderer types.
8. **ALWAYS** run `scaffold-doc` (i18n files + manifest), then apply its wiring plan (config.ts, DocRoutes.tsx, DocPanelContext.tsx, UserIndexPage.tsx)
9. **ALWAYS** run the ui-polish CLI before finishing (theme-token enforcement)
10. **For `user` type:** standalone annotated Mock UI TSX page. **DO NOT use DocRenderer.**
11. **For `developer|database|testing` types:** DocRenderer with `doc-data.ts` + `index.tsx` wrapper + `i18nNamespace` prop.
12. **ALWAYS** lead with **Objectif** as Section 1 — a factual description of what the module does, as its own numbered section (never folded into the header subtitle). **NEVER** include problème/solution, "Bénéfices" or "Avant/Après" sections — this is documentation, not sales. Both sides are enforced by the step-03 §0 structure gate.

### Theme / colour — delegated to the ui-polish CLI

13. **Colour & token compliance is enforced by the ui-polish CLI**, not by hand. After the page exists, run it (step-03) in apply mode (`--regenerate-threshold 0`). Do NOT hand-map Tailwind colours or maintain a mapping table — the CLI maps hardcoded colours → theme tokens deterministically. See `development/frontend/ui-polish`.

### Doc-specific intent the CLI can't infer (keep while authoring)

14. **Dashboard chart series / KPI use the `--dataviz-*` palette** (`--dataviz-accent`, `--dataviz-cat-1..12`, `--dataviz-trend-*`) — never `--color-accent-*`/`--color-primary-*` for data series. Mirrors the real `DashboardPage.tsx`.
15. **Brand colour = the themeable `--color-accent-*` ramp**, never the frozen `--color-primary-*` indigo.
16. **Highlight blocks (Annotation, Tip, "Avec la fonctionnalité")** use the discreet accent pattern `border-l-2 border-[var(--color-accent-500)] bg-[var(--bg-secondary)]` — never `--info/success/warning/error-bg` (reserved for real alerts).

### Mock UI fidelity + layout (user type — detail in templates.md)

17. **Faithful reproduction**: match the real page's layout family + each chart's recharts type (`extract-doc` `charts[]`). Never a generic KPI/table substitute.
18. **Expressive chart data**: ratio max/min(>0) ≥ 5x, visible peak + valley, height ≥ `h-24` (page) / `h-20` (DocPanel), real metric + unit (not abstract 0-100%).
19. **Annotations** sit INSIDE the same padded container as the Mock UI they explain; compact (`px-3 py-2 text-xs`).
20. **No DocPanel overflow**: `overflow-hidden` on chart cards, `min-w-0` on flex children, no fixed px bar widths; root container `space-y-8 max-w-5xl mx-auto pb-12` (no horizontal padding).
21. **Official card pattern**: `p-N bg-[var(--bg-card)] border border-[var(--border-color)] rounded-[var(--radius-card)]` — not `className="card"`, not `rounded-lg`, not `bg-white`/`bg-gray-*`.
22. **Fixed header block** (identical across pages): title + icon → **required accent tagline `t('summary')`** (`text-xl text-[var(--color-accent-600)] font-medium`) → `t('subtitle')` → inline stats line `<span>{N} {t('header.x')}</span>` (count as sibling text, **never** pills, **never** `t('header.x', {count})`). Missing tagline fails the §0 gate (`missingRequired` = `['summary']`).
</execution_rules>

<step_files>
## Step Files

| Step | File | Purpose |
|------|------|---------|
| 00 | [steps/step-00-init.md](steps/step-00-init.md) | Detect documentation type, target, application |
| 01 | [steps/step-01-scan.md](steps/step-01-scan.md) | Run `extract-doc` → report |
| 02 | [steps/step-02-generate.md](steps/step-02-generate.md) | Author content, run `scaffold-doc`, apply wiring plan |
| 03 | [steps/step-03-validate.md](steps/step-03-validate.md) | Run ui-polish, verify wiring, typecheck |
</step_files>

<success_criteria>
- Documentation page renders correctly in the 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) — FLAT for `user`, nested under the namespace key for DocRenderer types
- ui-polish reports 0 colour errors on the generated page
- Wiring applied: route in `DocRoutes.tsx`, namespace in `i18n/config.ts`, `docs-manifest.json` entry, `DocPanelContext.tsx` mapping (+ `UserIndexPage.tsx` for user type)
- Web app typechecks/builds
- Header is the fixed block: title + **accent tagline `t('summary')`** + subtitle + inline stats line (counts as sibling text, not pills) — consistent across pages
- Section 1 is **Objectif** (factual description of what the module does) AND no problème/solution, "Bénéfices" or "Avant/Après" framing — `extract-doc`'s `existingDoc.forbiddenSections` AND `existingDoc.missingRequired` (`objective`, `summary`) are all empty (step-03 §0 blocking gate)
</success_criteria>
