Create Usecase Description

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

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):