Create User Story

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]

GitHub Issues

gh issue create \
  --repo [CUSTOMIZE: your-org/your-repo] \
  --title "[story title]" \
  --body "[full story in markdown]" \
  --label "[appropriate labels]"

Jira

Use WebFetch to POST to Jira REST API or use jira CLI:
- Project: [CUSTOMIZE: YOUR-PROJECT-KEY]
- Issue Type: Story
- Summary: [story title]
- Description: [full story in markdown/Jira wiki format]
- Priority: [user-specified or default Medium]
- Labels: [appropriate labels]

Vault Fallback (no tracker active)

Save to 04-projects/[project]/stories/story-YYYY-MM-DD-[slug].md

Phase 6: Confirm and Link

1. Confirm creation with the user:

   Story created: **[TITLE]**
   [URL or file path]
   Priority: [priority]
   Labels: [labels]
   

2. If the user indicated this is related to another issue (Phase 3, option c), create a link/relation between them.

3. Also save a local copy to 04-projects/[project]/stories/ for vault reference.

Fallback Behavior

Error Handling

• API rate limits: Wait and retry once, then fall back to local save
• Authentication failures: Inform user their integration may need re-authentication
• Large search results: Limit duplicate check to top 10 most relevant matches
• Context overflow: Summarize duplicate results rather than showing full descriptions