product-narrative-generator

---
name: product-narrative-generator
description: "Generate newcomer-friendly NARRATIVE.md from per-product PRD.md for any AXOIQ product. Multi-audience (newcomer / pmo / engineer / external). Use when 'generate narrative', 'explain product', '/atlas narrative <product>', 'create newcomer doc for X', or onboarding new team member needs pedagogical product introduction."
mode: [engineering, personal]
effort: medium
version: 1.0.0
tier: [dev, admin]
---

# Product Narrative Generator

## Overview

Generate newcomer-friendly **NARRATIVE.md** files from authoritative per-product PRD.md sources. Multi-audience by default (newcomer + pmo + engineer + external sections) following the `template_version: narrative-v1` pattern validated 2026-05-11 on Brain + ATLAS Plugin manual narratives.

**Model strategy** : Opus for structure/audience-framing decisions, Sonnet for content drafting. HITL gate after draft before commit.

## Purpose

PRD = formal product spec (12 sections, audience: engineers/PMs/auditors).
NARRATIVE = pedagogical product story (4 audience sections, audience: newcomers/PMO/engineers/external).

**Complementary, NOT duplicate**. Same product, different framings.

## When to Use This Skill

- New team member joins → generate NARRATIVE.md for products they'll touch
- External client evaluation → generate NARRATIVE.md focused on `external` audience
- PMO briefing prep → generate NARRATIVE.md focused on `pmo` audience
- PRD updated → regenerate NARRATIVE.md to keep in sync (post-PRD-edit hook trigger)
- Workspace onboarding wizard → batch-generate all 10 product NARRATIVEs

## Inputs

| Input | Required? | Default | Notes |
|-------|-----------|---------|-------|
| `product` | YES | — | Product slug (brain, synapse, devhub, cloud-portal, axoiq-platform, atlas-plugin, homelab, gmining-innovation, synapse-pitch, gmining) |
| `audience` | NO | `multi` | One of : `multi` (all 4 sections balanced), `newcomer`, `pmo`, `engineer`, `external` |
| `style` | NO | `analogy-first` | One of : `analogy-first`, `use-case-first`, `comparison-first`, `formal` |
| `length` | NO | `medium` (~400-500L) | `short` ~200L · `medium` ~400-500L · `long` ~600-800L |

## Sources Read

The skill reads authoritatively from :

1. **`products/{product}/PRD.md`** (canonical authoritative source)
2. **`products/{product}/CLAUDE.md`** (technical context)
3. **`products/{product}/ROADMAP.md`** (timing context)
4. **`products/{product}/catalog-info.yaml`** (metadata)
5. **`decisions/*.md`** referenced in PRD `related_decisions:` frontmatter
6. **`docs/AXOIQ-OVERVIEW.md`** (ecosystem context for newcomer framing)
7. **`docs/AXOIQ-EXPLAINED.md`** (ecosystem pedagogical doc for cross-product comparisons)

**Forbidden** : the skill MUST NOT generate facts from training data. All content must be sourceable from the above files. Cite source in NARRATIVE if non-obvious.

## Outputs

Writes : `products/{product}/NARRATIVE.md`

**Frontmatter format** :

```yaml
---
type: narrative
product: {product}
audience_variants: [newcomer, pmo, engineer, external]
default_audience: newcomer  # or whatever specified
source_prd: products/{product}/PRD.md
template_version: narrative-v1
generated_by: product-narrative-generator
last_generated: {ISO 8601}
length: {short|medium|long}
visual_aids: [ascii-diagrams, comparison-tables, scenarios]
created: {ISO 8601 if new}
created_by: claude-{model}-{atlas_session_id}
atlas_session_id: {current session}
---
```

## NARRATIVE.md Structure (template-narrative-v1)

```markdown
# {Product} — Narrative pédagogique

> Tagline (1 sentence). Source: PRD Section 1.1.

## 📋 Table des matières (par audience)

[TOC with anchor links per audience section]

---

## 🌍 Le contexte AXOIQ (shared across audiences)
[Ecosystem-wide context, 1-2 paragraphs. Same content as docs/AXOIQ-EXPLAINED.md intro.]

---

## 👋 Pour un nouveau venu (start here)

### En 1 phrase
[Definition courte, sourceable]

### L'analogie
[Concrete analogy — NEW content, generated by skill based on PRD]

### Comment ça fonctionne (visual)
[ASCII diagram showing layers/components, derived from PRD Section 7 architecture]

### À quoi ça sert concrètement
[Table : situation × before × after, 4-6 rows derived from PRD Section 4 use cases]

### Pour qui c'est PAS
[Bullet list of NON-audiences — derived from PRD Section 12.3 anti-features + Section 2 personas-not-served]

### Memo rule
[1-line takeaway "si X → Y", helps newcomer remember]

---

## 📊 Pour PMO / executive

### En 1 phrase business
[Business framing, derived from PRD Section 1.1 + ROI implications]

### Pourquoi c'est stratégique
[Table : business dimension × without × with]

### Effort + ROI
[Effort visible from PRD Section 8 sub-plans + Section 9 roadmap]

### Sponsor
[From PRD frontmatter `owner:` + related_decisions context]

### Risk top 3 (PMO concern)
[Subset of PRD Section 11 risks, focused on probability MED+ × impact MED+]

---

## 🔧 Pour engineer (technical)

### Stack technique
[Table derived from PRD Section 7.1 + 7.2 + 7.3]

### Architecture (ASCII)
[Same or simplified ASCII from PRD Section 7.5/7.7]

### Comment contribuer
[Bullet/table : action × how — derived from PRD Section 8 sub-plans + repo conventions]

### Integration points clés
[Derived from PRD Section 6 complementarity table]

---

## 🌐 Pour external (clients / audit)

### Capabilities
[Customer-facing capability list — derived from PRD Section 4]

### Security posture
[Table : area × implementation — derived from PRD Section 10 EA1-EA9]

### Multi-tenant readiness (if applicable)
[If product is multi-tenant — derived from PRD Section 7.6 + related_decisions]

### Pour évaluer
[Action × comment — derived from PRD Section 4.3 use cases external + cross-references]

---

## 🆚 {Product} vs {Related} (if applicable)

[Cross-product comparison table — only if PRD has Section 6 complementarity entries suggesting confusion risk. Example: ATLAS vs Brain, Synapse vs Brain, AXOIQ Platform vs Cloud Portal]

---

## 📚 Aller plus loin

[Table : lecture × cible audience — cross-refs to PRD, ROADMAP, ADRs, sibling NARRATIVE files]

---

*🎓 Generated by `product-narrative-generator` skill v1.0.0 on {date}. Source authoritative: PRD.md. Audience-balanced multi-section.*
```

## Process (4 Phases with HITL)

### Phase 1: Source Loading

1. Read PRD.md (assert file exists)
2. Parse frontmatter → extract `related_decisions`, `version`, `status`, `owner`
3. Read related decisions/*.md
4. Read CLAUDE.md if exists
5. Read ROADMAP.md
6. Read docs/AXOIQ-OVERVIEW.md + docs/AXOIQ-EXPLAINED.md (ecosystem context)

### Phase 2: Structure Planning (HITL #1)

Present in chat to user :
1. Product identified : `{product}`
2. Audience scope : `{audience}` (multi / specific)
3. Style : `{style}` (analogy-first / use-case-first / comparison-first / formal)
4. Length target : `{length}` (short / medium / long)
5. Cross-product comparisons detected (if any) :
   - Example : if generating Brain narrative, suggest including "Brain vs ATLAS" section
   - Example : if generating ATLAS narrative, suggest including "ATLAS vs Brain" section

Ask AskUserQuestion to confirm structure choices.

### Phase 3: Section-by-Section Drafting

For each of the 4 audience sections (newcomer / pmo / engineer / external) :
1. Reference PRD section(s) being used as source
2. Generate audience-appropriate framing (NEW content : analogies, scenarios, framings — but FACTS sourced from PRD)
3. Insert ASCII diagram derived from PRD architecture
4. Insert tables (before/after, situations, dimensions)
5. Cite PRD section in subtle footnote-style if non-obvious sourcing

### Phase 4: Review + Write (HITL #2)

1. Display draft in chat (or summarize per section if too long)
2. Ask user for amendments (audience missing, wrong tone, factually incorrect, etc.)
3. Apply amendments
4. Write to `products/{product}/NARRATIVE.md`
5. Run validate.py to verify frontmatter
6. Cross-link check : grep ADR refs + ROADMAP refs resolve

## Audience-specific Framing Rules

### Newcomer
- Tone : friendly, scaffolded explanations
- Density : low (lots of analogies)
- Visuals : ASCII diagrams + simple tables
- Anti : NO jargon without immediate definition

### PMO / Executive
- Tone : business-focused, ROI-aware
- Density : medium (tables condense info)
- Visuals : effort matrices + risk tables
- Anti : NO code, NO detailed architecture

### Engineer
- Tone : technical peer-to-peer
- Density : high (detailed stack + integration)
- Visuals : architecture diagrams + sequence flows
- Anti : NO oversimplification, OK with technical jargon

### External
- Tone : professional, evaluator-oriented
- Density : medium (capabilities + posture)
- Visuals : capability matrices + security posture tables
- Anti : NO internal jargon, NO speculation on future features

## Cross-product Confusion Detection

When generating narrative, the skill should detect common confusion pairs and add `## 🆚 X vs Y` section if applicable :

| Confusion pair | Trigger | Add section ? |
|----------------|---------|----------------|
| ATLAS Plugin vs Brain | Both have "AI assistant" framing | ALWAYS for both narratives |
| Synapse vs Brain | Both serve G Mining engineers | ALWAYS for both |
| AXOIQ Platform vs Cloud Portal | Both have "platform" in name | ALWAYS for both |
| DevHub vs Cloud Portal | Both are entry points | ALWAYS for both |
| axoiq-workspace vs axoiq-platform | Both have "axoiq" + admin context | ALWAYS for both |

## Audit Trail

Every generation logged to `.atlas/audit/YYYY-MM/narrative-YYYY-MM-DD.jsonl` :

```json
{
  "skill": "product-narrative-generator",
  "version": "1.0.0",
  "product": "brain",
  "audience": "multi",
  "style": "analogy-first",
  "length": "medium",
  "source_prd_sha": "...",  // git SHA of PRD at generation time
  "output_file": "products/brain/NARRATIVE.md",
  "output_lines": 487,
  "generated_at": "2026-05-11T19:15:00-04:00",
  "atlas_session_id": "enchanted-finding-hamming",
  "model_used": "claude-opus-4-7",
  "hitl_gates_passed": ["phase-2-structure", "phase-4-review"]
}
```

## Publishing Integration (Workstream C linkage)

NARRATIVE.md is consumed by **DevHub Knowledge perspective** (Wave 1b post-G0 cutover) :

- API endpoint : `/api/v1/workspace/narratives` (similar to `/api/v1/workspace/diagrams`)
- Frontend rendering : audience selector pills + markdown render with Mermaid + Excalidraw + ⌘K search
- URL pattern : `dev.axoiq.com/knowledge/explained/{product}`

Spec : `axoiq-workspace/products/gmining/diagrams/_specs/devhub-knowledge-narratives-spec.md` (created same session).

## Examples

### Example 1 : Generate Brain narrative

```bash
/atlas narrative brain
```

Workflow :
1. Phase 1 : Loads `products/brain/PRD.md` + related_decisions [0023, 0034, 0035, 0036]
2. Phase 2 : User confirms audience=multi, style=analogy-first, include ATLAS comparison section
3. Phase 3 : Drafts 4 audience sections + ATLAS comparison
4. Phase 4 : User reviews → applies amendments → writes `products/brain/NARRATIVE.md`

### Example 2 : Generate Synapse narrative focused on external audience

```bash
/atlas narrative synapse --audience external
```

Workflow :
1. Phase 1 : Loads `products/synapse/PRD.md`
2. Phase 2 : Style defaults to formal, only external section generated
3. Phase 3 : Focus capabilities + security posture + multi-tenant
4. Phase 4 : Output ~200L external-only NARRATIVE.md

### Example 3 : Regenerate after PRD update (hook-triggered)

Hook : `post-prd-edit` (planned v8.3+)
- Detects PRD.md modification
- Auto-suggests : "Brain PRD was updated. Regenerate NARRATIVE.md ?"
- If yes → runs skill silently → produces diff → user reviews

## Anti-patterns (NEVER do)

- ⛔ **Generate facts from training data** — always source from PRD/CLAUDE.md/ROADMAP/decisions
- ⛔ **Skip HITL gates** — Phase 2 + Phase 4 are NON-NEGOTIABLE
- ⛔ **Duplicate PRD content verbatim** — narrative ≠ summary. Different framing.
- ⛔ **Omit cross-product comparisons** when confusion pair detected
- ⛔ **Speculate on future** — only what's in PRD Section 12 Future planned

## Validation

Post-generation validation :

```bash
# Frontmatter valid
python3 ops/validate.py --strict products/{product}/NARRATIVE.md

# Cross-refs resolve
grep -oE '\[[^]]+\]\([^)]+\.md[^)]*\)' products/{product}/NARRATIVE.md | check_links

# Audience sections present
grep -c "^## 👋 Pour un nouveau venu" products/{product}/NARRATIVE.md  # = 1
grep -c "^## 📊 Pour PMO" products/{product}/NARRATIVE.md  # = 1
grep -c "^## 🔧 Pour engineer" products/{product}/NARRATIVE.md  # = 1
grep -c "^## 🌐 Pour external" products/{product}/NARRATIVE.md  # = 1
```

## Future Enhancements (v1.1+)

- Audience-specific NARRATIVE files (NARRATIVE-newcomer.md, NARRATIVE-pmo.md, etc.) instead of single multi-section file — toggle via skill config
- Auto-translate FR ↔ EN (i18n)
- Diagram generation : Mermaid blocks for product architecture (not just ASCII)
- Hook integration : `post-prd-edit` auto-suggest regenerate
- Batch mode : `/atlas narrative all` generates all 10 products
- Audience customization : per-tenant narratives (Eldorado-specific framing post-multi-tenant)

---

*🎓 product-narrative-generator skill v1.0.0 — Generates pedagogical NARRATIVE.md from authoritative PRD.md. Multi-audience by default. HITL-gated. Audit-trailed. Designed for AXOIQ ecosystem onboarding + external evaluator pitching. Validated 2026-05-11 via manual narrative creation for brain + atlas-plugin (template-v1 source).*