create-usecase-description

name	create-usecase-description
description	Creates a use-case description page under guidance_layer/website/content/docs/use-cases/ following the established GAIK format (business layer → strategy → no-code → code-based → components → evaluation → resources). Accepts user-provided context and marks any missing sections as Coming Soon. Updates meta.json to register the new page.
argument-hint	[use-case-name] [context: components, workflow, business value, demo link]

Create Use-Case Description

Generates a use-case documentation page under guidance_layer/website/content/docs/use-cases/ following the structure and style established by incident-reporting.mdx (gold-standard reference — read it before generating any content).

Requires user-provided context — the user supplies the use-case details (business value, workflow, components, example output, demo link). This skill structures and formats that content into a properly formatted MDX page. It does not invent content beyond what the user provides.

Handles both new pages and stub promotion — if a Coming Soon stub already exists for this use case, it promotes it to a full page.

---

What this skill creates

File	Action
guidance_layer/website/content/docs/use-cases/{slug}.mdx	Create (new) or promote (stub → full)
guidance_layer/website/content/docs/use-cases/meta.json	Update if slug not yet registered

---

Workflow

Phase 1 — Context Parsing

1. Read incident-reporting.mdx — the gold-standard reference. Understand its exact structure, heading names, value-type format, diagram style, step format, and evaluation link format before generating anything.
2. Derive the page slug from the use-case name (lowercase, hyphens, e.g. construction-site-diary-creation).
3. Check whether a .mdx file already exists for this slug:
   • Fully documented → warn the user and ask for explicit confirmation before overwriting.
   • Stub → proceed; the stub will be replaced.
   • Does not exist → create new.
4. Map the user-provided context against the required and optional sections defined in references/mdx-template.md.
5. For each section where no context was provided, ask:

   "No content for [Section Name]. Supply it now, or mark it Coming Soon?"

   • User supplies → incorporate before generating.
   • User skips → section gets <Callout type="warn">**Coming Soon:** [one-sentence placeholder]</Callout>
6. Ask once: "Is there a live demo link to include?"
   • If yes → add <Callout type="info"> with the link near the end of the Software Module section, matching the incident-reporting pattern.

Phase 2 — Outline

Present a section-by-section status table before writing anything:

Section                                    Status
────────────────────────────────────────── ──────────
Frontmatter + H1 heading                   ✅
Intro paragraph                            ✅ / Coming Soon
Business layer                             ✅ / Coming Soon
Strategy layer                             ✅ / Coming Soon
Implementation — No-Code                   ✅ / Coming Soon
  (Structure A: single asset)              or
  (Structure B: Prompt-based + Claude Skill)
Implementation — Code-Based (diagram)      ✅ / Coming Soon
Software Components (N GAIK components)    ✅ / Coming Soon
  Downstream tasks subsection              ✅ / omit
Defining What to Extract                   ✅ / omit
Software Module (diagram + outputs)        ✅ / Coming Soon / omit
Adaptable to Other Domains                 ✅ / Coming Soon
Evaluation Methods                         ✅ / Coming Soon
Related Resources                          ✅
meta.json                                  update / no change needed

Phase 3 — Plan Review (never skip)

Present the outline to the user and wait for explicit approval before writing any files. Adjust based on feedback.

Phase 4 — Generate Content

Run both sub-steps in order. Do not commit.

4a — MDX Page

Follow references/mdx-template.md for the exact section order, heading names, and formatting rules. All diagrams follow references/mermaid-guide.md.

Opening (before first H2):

---
title: {Use Case Display Name}
description: {One-sentence description}
---
# {Use Case Display Name} Generic Use Case (Cross-Cutting Use Case)

{1–2 sentence business context intro.}

The H1 heading always ends with "Generic Use Case (Cross-Cutting Use Case)".

Business layer (## Business layer – use case specification):

• Opening paragraph describing what the use case covers and who the users are
• Bullet list: "Concrete example fragments reflected in the use case design include:" — 3–5 bullets describing the scenario
• Closing sentence explaining what the canvas provides
• Canvas image reference: ![GenAI Product Description for {Use Case}](/images/{filename}.png) — if image provided
• PowerPoint download link — if provided

Strategy layer (## Strategy layer – value evaluation and monitoring):

• Link to the Value Evaluation Framework
• Value type blocks, each formatted exactly as:

  {Value type} value (primary / secondary):
  "Fragment 1", "Fragment 2", "Fragment 3"
  → Outcome: {outcome sentence}
  

  Use however many value types the user-provided value model contains — the model may include 3 (Functional, Informational, Emotional) or up to 5–6 (also Financial, Social, Operational, etc.). Do not limit to exactly 3.
• Value evaluation image — if provided
• PowerPoint download link — if provided
• Closing sentence about using the model before and after deployment

Implementation — No-Code (## Implementation layer using No-Code):

This section can take two different structures depending on what no-code assets exist for the use case.

Structure A — Single asset (one Claude Skill or one set of prompt templates):

• Opening paragraph
• Numbered list of 1–3 GitHub asset links (prompt templates, agent skills)
• Explanation of what the no-code assets do
• "What the business user sets up (once):" — prose + bullet list
• "What happens in daily work:" — numbered steps with bold **Step N – description** headers and nested bullets
• "Example of what the business gets out:" — intro sentence + structured bullet list of output fields
• Closing 4-bullet list: easy to paste / safe to store / reliable for analytics / suitable for audits

Structure B — Two co-existing approaches (prompt-based AND Claude Skill):

• Opening paragraph introducing both approaches and when to use each
• ### Prompt-based approach subsection — describe the prompt(s) briefly, what they do, GitHub link
• ### Claude Skill subsection — brief introduction (2–4 sentences) covering what it does, when to prefer it over the prompt-based approach, and GitHub link; do not include detailed setup steps or daily workflow — link to the documentation instead
• Use "Claude Skill" as the term — not "Claude Desktop agent skill", not "Claude Desktop Skill"

Use Structure B when both implementation_layer/no-code-assets/prompts/ and implementation_layer/no-code-assets/agent-skills/ assets exist for the use case. Use Structure A for all other cases.

Implementation — Code-Based (## Implementation Layer Using Code-Based Method.):

• Note: heading ends with a period — match exactly
• 1–2 sentence overview naming the GAIK components used and noting any downstream (non-GenAI) steps
• flowchart LR Mermaid diagram with subgraph for the GAIK extraction pipeline — follow references/mermaid-guide.md diagram style (emojis, stroke colors, subgraph pattern)
• If the pipeline output feeds into downstream org-specific steps (pricing, ERP, document generation), add a downstream node after the GAIK output in the diagram, styled yellow (fill:#fefce8) or green (fill:#dcfce7), and labelled clearly as downstream/org-specific
• --- divider after this section

Software Components (## Software Components):

• Only list actual GAIK software components — i.e. classes/modules from implementation_layer/src/gaik/software_components/ or software_modules/. Do NOT list business-specific logic (pricing calculators, PDF renderers, ERP connectors) as software components — these belong in the "Downstream tasks" subsection instead.
• One ### per component, numbered: ### 1. ComponentName
• Each component gets:
  1. 2–3 sentence description
  2. flowchart LR or flowchart TD Mermaid diagram with subgraph — use emojis and stroke colors
  3. GitHub source link: > 📁 [\path/to/component/`](https://github.com/GAIK-project/gaik-toolkit/tree/main/...)`
  4. --- divider after each component

Downstream tasks (### Downstream tasks) (add when the use case involves post-extraction non-GenAI steps):

• Add this unnumbered subsection after the last software component when the pipeline output feeds into business-specific or conventional (non-AI) processing steps
• Describe what happens to the structured output: price calculation, document generation, ERP integration, database storage, etc.
• Clarify that these steps are outside the GenAI pipeline and may require organisation-specific customisation
• Do NOT add a diagram for downstream tasks — prose only

Defining What to Extract (## Defining What to Extract: User Requirements) (include when the use case involves schema-guided extraction with user-defined fields; omit for other use cases):

• 1–2 sentence intro explaining that fields are specified in plain language
• Plain-text code block showing the field specification in the exact format used in incident-reporting.mdx (field name + optional constraint in brackets, followed by output rules)
• Output rules as a bullet list inside the code block

Software Module (## Software Module: {ModuleName}) (if a combined GAIK module is used):

• 1–2 sentence description
• flowchart TD Mermaid diagram with nested subgraphs (Step 1, Step 2 pattern) — follow incident-reporting pattern
• Example output: if screenshot images are available, use side-by-side JSX:

  <p>
    <img src="/gaik-toolkit/images/image1.png" alt="..." style={{ width: "45%", height: "auto", display: "inline-block" }} />
    <img src="/gaik-toolkit/images/image2.png" alt="..." style={{ width: "45%", height: "auto", display: "inline-block" }} />
  </p>
  

• GitHub module and examples links with 📁 prefix
• Demo link as inline text: "To test ... please visit the GAIK demo link"
• --- divider after this section

Adaptable to Other Domains (## Adaptable to Other Domains):

• 1 sentence framing
• Single bullet line listing 3–5 domains, comma-separated
• --- divider after

Evaluation Methods (## Evaluation Methods):

• Opening sentence: "The quality of this use case is evaluated by assessing each software component independently:"
• One ### per evaluator. Each gets:
  • 1–2 sentence description of what is measured and the key metric
  • > 📊 **{Title}:** [\path/`](https://github.com/GAIK-project/gaik-toolkit/tree/main/evaluation_layer/eval_methods/{folder}/)` link
• --- divider after

Related Resources (## Related Resources):

• 2-column Markdown table — | Resource | Link | — NOT 3 columns
• List all key components, modules, examples, canvas, and implementation layer overview

General rules:

• --- horizontal dividers between all major H2 sections
• Missing sections → <Callout type="warn">**Coming Soon:** [placeholder]</Callout>

4b — Update meta.json

If the slug is not already in guidance_layer/website/content/docs/use-cases/meta.json, insert it in the pages array at the appropriate position.

Phase 5 — Verification Summary

After writing, print:

Files created / modified:
  ✓ guidance_layer/website/content/docs/use-cases/{slug}.mdx  (N lines)
  ✓ guidance_layer/website/content/docs/use-cases/meta.json   (updated / unchanged)

Sections marked Coming Soon: [list or "none"]

To verify:
  cd guidance_layer/website && pnpm dev
  → /use-cases/{slug}   (confirm renders, all Mermaid diagrams visible)

---

Hard Rules

• Never skip Phase 3. Always wait for explicit approval before writing any files.
• Never overwrite a fully-documented page without explicit user confirmation.
• meta.json slug must exactly match the .mdx filename (minus .mdx). A mismatch silently breaks sidebar navigation.
• <Callout type="warn"> only for Coming Soon sections. Use <Callout type="info"> for demo links and helpful tips.
• Do not commit. Leave all changes uncommitted for user review.
• Do not fabricate content. Only generate diagrams, code, and prose derivable from the user-provided context. Generic placeholders must be clearly marked.
• Mermaid must use flowchart keyword (not graph). Use subgraphs, emojis in labels, and stroke: colors per references/mermaid-guide.md. Test mentally that all node IDs are unique and subgraph blocks are closed.
• H1 heading always ends with "Generic Use Case (Cross-Cutting Use Case)".
• Related Resources table is 2 columns (Resource | Link), not 3.
• Use cases must be generic. Never mention a specific company name, organization name, client name, or proprietary product name. If the user's context references a named organization, replace it with a generic description (e.g. "a manufacturing company", "an enterprise client", "a partner organization"). This applies to all sections.

---

References

• references/mdx-template.md — canonical section order, heading names, value-type format, diagram templates, evaluation link format
• references/mermaid-guide.md — flowchart syntax, subgraph patterns, emoji usage, stroke color conventions

Pattern references (read before generating — do not skip):

• guidance_layer/website/content/docs/use-cases/incident-reporting.mdx — gold-standard reference; follow its structure, style, and diagram approach exactly
• guidance_layer/website/content/docs/use-cases/purchase-order-processing.mdx — alternative component set
• guidance_layer/website/content/docs/use-cases/dental-transcription-close-captioning.mdx — shorter format