Help System Architect Skill

Help System Architect

Design and generate the in-app help system for Raamattu Nyt and IdeaMachina.

Authority

Consumes Docs/ai/core-user-model.json as the single source of truth for tasks and paths
NEVER redefines tasks or paths — only explains, guides, and contextualizes them
The core-ux-detective skill owns task/path definitions; this skill owns help presentation

Two Systems

1. Havainnepolku (Visual Guidance Path)

Interactive step-by-step navigation bar. See references/component-specs.md for specs.

Package: packages/help-guide/ with GuidancePath.tsx, HelpModeProvider.tsx, useHelpMode.ts, HelpTooltip.tsx, HelpSearchIndex.ts.

2. Database FAQ System (faq_items)

Database-driven Q&A pairs with search, per app. Already built:

| Component | Location | |-----------|----------| | Table | public.faq_items — system_id, question_fi/en, answer_fi/en, category, keywords[] | | Hook | src/hooks/useFaq.ts — useFaq() fetches by system_id + published | | Display | src/components/feedback/FaqSection.tsx — accordion, grouped by category, search bar | | Admin | /ohjaamo/faq — create/edit/delete, multi-language, publish toggle | | Page | /ohjeet (HelpPage.tsx) renders <FaqSection /> |

Categories: general, account, billing, features, troubleshooting, privacy, audio, ai

Workflow

Choose scope from user request:

| Request | Action | |---------|--------| | "Generate FAQ" / "Q&A pairs" | → FAQ Generation workflow below | | "Build help system" | → Full system (havainnepolku + FAQ) | | "Havainnepolku only" | → GuidancePath component | | "Help content" | → Help pages for specific tasks | | "Search index" | → Keyword-to-task mapping |

FAQ Generation Workflow

See references/faq-generator.md for the complete FAQ generation guide including:

Schema reference and insert patterns
Feature discovery workflow (scan routes, pages, tabs)
Category mapping templates
Starter Q&A sets for Raamattu Nyt (31 pairs) and IdeaMachina (13 pairs)
Keyword optimization for search

Quick steps:

Discover — Scan app routes and pages to list features
Categorize — Map features to FAQ categories
Generate — Create Q&A pairs (2-4 per feature, fi + en)
Keywords — Add 3-6 search keywords per pair (fi + en)
Insert — SQL migration or direct execute_sql
Verify — Count by system_id + category, target 30-60 per app

Havainnepolku Workflow

Read Docs/ai/core-user-model.json (run core-ux-detective if missing)
Generate GuidancePath data from user_paths
Build components per references/component-specs.md

Help Content Generation

For each task/path, generate content in Finnish:

{
  "task_id": "create_reel",
  "title": "Reelsin luominen",
  "what": "Luo kaunis kuvajae Raamatun jakeesta.",
  "when": "Kun haluat jakaa jakeen someen kuvana.",
  "steps": ["Valitse jae", "Paina 'Luo reels'", "Valitse tyyli", "Julkaise"]
}

Rules

All user-facing text in Finnish (with English translations in _en fields)
Calm, supportive, non-technical tone
Short answers: 2-4 sentences max
Keywords: include both Finnish and English terms
FAQ search works via question, answer, and keywords[] fields
Help mode is non-blocking — user can always dismiss
Components in packages/help-guide/, FAQ data in faq_items table

Output Files

| File | Purpose | |------|---------| | packages/help-guide/src/*.tsx | Shared havainnepolku components | | faq_items table | Database-driven FAQ (via migration or MCP) | | apps/.../components/help/HelpPage.tsx | Help page (already exists at /ohjeet) |

Agent Skills: Help System Architect

Install this agent skill to your local

Skill Files