frontend-docs-architect

What this skill does

# Frontend Docs Architect

Generate house-style frontend documentation **grounded in the actual code**. The skill investigates the solution completely and automatically, proposes a documentation plan that the user must approve, and only then writes files. Existing documentation is moved to an archive — never blindly overwritten. Output is English, written for both human developers and LLM agents.

## Metadata

| Field | Value |
|---|---|
| `name` | frontend-docs-architect |
| `primary_category` | generation |
| `secondary_category` | planning |
| `output_mode` | human_readable |
| `creativity_level` | low (structure and prose are authored freely; every fact is grounded in the code) |
| `evidence_mode` | required for all technical claims (`path:line` references); not applicable to authored prose/structure |
| `tone` | technical / neutral |
| `version` | 1.1.0 |

## When to use

- A frontend codebase must be (re)documented in a consistent house style, grounded in the real code rather than assumptions.
- The architecture and techniques are unknown or vary per project and must first be discovered before documentation can be accurate.
- Existing documentation is outdated, incomplete, or inconsistent and must be replaced while the old versions are preserved (archive).

## When not to use

- The target directory is not a recognizable frontend (no package manifest, no frontend framework). → Return `Cannot proceed`.
- The task is backend-only or library-only documentation with no frontend.
- A single quick README without research is wanted. → Use `readme-generator` instead.

## Required input

- **Frontend root path** — the directory to document. Default: current working directory. The skill locates the nearest package manifest and framework markers.

## Optional input

- **Scope** — which app/package to document when a monorepo or multiple frontends are detected.
- **Emphasis areas** — topics to expand (e.g. auth, state, API integration).
- **Naming/branding conventions** — product or house-style names to use in headings and prose.

## Input schema

```
{
  "content":     { "frontend_root": "<path>" },
  "context":     { "scope": "<app/package | null>", "emphasis": ["<area>", ...] | null,
                   "naming": "<brand/style note | null>" },
  "constraints": { "language": "English (fixed)", "audience": "developers + LLM agents (fixed)" }
}
```

## House-style baseline

The documentation house style is a **strong guideline, not a rigid template**. Anchor on these conventions; adapt the actual set of files to what the research finds (omit guides for absent techniques, add guides for present ones).

- **Single entry point** — a top-level doc index / README that links out to everything.
- **Layered, progressive disclosure** — Setup → Architecture → Development guidelines → Operations/Deployment.
- **`documentation/` tree** with, where applicable: `ARCHITECTURE.md`, `SETUP.md`, `CONTRIBUTING.md`, `DEPLOYMENT.md`, and a `development/` layer.
- **`development/` decision-tree hub** — a `README.md` that routes the reader by file type to specific guides (components, pages, stores/state, composables/hooks, services/API, styling).
- **Consistent per-guide section template** — `When to use` → `Pattern / Standard structure` → `Real Examples` (pulled from the actual codebase) → `Quick Checklist` → `Next Steps` (cross-links).
- **Cross-linking** — every guide links back to the hub and to related guides.
- **Mermaid diagrams** where the house style uses them (data flow, auth flow, component/state relationships, deployment), as in `ARCHITECTURE.md`. Use fenced ` ```mermaid ` blocks — never ASCII art.
- **Agent-readable** — explicit conventions, predictable headings, code-fenced paths/commands, no implicit knowledge.

### Documentation depth — do not over-document

Document understanding the source cannot give the reader for free. Both humans and LLM agents can read the files directly, so do not restate their mechanical contents.

- **Do not** walk through self-evident files line-by-line — a `Dockerfile`, CI YAML, `package.json`, lockfiles, `tsconfig`, lint/format configs, or `.env` examples. Reproducing what the file already plainly states adds noise, drifts out of date, and buries the signal.
- **Do** document the *why* behind them — the principles, decisions, conventions, constraints, and non-obvious wiring: why the deploy is split into these stages, why this state pattern was chosen, what a config value affects downstream, how pieces connect that the files alone don't reveal.
- Reference such files by `path` so the reader can open them; explain intent, not syntax.
- When in doubt: if removing a passage loses no understanding that isn't already obvious from opening the file, cut it.

## Mermaid diagram conventions

All diagrams use Mermaid in fenced ` ```mermaid ` blocks. No ASCII art.

| Concept | Mermaid diagram |
|---|---|
| Data flow, request/response, build/deploy pipeline | `flowchart` (`flowchart LR` / `TD`) |
| Auth flow, API call sequences, runtime interactions over time | `sequenceDiagram` |
| Component / store / module relationships and dependencies | `flowchart` or `classDiagram` |
| State machines (e.g. auth/session, async UI states) | `stateDiagram-v2` |
| Data model / entity relationships | `erDiagram` |

- Keep diagrams **grounded**: nodes and edges must reflect real modules, routes, stores, or services found in the code — never invented. Label nodes with real names; the surrounding prose cites `path:line`.
- Prefer several small, focused diagrams over one sprawling one.
- Diagram structure/layout may be authored freely (per the grounding policy); the entities and relationships shown must be real.

## Processing rules

Execute in order. Steps 1–4 are research and planning; **no file is created, moved, or modified before step 5**, which requires explicit user approval.

1. **Determine scope.** Locate the frontend root and package manifest. Detect monorepo / multiple frontends. If more than one app is found, ask which to document (or offer a per-app plan). If no frontend is recognizable, stop with `Cannot proceed`.

2. **Research the solution — fully and automatically. Leave nothing out.** Detect and record, with `path:line` evidence:
   - Framework + version (Vue/Nuxt, React/Next, Angular, Svelte/SvelteKit, Solid, etc.) and language (TS/JS).
   - Build tooling and bundler (Vite, webpack, Nuxt, Next, etc.), scripts, and package manager.
   - Routing approach (file-based, config-based, router library) and route map.
   - State management (Pinia, Vuex, Redux, Zustand, Context, Composition stores, signals).
   - Component and folder organization; component categories/patterns in use.
   - Styling approach (SCSS, CSS Modules, Tailwind, CSS-in-JS, BEM, design system).
   - API/data integration (SDK/client, generated clients, fetch wrappers, services layer).
   - Build/deploy and runtime (Docker, PM2, CI config, environment variables).
   - Testing (unit, component, e2e) and tooling (lint, format, hooks).
   - Existing documentation: inventory every doc file, note coverage and staleness.

3. **Map findings to the baseline.** Decide which house-style files apply. Add guides for techniques present (e.g. a `hooks/` guide for React); omit guides for techniques absent. Note every adaptation and its reason. Decide what **not** to document — self-evident files (Dockerfile, CI config, `package.json`, configs) are referenced and explained by intent, not reproduced (see Documentation depth).

4. **Propose the plan and STOP for approval.** Output a plan containing:
   - **Detected stack summary** (table, with evidence).
   - **Proposed documentation structure** (file tree under `documentation/`).
   - **Per-file actions** — `create` / `update`, with a one-line purpose each.
   - **Archive plan** — which existing docs move to `documentation/archive/` (preserve relative structure).
   - **Open questions / assumptions** and **risks**.
   - **Success criteria.**
   Wait f