write-story

name	write-story
description	Use this skill when the user says "write story", "create story", "new story", "스토리 작성", "스토리 만들어", "스토리 써줘", or wants to create user stories. Collaboratively writes XP-style user stories with acceptance criteria and registers them to TrackerBoot via MCP.

Write Story

Invocation

/write-story <project-id>

• project-id — TrackerBoot 프로젝트 ID (필수)

project-id 없이 호출되면 Step 0에서 즉시 중단한다.

---

Step 0: 사전 조건 확인

스킬 실행 전 반드시 다음을 확인한다.

프로젝트 ID 확인 (필수)

호출 시 project-id가 제공되었는지 확인한다.

제공되지 않았으면 즉시 중단:

❌ TrackerBoot 프로젝트 ID가 필요합니다.

프로젝트 ID 없이 실행하면 권한이 있는 임의의 프로젝트에 스토리가 등록될 수 있습니다.

사용법: /write-story <project-id>
예시:   /write-story 12345678

STOP.

제공되었으면: project-id를 세션 전체에서 사용할 값으로 저장한다.

Step 1: 시나리오 수집

사전 조건이 모두 통과되면, 사용자에게 시나리오를 요청한다.

구상하고 계신 사용자 시나리오를 설명해주세요.

누가 어떤 상황에서 무엇을 하려는지 자유롭게 서술해주시면 됩니다.
가능하면 이 기능을 사용하는 페르소나도 함께 알려주세요.
하나의 시나리오를 작은 스토리들로 나눠드리겠습니다.

예시:
  "쇼핑몰에서 사용자가 상품을 장바구니에 담고, 결제 수단을 선택한 뒤,
   주문을 완료하고 확인 이메일을 받는 전체 흐름"

PAUSE.

시나리오를 받은 뒤 As에 사용할 페르소나 표현이 없거나 모호하면 바로 다음 질문으로 확인한다.

이 시나리오의 주요 페르소나는 누구인가요?

예시:
  - 처음 구매하는 신규 고객
  - 여러 팀을 관리하는 프로젝트 매니저
  - 영업 담당자 Alex

PAUSE. 페르소나를 확인한 뒤 Step 2로 진행한다.

---

Step 2: 스토리 분리

수집한 시나리오를 분석하여 INVEST 원칙에 따라 독립적인 스토리들로 나눈다.

분리 기준

분리 상세 규칙은 references/story-splitting-guide.md 참조.

스토리의 As 항목은 반드시 명시적인 페르소나 표현을 사용한다.

• 시나리오에 페르소나가 드러나면 그 표현을 사용한다.
• 시나리오에 페르소나가 없거나 모호하면 Step 1의 추가 질문으로 먼저 확인한다.
• 확인되지 않은 상태에서 임의의 페르소나를 만들어 진행하지 않는다.

각 스토리가 다음을 만족하는지 검토한다:

• Independent: 다른 스토리에 의존하지 않고 독립적으로 전달 가능한가?
• Valuable: 기술적 수평 분할이 아닌 사용자에게 실질적인 가치를 전달하는가?
• Small: 하나의 이터레이션 안에서 완료할 수 있을 만큼 작은가?
• Testable: 인수 기준을 작성할 수 있는가?

UI 인터랙션 흐름 시나리오일 때

시나리오가 화면 구성, 버튼, 입력 폼 등 UI 조작 흐름을 포함하면 UI 인터랙션 흐름별 분리 패턴을 적용한다.

다음 유형별로 스토리를 나눈다:

1. 진입점 노출 — 기능을 시작할 수 있는 버튼/아이콘이 화면에 보인다
2. 화면 전환 — 버튼을 누르면 새 화면/윈도우가 열린다
3. 폼 구성 확인 — 열린 화면에서 필요한 입력 필드와 버튼이 보인다
4. 데이터 저장 — 입력 후 저장하면 결과가 특정 화면에 반영된다
5. 취소/복귀 — 취소하거나 이전 버튼으로 되돌아간다
6. 기존 데이터 노출 — 수정 진입 시 기존 값이 채워져 있다
7. 삭제 확인 — 삭제 전 확인 메시지가 표시된다

"버튼 하나 추가"가 너무 작아 보여도, UI 인터랙션 흐름 단위에서는 유효한 스토리다.

분리 결과 표시 형식

## 📋 스토리 분리 결과

시나리오를 [N]개의 스토리로 나눴습니다.

---

**[1] [스토리 제목]**

### Why

**As** [페르소나]
**I want** [기능]
**So that** [가치]

> 분리 이유: [왜 이 단위로 나눴는지]

**[2] [스토리 제목]**

### Why

**As** [페르소나]
**I want** [기능]
**So that** [가치]

> 분리 이유: [왜 이 단위로 나눴는지]

...

---
이 분리가 적절한가요?
→ "ok" — 인수 기준 작성으로 진행
→ "split [번호]" — 더 잘게 나누기
→ "merge [번호] [번호]" — 합치기
→ "edit [번호]" — 수정

PAUSE. 변경 사항 반영 후 재표시. "ok" 를 받으면 진행.

---

Step 3: 인수 기준 작성

확정된 모든 스토리에 대해 AC를 한 번에 작성한 뒤, 전체를 함께 검토한다.

AC 작성 순서

각 스토리마다 다음 순서로 작성한다:

1. 해피 패스 — 정상적인 주요 흐름 먼저
2. 엣지 케이스 — 경계값, 예외 흐름
3. 오류 케이스 — 잘못된 입력, 시스템 오류

UI 스토리 AC 작성 시 규칙

• GIVEN: 항상 화면 이름을 명시한다 (예: "메인 화면이 열려 있을 때")
• THEN: 화면의 어느 위치에서 무엇이 보이는지 명시한다 (예: "오른쪽 상단에 + 버튼이 보인다")
• 상세 규칙은 ac-writing-guide.md의 "UI 스토리 AC 작성 패턴" 참조

영속성 AC

데이터를 생성·수정·삭제하는 스토리에는 반드시 영속성 AC를 마지막에 추가한다. 별도 "영속성 스토리"를 만들지 않는다. 패턴은 ac-writing-guide.md의 "영속성 AC 패턴" 참조

전체 AC 표시 형식

모든 스토리의 AC를 하나의 블록으로 표시한다.

## 📋 인수 기준 초안 (전체 [N]개 스토리)

---

### [1] [스토리 제목]

```gherkin
Scenario: [시나리오 이름]
    Given [사전 조건]
    When  [사용자 행동]
    Then  [기대되는 결과]

Scenario: [시나리오 이름]
    Given [사전 조건]
    When  [사용자 행동]
    Then  [기대되는 결과]

---

[2] [스토리 제목]

Scenario: [시나리오 이름]
    Given [사전 조건]
    When  [사용자 행동]
    Then  [기대되는 결과]

...

표시 후:

인수 기준을 검토해주세요. → "add [스토리번호] [내용]" — AC 추가 → "remove [스토리번호 AC번호]" — AC 제거 → "edit [스토리번호 AC번호]" — AC 수정 → "done" — 완료, 레이블 선택으로 진행

PAUSE. 변경 사항 반영 후 재표시. "done" 을 받으면 Step 4로 진행한다.

AC 작성 상세 규칙은 `references/ac-writing-guide.md` 참조.

---

## Step 4: 레이블 선택

### 4-1. 레이블 추천

전체 스토리 내용을 분석하여 공통 레이블과 개별 레이블을 추천한다.
스토리 번호는 `S1`, `S2` 형식으로 표기하고, 연속된 범위는 `S1~S4` 형식으로 묶어 표시한다.

스토리 내용을 분석한 추천 레이블입니다.

공통 레이블 추천:

• [레이블명] ([적용 이유 — 기능 도메인 설명])
• [레이블명]

개별 레이블 추천:

• S[번호]~S[번호] : [레이블명]
• S[번호]~S[번호] : [레이블명]
• S[번호] : [레이블명]

적용할 레이블을 선택해주세요. → "ok" / "done" — 추천 그대로 확정 → 추가/제거하고 싶으면 알려주세요

PAUSE. 변경 사항 반영 후 재표시. "ok" / "done" 을 받으면 레이블을 확정하고 4-2로 진행한다.

### 4-2. 관련 스토리 조회 및 문맥 반영

레이블이 확정되면, TrackerBoot MCP로 동일 프로젝트 내 동일 레이블의 기존 스토리를 조회한다.

tracker-boot-mcp-tb_search_stories (projectId + labels filter)

조회 시 반드시 Step 0에서 저장한 `project-id`를 함께 전달한다.

**관련 스토리가 없으면:** 조용히 진행한다.

**관련 스토리가 있으면:** 다음 순서로 분석한다.

#### 1) 기존 스토리 목록 표시

📋 기존 관련 스토리 (레이블: "[레이블]", 총 [N]개)

• [스토리 ID] [스토리 제목]
• [스토리 ID] [스토리 제목] ...

기존 스토리를 바탕으로 문맥을 분석합니다...

#### 2) 문맥 분석

기존 스토리들에서 다음 항목을 추출한다:

- **페르소나 표현** — "As" 뒤에 쓰인 페르소나 명칭 (기존과 일치시킴)
- **동사/행동 표현** — "I want to" 뒤에 쓰인 동사 패턴 (기존 용어 우선)
- **화면·UI 용어** — 기존 스토리에서 사용한 화면 이름, 버튼 명칭
- **AC 형식** — GIVEN/WHEN/THEN 작성 스타일 및 상세 수준
- **중복 스코프** — 새 스토리와 동일하거나 겹치는 기능

#### 3) 변경이 필요한 경우 개발자에게 알림

분석 결과 새 스토리 조정이 필요하면 변경 사항을 표시하고 확인을 받는다:

🔍 기존 스토리 문맥 분석 결과

[변경 필요 항목이 있는 경우]

조정 사항:

• [스토리 N] "[기존 표현]" → "[기존 스토리 문맥에 맞춘 표현]" 이유: [기존 스토리에서 사용한 용어/패턴과 일치시키기 위해]
• ...

[중복 스코프가 있는 경우]

중복 검토:

• [스토리 N]이 기존 스토리 [[스토리 ID] [제목]]과 스코프가 겹칩니다. → 제거 또는 스코프 조정이 필요합니다.

조정을 적용할까요? → "ok" — 전체 적용 → "skip" — 조정 없이 진행 → 특정 항목만 적용하려면 알려주세요

PAUSE. "ok" 를 받으면 스토리와 AC에 조정 사항을 반영하고 Step 5로 진행한다.

**변경이 필요하지 않은 경우:** 조용히 Step 5로 진행한다.

---

## Step 5: 최종 확인

완성된 전체 스토리 목록을 표시하고 최종 승인을 받는다.

```markdown
## ✅ 최종 스토리 Preview ([N]개)

---

### [1] [스토리 제목]

### Why

**As** [페르소나]
**I want** [기능]
**So that** [가치]

### Acceptance Criteria

```gherkin
Scenario: [시나리오 이름]
    Given [조건]
    When  [행동]
    Then  [결과]

레이블: [레이블1], [레이블2]

---

[2] [스토리 제목]

...

---

TrackerBoot에 [N]개 스토리를 등록할까요? → "register" — 전체 등록 → "register [번호]" — 해당 스토리만 등록 → "edit [번호] [섹션]" — 수정 (title / description / ac / labels) → "cancel" — 취소

PAUSE.

---

## Step 6: TrackerBoot 등록

개발자가 확인하면 TrackerBoot MCP로 스토리를 **역순(마지막 스토리부터)**으로 등록한다.

> TrackerBoot는 새로 등록된 스토리를 목록 상단에 추가하므로, 원하는 순서대로 화면에 표시되려면 **마지막 스토리(S[N])부터 첫 번째 스토리(S1) 순서**로 등록해야 한다.

### MCP 도구

tracker-boot-mcp-tb_create_story — 스토리 생성 (Why + AC + Notes 모두 description에 포함)

### 등록 절차

스토리마다 **1단계(스토리 생성)**만 실행한다. **S[N] → S[N-1] → ... → S[1] 순서로 진행한다.**

**1단계 — 스토리 생성:**

AC는 task가 아닌 `description`의 `### Acceptance Criteria` 섹션에 gherkin 형식으로 포함한다.
라벨은 MCP가 지원하지 않으므로 `description`의 `**Notes:**` 섹션에 ul 형식으로 포함한다.
추후 MCP 서버가 라벨 생성을 지원하면 `labels` 파라미터를 함께 전달한다.

```json
{
  "projectId": "[Step 0에서 저장한 project-id]",
  "title": "[스토리 제목]",
  "storyType": "Feature",
  "description": "### Why\n\n**As** [페르소나]\n**I want** [기능]\n**So that** [가치]\n\n### Acceptance Criteria\n\n```gherkin\nScenario: [시나리오 이름]\n    Given [사전 조건]\n    When  [사용자 행동]\n    Then  [기대되는 결과]\n\nScenario: [시나리오 이름]\n    Given [사전 조건]\n    When  [사용자 행동]\n    Then  [기대되는 결과]\n```\n\n**Notes:**\n\n- [레이블1]\n- [레이블2]"
}

등록 진행 표시

역순으로 진행하되, 진행 카운터는 원래 순서(S1=1번)로 표시한다:

⏳ [N/N] 등록 중... [마지막 스토리 제목]
✅ [N/N] [마지막 스토리 제목] — 완료 (ID: [스토리 ID])
⏳ [N-1/N] 등록 중... [N-1번째 스토리 제목]
✅ [N-1/N] [N-1번째 스토리 제목] — 완료 (ID: [스토리 ID])
...
⏳ [1/N] 등록 중... [첫 번째 스토리 제목]
✅ [1/N] [첫 번째 스토리 제목] — 완료 (ID: [스토리 ID])

전체 등록 완료

✅ 전체 [N]개 스토리 등록 완료

등록된 스토리:
  - #[스토리 ID] [스토리 제목]
  - #[스토리 ID] [스토리 제목]
  ...

→ 각 스토리에 대해 후속 구현 계획이나 개발 워크플로우를 이어갈 수 있습니다.

등록 실패

특정 스토리 등록에 실패하면:

❌ [N번 스토리] 등록 실패: [오류 메시지]

→ "retry" — 다시 시도
→ "skip" — 이 스토리 건너뛰고 다음으로
→ "copy" — 해당 스토리 내용을 Markdown 형식으로 출력
→ "cancel" — 전체 등록 중단

---

참조 파일

파일	사용 시점
references/story-splitting-guide.md	Step 2 스토리 분리 시
references/story-format-guide.md	Step 2 스토리 초안 형식
references/ac-writing-guide.md	Step 3 AC 작성 시