AI Prompting & Disclosure

Key Terms

• LLM — An AI that reads and writes text (like Claude or ChatGPT); used here to write stories, translate, and fix errors
• Twee — A simple text format for writing Twine stories; you type :: for new scenes and [[brackets]] for choices
• DALL-E 3 — An AI by OpenAI that draws pictures from written descriptions; used for course illustrations
• Harlowe — The default story engine for Twine 2, controlling how stories look and behave
• IFID — A unique ID for each Twine story version, like a serial number so no two stories get mixed up

SisterShield integrates AI at several points in the content pipeline. This page documents each AI feature, the models used, safety controls, and the ethical boundaries between human-authored and AI-generated content.

AI Features Overview

Feature	Model	Code Location	Purpose	Safety Controls
Story Generation	Claude Sonnet / GPT-4o	src/lib/llm/generate-story.ts	Generate Twee 3 interactive stories	Structured output, validation, mandatory safety passages
Metadata Translation	Claude Sonnet / GPT-4o	src/lib/llm/translate.ts	Translate course titles and descriptions	JSON output parsing, fallback to original
Full Story Translation	Claude Sonnet / GPT-4o	src/lib/llm/translate.ts	Translate entire Twee stories (en-US / ko-KR)	Passage name preservation rules, IFID regeneration
Batch Translation	Claude Sonnet / GPT-4o	src/lib/llm/translate.ts	Translate multiple courses’ metadata in one call	Array output parsing, per-item fallback
Error Fixing	Claude Sonnet / GPT-4o	src/lib/llm/fix-twee-errors.ts	Repair dead links, duplicates, orphans in Twee	Programmatic detection first, LLM repairs only flagged errors
Image Prompt Generation	Claude Sonnet / GPT-4o	src/lib/llm/generate-image-prompts.ts	Create DALL-E 3 prompts with style consistency	No minors, no violence, character age 18-22, passage name validation
Image Generation	DALL-E 3 (OpenAI)	src/lib/llm/client.ts (generateImage)	Generate illustrations for course passages	Safety prepend in prompts, content policy enforcement by DALL-E

Provider Abstraction

The LLM_PROVIDER environment variable controls which text LLM backend is used. The abstraction lives in src/lib/llm/client.ts.

LLM_PROVIDER=anthropic  -->  Claude Sonnet (claude-sonnet-4-5-20250929)
LLM_PROVIDER=openai     -->  GPT-4o

The callLLM(systemPrompt, userPrompt, options?) function accepts a system prompt, user prompt, and optional max tokens parameter. It returns the text response as a string. Provider-specific SDK initialization and error handling are encapsulated inside the module.

Image generation always uses OpenAI (DALL-E 3) regardless of the LLM_PROVIDER setting, because Anthropic does not offer an image generation API.

Story Generation

The story generation system (src/lib/llm/generate-story.ts) is the most complex AI feature.

System Prompt Design

The system prompt defines the AI as an “Expert Narrative Designer and Social Impact Consultant” specializing in TF-VAWG prevention. It specifies:

1. Internal planning steps: The LLM outlines TF-VAWG risks, scenario arcs, and dangerous choice placement before writing.
2. Protagonist design: Name, personality, sensory details, internal monologue.
3. Story structure: 20-30 content passages organized into 3-4 scenarios, each addressing a distinct TF-VAWG risk.
4. Dangerous Choice Architecture: Safe choices lead to positive outcomes; dangerous choices lead to mandatory Risk Analysis passages with five components (narrative consequence, technical explanation, real-world fact, safer alternative, retry link).
5. Explore-All pattern: Hub-and-spoke structure for educational choice points where all options are valuable.
6. Ending arc: Reflection, Community Action, Key Takeaways (with UN SDG 5 connection), Quiz (3 questions), Resources.
7. Writing quality: Novel-like engagement with sensory details, dialogue, emotional progression.
8. Markup constraints: Only Twee 3 link syntax, headings, bold, and bullets. No Harlowe macros or variables.

Output Validation

After receiving the LLM response, the system:

1. Strips markdown code fences if present.
2. Repairs StoryData JSON (trailing commas, whitespace).
3. Validates the Twee source structure (calls validateTweeSource()).
4. Extracts the story title from the :: StoryTitle passage.
5. Generates bilingual metadata via a follow-up translation call.

Post-Processing

If the LLM output fails validation, the error is logged and an exception is thrown. The UI can then prompt the teacher to retry generation.

Translation

Metadata Translation (ensureBilingualField, ensureBilingualMetadata)

Ensures that titleI18n and descriptionI18n fields have values for both en-US and ko-KR. If one locale is missing, the LLM translates from the available one. Falls back to the original text if translation fails.

Batch Metadata Translation (batchTranslateMetadata)

Groups courses by translation direction (needs Korean vs needs English), then sends a single LLM call per direction with all items numbered. Parses the JSON array response and maps translations back to items.

Full Story Translation (translateTweeSource)

Translates an entire Twee 3 story while preserving:

• Passage names (kept in English for technical compatibility).
• StoryData JSON block (copied verbatim).
• Link targets in [[Display Text->PassageName]] syntax (only display text is translated).
• All formatting (headings, bold, bullet lists).

A new IFID is generated for each translated version to ensure uniqueness.

Image Generation

Prompt Generation Pipeline

1. The Twee source is parsed into passages.
2. StoryData, StoryTitle, Resources, and Quiz passages are excluded.
3. The LLM analyzes all content passages and produces:
   • A style directive (single sentence defining the unified art style).
   • A character roster (fixed visual persona for each recurring character).
   • 8-12 image prompts (one per selected passage, embedding the style directive and character descriptions).

Safety Constraints in Image Prompts

The system prompt for image generation enforces:

• Age floor: All characters depicted as young adults (18-22), even if the story describes teenagers.
• No violence: No weapons, nudity, drugs, horror, or inappropriate content.
• No threatening content: Show emotional response or safe action, never the threat itself.
• No text in images: Prevents confusing or misleading text artifacts.
• Modest clothing: College campus appropriate.

DALL-E 3 Generation

The generateImage() function in src/lib/llm/client.ts sends prompts to DALL-E 3 with response_format: 'b64_json' and returns the image as a Buffer. The default size is 1024x1024.

Error Fixing

The error fixing pipeline combines programmatic detection with AI repair:

1. Detection (src/lib/twine/detect-errors.ts): Scans the Twee source for dead links (links to nonexistent passages), duplicate passages (same name defined twice), and orphan passages (unreachable from Start).
2. Repair (src/lib/llm/fix-twee-errors.ts): Sends the Twee source and the list of detected errors to the LLM. The LLM creates missing passages, merges duplicates, and adds links to orphans while preserving all existing content.
3. Output: A JSON object with fixedSource (complete corrected Twee) and summary (array of fix descriptions).

Disclosure Statement

What AI Generates

• Interactive story content (narrative, dialogue, choices, risk analysis passages, quiz questions, resource listings).
• Translations of story content and metadata.
• Image prompts and illustrations.
• Fixes for structural errors in Twee stories.

What the Team Authored

• The prompt architecture: system prompts, output format specifications, validation rules, and safety constraints.
• The educational framework: TF-VAWG risk categories, the Dangerous Choice Architecture, the CBT-inspired skill-building approach, the connection to UN SDG 5.
• The safety constraints: no victim-blaming, mandatory recovery paths, age requirements for illustrations, real crisis resources.
• All application code: the LLM client, Twine pipeline, database schema, UI components, and API routes.
• The design system, authentication, and privacy controls.

”Original Logic” Explanation

The team designed the complete system of constraints within which AI operates. The AI generates content, but the educational methodology, safety guardrails, output structure, and quality criteria are human-authored. The AI is a content generation tool operating within a human-designed framework, not an autonomous decision-maker.

Ethical Considerations

1. AI as tool, not replacement: AI generates educational content under strict constraints. Teachers review and can edit all generated content before it reaches students.
2. Transparency: This documentation openly describes how AI is used, what prompts are given, and what safety controls exist.
3. No hidden reasoning: The system uses structured output formats (Twee 3, JSON). There is no hidden chain-of-thought that could contain harmful content. All LLM output is either displayed to the teacher or validated programmatically.
4. Human oversight: Generated stories are saved as drafts. A teacher must review and publish them before students can access them.
5. Fallback behavior: If LLM calls fail, the system falls back gracefully (original text for translation, error messages for generation). No silent failures.

Prompt Evolution Appendix

This section documents the iterative evolution of SisterShield’s story generation prompt — from a naive first attempt to the production system described above. Each version demonstrates what was learned and what design elements were added to solve specific problems.

Version 1: Naive Prompt

The first attempt was a simple, unstructured instruction:

You are a story writer. Write an interactive story about online safety
for teenage girls. Use Twee 3 format. Include choices that lead to
different outcomes. Add a quiz at the end.

Problems with Version 1:

#	Problem	Consequence
1	No protagonist design	Generic, forgettable characters with no sensory detail
2	No TF-VAWG specificity	Stories about vague “online safety” rather than specific threats
3	No safety constraints	LLM generated graphic descriptions of abuse
4	No structural requirements	Unpredictable story length (5-50 passages)
5	No educational framework	Choices were “right/wrong” with no learning content
6	No output validation rules	Invalid Twee syntax, broken links, Harlowe macros
7	No crisis resources	Stories ended without connecting users to real help

Version 2: Structured but Incomplete

The second iteration added structure but still lacked critical safety and educational elements:

You are an educational story designer specializing in digital safety.

Write a Twee 3 interactive story with:
- A named protagonist (female, college-age)
- 3 scenarios about different types of online threats
- 20-25 passages
- Choices that lead to safe or unsafe outcomes
- A quiz section at the end with 3 questions
- A resources section with helpline numbers

Format: Use only [[Display->Target]] link syntax. No Harlowe macros.

Remaining Problems:

#	Problem	Why Version 2 Didn’t Solve It
1	No internal planning step	LLM jumped straight to writing without outlining risks
2	No dangerous choice architecture	”Unsafe outcomes” were dead ends, not learning moments
3	No recovery paths	Wrong choices punished the user instead of educating
4	No image safety constraints	No guidance for age-appropriate visual content
5	No explore-all pattern	Linear structure missed hub-and-spoke learning opportunities

Version 3: Production Prompt

The production prompt (documented in the Story Generation section above) addresses every identified problem. The table below maps each design element to the specific problem it solves:

Design Element	Problem Solved	How
Internal planning steps	Unstructured output	LLM outlines TF-VAWG risks and scenario arcs before writing
Protagonist design spec	Generic characters	Name, personality, sensory details, internal monologue required
20-30 passage structure	Unpredictable length	Explicit passage count range with 3-4 scenario organization
Dangerous Choice Architecture	Dead-end wrong choices	Safe → positive outcomes; dangerous → Risk Analysis passages with 5 mandatory components
Recovery paths	Punishing wrong choices	Every Risk Analysis passage includes “Let me think again” retry link
Explore-all pattern	Linear-only structure	Hub-and-spoke for educational choice points where all options teach
Ending arc specification	Missing educational closure	Reflection → Community Action → Key Takeaways (SDG 5) → Quiz → Resources
Markup constraints	Invalid syntax	Only Twee 3 links, headings, bold, bullets; no Harlowe macros or variables
Crisis resource mandate	No real help connections	Every story must end with verified Korean hotlines and international organizations

What This Evolution Demonstrates

1. Iterative engineering: Each version was tested, failures were documented, and specific design elements were added to address each failure. This is prompt engineering as a disciplined practice, not trial-and-error.
2. Safety-by-design: Safety constraints were not an afterthought — they were the primary driver of prompt evolution from Version 1 to Version 3. The shift from “punishing wrong choices” to “educating through Risk Analysis passages” required rethinking the entire story architecture.
3. Educational framework integration: The connection between interactive storytelling and TF-VAWG education is not generic. The Dangerous Choice Architecture, explore-all pattern, and mandatory ending arc are original educational design elements.
4. Technical depth: The production prompt generates structured output (Twee 3) that passes programmatic validation, integrates with a Twine parser/builder pipeline, and produces content that can be automatically translated while preserving passage links.

Rubric Connection: Technical

This prompt evolution is direct evidence for the Technical rubric category. It demonstrates that AI integration in SisterShield is not “plug in an API” — it is a carefully engineered system where each prompt design element solves a documented problem.