User Story erstellen

Guide the user through creating a well-structured user story that can be used as a prompt for Claude Code to implement with Test-Driven Development (TDD).

When to Use This Command

• Planning and documenting new features
• Preparing user stories for TDD implementation
• Capturing requirements in a structured format
• Creating stories for Linear tickets or documentation

Related Commands

Command	Purpose
/lt-dev:fix-issue	Work on an existing Linear issue

Workflow: Create story → Save to Linear → /lt-dev:fix-issue to implement

IMPORTANT: The generated story and all user-facing communication must ALWAYS be in German, regardless of the user's input language. Exceptions: Properties (camelCase), code snippets, and technical terms remain in English.

ABORT HANDLING: If the user wants to cancel at any point (e.g., "abbrechen", "stop", "cancel", "nicht mehr"), acknowledge it (in German): "Okay, Story-Erstellung abgebrochen." and stop the process.

---

Guidelines for Good Stories

Keep these guidelines in mind when generating the story:

INVEST Criteria (Quality Check)

Every story should be checked against these criteria:

• Independent - Can be implemented without depending on other stories
• Negotiable - Open for discussion and refinement
• Valuable - Delivers real, tangible value to the user (not just technical tasks)
• Small - Completable within a single sprint (if too large, suggest splitting)
• Testable - Has measurable acceptance criteria

3C Model

• Card - Concise title that fits on a notecard
• Conversation - Story emerges from dialogue (Gap Analysis enables this)
• Confirmation - Clear acceptance criteria define "done"

Emotional Narrative

The story should convey the user's emotional experience, not just technical functionality. Ask "Why does this matter to the user?" - use the 5 Whys technique if the reason is unclear.

Title

• Keep short (max 10 words)
• Format: "[Rolle] möchte [Feature], damit [Kurze Begründung]"

Acceptance Criteria

• Aim for 4-8 criteria per story
• Start with action verbs (kann, soll, muss)
• Be specific and measurable - focus on what, not how
• Include both positive and negative cases
• Consider: authentication, authorization, validation, persistence
• Optional Gherkin format for complex criteria:

  Gegeben [Ausgangssituation]
  Wenn [Aktion]
  Dann [Erwartetes Ergebnis]
  

Properties

• Only include if user explicitly specifies them - do not auto-generate
• Use camelCase for property names
• Provide BOTH English AND German descriptions
• Specify relationships clearly (e.g., "Referenz auf User-Entität")

For TDD

• Each acceptance criterion becomes at least one test
• Consider edge cases that need explicit tests
• Think about security tests (permission-denied scenarios)

---

Step 1: Collect Initial Thoughts

Check for argument: If the user provided an initial idea as argument (e.g., /lt-dev:create-story "FAQ Feature"), use that as starting point and skip directly to Step 2.

If no argument provided: Output the following prompt in German and wait for user response:

Bitte beschreibe deine User Story Idee. Teile so viele Details wie möglich mit:

• Wer braucht dieses Feature (Rolle/Nutzertyp)?
• Was soll erreicht werden?
• Warum wird es benötigt?
• Spezifische Anforderungen oder Properties?
• Technische Hinweise?

Schreib einfach deine Gedanken auf - ich helfe dir, sie in eine strukturierte User Story zu bringen.

Wait for the user's response before proceeding to Step 2.

---

Step 2: Analyze and Identify Gaps

After receiving the user's input, analyze it against this checklist:

Required Elements Checklist

Basic Story Elements:

• Role - Who is the user? (Admin, Customer, Guest, etc.)
• Feature - What do they want to achieve?
• Reason - Why do they need this? What's the benefit?

Description Details:

• Context - Background information, which system/module?
• Requirements - Specific functional requirements
• Properties (optional) - Data fields with types (if applicable)
• Notes (optional) - Technical hints, constraints, special logic

Quality Criteria:

• Acceptance Criteria - Testable conditions for success
• Security Considerations - Who can access/modify? (permissions)
• Edge Cases - What happens in special situations?

Gap Analysis

For each missing or unclear element, formulate a specific question in German using the AskUserQuestion tool:

Fehlende Rolle:

• "Wer wird dieses Feature nutzen? (z.B. Admin, Kunde, Gast, Entwickler)"

Fehlendes Feature/Ziel:

• "Was genau soll der Nutzer tun können?"

Fehlende Begründung:

• "Welchen Nutzen bringt dieses Feature? Welches Problem löst es?"

Fehlende Properties (only ask if the feature involves data entities):

• "Welche Daten müssen gespeichert werden? Bitte liste die Properties mit ihren Typen auf (string, number, boolean, Date, enum, Referenz)"

Fehlende Akzeptanzkriterien:

• "Wie können wir überprüfen, dass das Feature funktioniert? Was sind die Erfolgsbedingungen?"

Unklare Sicherheit:

• "Wer soll Zugriff auf dieses Feature haben? Gibt es Berechtigungseinschränkungen?"

Fehlende Edge Cases:

• "Gibt es Sonderfälle zu beachten? Was soll passieren, wenn [konkretes Szenario]?"

Questioning Strategy

1. Ask only about missing/unclear elements - Don't ask for information already provided
2. Be specific - Reference what was said and ask for clarification
3. Group related questions - Ask 2-4 questions at once, not one by one
4. Suggest improvements - If something seems incomplete, suggest additions
5. Accept refusal gracefully - If the user refuses to answer or provides no input, accept it and make the best of available information

Example question (in German): "Deine Story-Idee ist klar bezüglich des Grundfeatures. Ich brauche noch ein paar Details:

1. Du hast erwähnt, dass Admins Items verwalten können - können Gäste sie auch sehen?
2. Sollen die Items eine bestimmte Reihenfolge/Position haben?
3. Was passiert, wenn jemand versucht, ein Item zu löschen, das anderswo referenziert wird?"

If user refuses or skips questions:

• Accept the decision without pushing further
• Proactively suggest reasonable completions based on context and common patterns
• Present suggestions to the user for confirmation before including them
• Proceed with available information after user confirmation

Proactive Suggestion Strategy

When the user doesn't provide information for certain areas, don't just leave gaps - actively suggest sensible completions:

For missing Role:

• Analyze the feature context to infer the most likely user role
• Suggest: "Da es um Verwaltungsfunktionen geht, nehme ich an, dass ein Admin diese nutzen soll. Passt das?"

For missing Reason/Benefit:

• Derive the benefit from the feature's purpose
• Suggest: "Der Nutzen könnte sein: damit Besucher schnell Antworten auf häufige Fragen finden. Soll ich das so übernehmen?"

For missing Properties:

• Do NOT automatically suggest properties if the user hasn't specified any
• Only include properties in the story if the user explicitly provides them
• If the user mentions data fields vaguely, ask for clarification: "Du hast [Datenfeld] erwähnt. Möchtest du die Properties genauer spezifizieren, oder soll das der Implementierung überlassen werden?"
• If the user declines to specify properties, omit the Properties section entirely - the implementation agent will determine appropriate properties based on the requirements

For missing Acceptance Criteria:

• Generate standard criteria based on the feature type (CRUD → list, create, read, update, delete permissions)
• Suggest: "Ich schlage folgende Akzeptanzkriterien vor: [Liste]. Möchtest du welche anpassen oder ergänzen?"

For missing Security/Permissions:

• Suggest common permission patterns based on the role
• Suggest: "Ich würde vorschlagen: Admins haben vollen Zugriff, Gäste können nur lesen. Ist das korrekt?"

For missing Edge Cases:

• Suggest typical edge cases for the feature type
• Suggest: "Mögliche Edge Cases wären: Was passiert bei leeren Eingaben? Bei Duplikaten? Bei Löschung referenzierter Daten?"

Suggestion Format (in German): "Für [Bereich] schlage ich vor: [konkreter Vorschlag]. Passt das so, oder möchtest du etwas ändern?"

Important:

• Always present suggestions as proposals, not decisions
• Let the user confirm, modify, or reject each suggestion
• If the user confirms with just "ja", "ok", "passt", accept the suggestion and proceed
• Integrate confirmed suggestions directly into the story - the final story should only contain definitive requirements, not assumptions or proposals
• The user should be able to review the complete story and request changes before finalizing

---

Step 3: Validate Completeness

Once all information is gathered, perform a final validation:

INVEST Check

• Independent: Does this story depend on other stories? If yes, note dependencies or suggest splitting.
• Valuable: Is the user value clear? If the "damit" part is weak, use 5 Whys to dig deeper:
  • "Warum ist das wichtig?" → Answer → "Und warum ist das wichtig?" → repeat until real value emerges
• Small: Can this be completed in one sprint? If too large, suggest splitting into smaller stories (in German):
  • "Diese Story scheint recht umfangreich. Sollen wir sie in kleinere Stories aufteilen?"
• Testable: Are all acceptance criteria measurable and verifiable?

Coherence Check

• Does the feature make sense as described?
• Are the requirements internally consistent?
• Do the acceptance criteria cover all requirements (aim for 4-8)?
• Are there any contradictions?

Emotional Value Check

• Does the story convey why this matters to the user?
• Is it more than just a technical task?
• If the narrative feels dry, ask (in German): "Was ist der eigentliche Nutzen für den Anwender? Welches Problem wird gelöst?"

TDD Readiness Check

• Can each acceptance criterion be converted to a test?
• Are the properties clear enough for implementation?
• Is the security model defined?

If issues found: Ask clarifying questions (in German) before proceeding.

If complete: Proceed to Step 4.

---

Step 4: Generate and Present Story

Generate the complete user story in the standard format and present it to the user first.

Display the story in a clearly marked code block so the user can:

• Review and discuss the story
• Request changes or optimizations
• Copy it if needed

After presenting the story, ask (in German): "Ist die Story so in Ordnung, oder möchtest du noch etwas anpassen?"

If changes requested: Make the adjustments and present the updated story again.

If approved: Proceed to Step 5 (Ask for Output Format).

Story Format (German)

# [Titel - Rolle möchte Feature, damit Begründung]

**Story:** Als [Rolle] möchte ich [Feature], damit [Begründung].

## Beschreibung

[Ausführliche Beschreibung]

### Kontext
[Hintergrund und Systemkontext]

### Anforderungen
[Liste der spezifischen Anforderungen]

### Properties (optional - nur wenn vom Nutzer explizit angegeben)

| Property   | Type   | Required | Description (EN)   | Beschreibung (DE)    |
|------------|--------|----------|--------------------|----------------------|
| example    | string | yes      | Example property   | Beispiel-Eigenschaft |

[Diesen Abschnitt komplett weglassen, wenn der Nutzer keine Properties angegeben hat]

### Hinweise (optional)
[Technische Hinweise, Einschränkungen, spezielle Logik - nur wenn relevant]

## Akzeptanzkriterien

- [ ] [Testbares Kriterium 1]
- [ ] [Testbares Kriterium 2]
- [ ] [Sicherheitskriterium]
- [ ] [Edge-Case-Kriterium]

---

Step 5: Ask for Output Format

Once the user approves the story, use AskUserQuestion with these 4 options:

Question: "Wie möchtest du mit dieser Story fortfahren?"

Option	Label	Description
1	Neues Linear Ticket	Neues Ticket in Linear erstellen
2	Bestehendes Ticket erweitern	Bereits angelegtes Linear Ticket aktualisieren
3	Markdown-Datei	Story in eine .md-Datei im Projekt speichern
4	Direkt umsetzen	Sofort mit TDD-Implementierung starten

Note: The "Other" option allows shortcuts - see below.

After user selects an option:

• Option 1 (Neues Linear Ticket): Proceed to Step 6, Option 1
• Option 2 (Bestehendes Ticket erweitern):
  • MUST ask for Ticket-ID first: "Bitte gib die Ticket-ID des bestehenden Linear Tickets an (z.B. DEV-123 oder nur 123):"
  • Wait for user response with the ID
  • Then proceed to Step 6, Option 2 with the provided ID
• Option 3 (Markdown-Datei): Proceed to Step 6, Option 3
• Option 4 (Direkt umsetzen): Proceed to Step 6, Option 4
• Other (free text input): Parse the input:
  • Ticket-ID pattern detected (e.g., DEV-123, ABC-456): Proceed directly to Step 6, Option 2 with this ID
  • Number only (e.g., 123, 456): Assume DEV- prefix → Proceed to Step 6, Option 2 with DEV-[number]
  • Anything else (e.g., "nichts", "nein", "abbrechen"): Confirm in German: "Alles klar! Die Story wurde oben angezeigt und kann bei Bedarf kopiert werden." - END

Shortcut hint (optional): After presenting options, you may add: "Tipp: Du kannst bei 'Other' auch direkt eine Ticket-ID eingeben (z.B. 123 für DEV-123)."

---

Step 6: Execute Selected Output

Option 1: Linear Ticket erstellen

Prerequisite: Linear MCP must be installed (lt claude install-mcps linear)

1. First, check if Linear MCP is available. If not, inform the user (in German):

   • "Linear MCP ist nicht installiert. Du kannst es mit lt claude install-mcps linear installieren."
   • Then ask if they want to choose a different output option

2. If Linear MCP is available, ask for Linear project/team (in German):

   • "In welchem Linear Team soll das Ticket erstellt werden?"
   • Use Linear MCP to list available teams to help the user choose
   • If the user provides an invalid team, show available teams and ask again

3. Create ticket via Linear MCP:

   • Title: The story title
   • Description: The full story in markdown format
   • Labels: Add relevant labels if applicable

4. Report the created ticket URL to the user (in German)

5. Then ask (in German): "Möchtest du diese Story jetzt auch mit TDD umsetzen?"

Option 2: Bestehendes Linear Ticket erweitern

Prerequisite: Linear MCP must be installed (lt claude install-mcps linear)

Note: The ticket ID was already collected in Step 5 (either via Option 2 selection or "Other" shortcut).

1. First, check if Linear MCP is available. If not, inform the user (in German):

   • "Linear MCP ist nicht installiert. Du kannst es mit lt claude install-mcps linear installieren."
   • Then ask if they want to choose a different output option

2. Fetch the existing ticket via Linear MCP:

   • Use get_issue to retrieve the current ticket details
   • If the ticket doesn't exist, inform the user (in German): "Ticket [ID] wurde nicht gefunden. Bitte überprüfe die ID."
   • Then ask for a corrected ID or a different output option

3. Show the user the current ticket state (in German):

   • "Aktuelles Ticket [ID]: [Titel]"
   • "Aktuelle Beschreibung: [kurze Zusammenfassung oder 'leer']"
   • Ask: "Möchtest du die Beschreibung vollständig ersetzen oder die Story anhängen?"
   • Options: "Ersetzen" (replace) or "Anhängen" (append)

4. Update the ticket via Linear MCP:

   • Title: Update to the optimized story title (ask user: "Soll der Titel auf '[neuer Titel]' aktualisiert werden?")
   • Description: Replace or append the story in markdown format based on user choice
   • IMPORTANT: Do NOT include the title as a heading in the description to avoid duplication - the description should start directly with the story statement ("Story: Als...")
   • If appending, add a separator: \n\n---\n\n[story content without title heading]

5. Report the updated ticket URL to the user (in German): "Ticket [ID] wurde erfolgreich aktualisiert: [URL]"

6. Then ask (in German): "Möchtest du diese Story jetzt auch mit TDD umsetzen?"

Option 3: Als Markdown-Datei speichern

1. Ask for the file location (in German):

   • "Wo soll die Story gespeichert werden? (z.B. docs/stories/faq-verwaltung.md oder stories/STORY-001.md)"
   • Suggest a filename based on the story title (e.g., stories/admin-faq-verwaltung.md)

2. Validate the path:

   • Check if the parent directory exists
   • If not, ask (in German): "Das Verzeichnis [dir] existiert nicht. Soll ich es erstellen?"
   • If the file already exists, ask (in German): "Die Datei existiert bereits. Überschreiben?"

3. Write the story to the specified file

   • If writing fails, inform the user (in German): "Fehler beim Speichern: [error]. Bitte einen anderen Pfad angeben."
   • Then ask for a new path

4. Confirm (in German): "Story gespeichert unter [Pfad]"

5. Then ask (in German): "Möchtest du diese Story jetzt auch mit TDD umsetzen?"

Option 4: Direkt umsetzen (or TDD after Option 1/2/3)

When the user chooses direct implementation or answers "yes" to TDD after Option 1, 2, or 3:

1. Confirm (in German): "Starte TDD-Implementierung mit dem building-stories-with-tdd Skill..."

2. Invoke the building-stories-with-tdd skill with the generated story as context

3. The skill will handle: test creation, implementation, validation

---

Beispiel: FAQ-Verwaltung Story

Here is an example of a well-structured user story:

User's initial input:

"Ich brauche FAQs die der Admin verwalten kann und die auf der Website angezeigt werden. Die sollen eine Reihenfolge haben."

Gap analysis question (in German):

"Du hast erwähnt, dass FAQs eine Reihenfolge haben sollen. Möchtest du die Properties (z.B. question, answer, position) genauer spezifizieren, oder soll das der Implementierung überlassen werden?"

User response:

"Nein, das kann die Implementierung machen."

Resulting story (suggestions integrated as definitive requirements):

# Admin möchte FAQs verwalten, damit sie auf der Website verfügbar sind

**Story:** Als Admin möchte ich FAQs verwalten können, damit sie allen Besuchern auf der Website zur Verfügung stehen.

## Beschreibung

Es soll ein Modul für FAQs erstellt werden, in dem der Admin FAQs sehen, anlegen, bearbeiten und löschen kann. Nicht eingeloggte Nutzer sollen die FAQs sehen können, damit sie auf der Website dargestellt werden können.

### Kontext
- FAQs sind öffentlich sichtbare Inhalte, die von Administratoren verwaltet werden
- Die Reihenfolge der FAQs ist für die Anzeige wichtig

### Anforderungen
- Admins können vollständige CRUD-Operationen auf FAQs durchführen
- Alle Nutzer (auch Gäste) können FAQs lesen
- FAQs müssen eine bestimmte Reihenfolge haben
- Die Reihenfolgeverwaltung muss automatisch und effizient erfolgen

## Akzeptanzkriterien

- [ ] Administratoren können FAQs vollständig verwalten (GET, POST, DELETE, PUT)
- [ ] Alle Nutzer (auch nicht eingeloggte) können die komplette Liste der FAQs sortiert nach Reihenfolge abrufen
- [ ] Beim Anlegen einer neuen FAQ wird automatisch die nächste Position in der Reihenfolge vergeben
- [ ] Die Reihenfolge der FAQs kann angepasst werden
- [ ] Nicht-Admin-Nutzer können keine FAQs erstellen, bearbeiten oder löschen

Beispiel eines Akzeptanzkriteriums im Gherkin-Format:

Gegeben es existieren bereits 3 FAQs in der Reihenfolge A, B, C
Wenn ein Admin eine neue FAQ D an Position 2 einfügt
Dann ist die neue Reihenfolge A, D, B, C
Und alle anderen FAQs werden entsprechend neu positioniert

---

Execution Summary

1. Collect initial thoughts - Let user describe their idea freely
2. Analyze gaps - Check against required elements checklist
3. Ask targeted questions - Only for missing/unclear elements (in German)
4. Validate completeness - INVEST check, coherence, emotional value, and TDD readiness
5. Generate and present story - Format according to template (in German!) and present for discussion/optimization
6. Ask for output - 4 options: Neues Linear Ticket, Bestehendes Ticket erweitern, Markdown, Direkt umsetzen
   • If "Bestehendes Ticket erweitern": MUST ask for Ticket-ID separately
   • Shortcut: "Other" with Ticket-ID (e.g., 123 → DEV-123) skips extra question
7. Execute choice and offer TDD - Create output in selected format, then offer TDD implementation if not already chosen

Key behaviors:

• User can abort at any point - acknowledge and stop
• Always validate paths/teams before executing
• Handle errors gracefully with German error messages
• "Nichts davon" is a valid choice - story was already displayed

Remember: A well-written user story leads to better tests and cleaner implementation!