/create-user-story

name: create-user-story
description: Create user stories with duplicate checking across any project tracker (Linear, GitHub Issues, Jira)
roles: [product-manager, engineering-lead, founder]
integrations: [linear, github, jira]

COG Create User Story Skill

When to Invoke

• User wants to create a new user story, feature request, or issue
• User says "create story", "new story", "add issue", "write user story", "create ticket"
• User describes a feature or requirement that should be tracked

Agent Mode Awareness

**Check `agent_mode` in `00-inbox/MY-PROFILE.md` frontmatter:**

• If `agent_mode: team` — use parallel agents to check for duplicates across all active trackers simultaneously, then create the story
• If `agent_mode: solo` — check duplicates and create the story sequentially in the main conversation

Command: `/create-user-story`

Pre-Flight Check

1. **Read `00-inbox/MY-INTEGRATIONS.md`** to determine which project trackers are active:

• **Linear** — use Linear MCP tools
• **GitHub** — use `gh` CLI
• **Jira** — use `jira` CLI or Jira API via WebFetch
• If NO tracker is active, save the story as a markdown file in `04-projects/[project]/stories/` and inform the user

2. **Read `00-inbox/MY-PROFILE.md`** to get:

• Active projects (to determine which project/repo/board to target)
• User's name (for story author attribution)

3. **Ask the user** (if not already provided):

• What is the feature or requirement? (free-form description)
• Which project does this belong to? (if multiple active projects)
• Priority level? (optional — default to medium)

---

Execution Strategy

Phase 1: Understand the Request

Parse the user's input to extract:

• **Feature description** — what the user wants built
• **Target users** — who benefits from this
• **Problem statement** — what problem this solves
• **Project context** — which project this belongs to

If the user provides a brief description, ask clarifying questions before proceeding:

• Who is the target user for this feature?
• What problem does this solve?
• Are there any specific acceptance criteria you have in mind?

Phase 2: Duplicate Check

**CRITICAL: Always check for duplicates before creating.**

Team Mode (parallel agents)

Launch duplicate-check agents in parallel using the Task tool with `run_in_background: true`:

**Agent: "duplicate-checker-linear"** (if Linear is active)

Search Linear for potential duplicate issues.
1. Use ToolSearch to load Linear tools
2. Use mcp__claude_ai_Linear_2__list_issues to search for issues with similar keywords
3. Search across all active projects/teams
4. Return any issues that match by title similarity or description overlap

Search terms: [extracted keywords from user's description]
Return: list of potential duplicates with title, status, URL, and similarity assessment

**Agent: "duplicate-checker-github"** (if GitHub is active)

Search GitHub Issues for potential duplicates.
Repository: [CUSTOMIZE: your-org/your-repo]

1. gh search issues "[keywords]" --repo [CUSTOMIZE: your-org/your-repo] --json number,title,state,url,body --limit 20
2. Also search closed issues to check if this was already done:
   gh search issues "[keywords]" --repo [CUSTOMIZE: your-org/your-repo] --state closed --json number,title,state,url --limit 10

Return: list of potential duplicates with title, status, URL, and similarity assessment

**Agent: "duplicate-checker-jira"** (if Jira is active)

Search Jira for potential duplicate issues.
Project: [CUSTOMIZE: YOUR-PROJECT-KEY]

1. Use WebFetch or jira CLI to search:
   JQL: project = "[CUSTOMIZE: YOUR-PROJECT-KEY]" AND text ~ "[keywords]" ORDER BY created DESC
2. Check both open and recently resolved issues

Return: list of potential duplicates with key, title, status, URL, and similarity assessment

Solo Mode (sequential)

Run the same duplicate checks sequentially for whichever tracker is active.

Phase 3: Report Duplicates (if found)

If potential duplicates are found, present them to the user:

I found [N] potential duplicate(s):

1. **[TITLE]** ([STATUS]) — [URL]
   Similarity: [High/Medium/Low] — [reason]

2. **[TITLE]** ([STATUS]) — [URL]
   Similarity: [High/Medium/Low] — [reason]

Options:
a) These are different — proceed with creating the new story
b) This is a duplicate of #[N] — skip creation
c) This is related to #[N] — create and link them

**Wait for user confirmation before proceeding.**

Phase 4: Format the User Story

Generate the story in standard user story format:

## Title
[Concise, descriptive title]

## User Story
**As a** [type of user],
**I want** [goal/desire],
**So that** [benefit/value].

## Description
[Expanded description of the feature, including context and background]

## Acceptance Criteria

### Scenario 1: [Happy path scenario name]
- **Given** [precondition]
- **When** [action]
- **Then** [expected outcome]

### Scenario 2: [Alternative scenario name]
- **Given** [precondition]
- **When** [action]
- **Then** [expected outcome]

### Scenario 3: [Edge case or error scenario name]
- **Given** [precondition]
- **When** [action]
- **Then** [expected outcome]

## Technical Notes
[Any implementation hints, constraints, or dependencies — if applicable]

## Out of Scope
[What this story explicitly does NOT cover — helps prevent scope creep]

**Present the formatted story to the user for review before creating it.**

Phase 5: Create in Tracker

After user approves the story content:

Linear

1. Use ToolSearch to load Linear tools
2. Use mcp__claude_ai_Linear_2__get_team to find the target team
3. Use mcp__claude_ai_Linear_2__list_issue_labels to find appropriate labels
4. Use mcp__claude_ai_Linear_2__save_issue to create the issue with:
   - title: [story title]
   - description: [full story in markdown]
   - team: [target team]
   - priority: [user-specified or default medium]
   - labels: [appropriate labels]