Imported from phucnt-bazone-vietnam/use-case-writer (SKILL.md). Install upstream with npx skills add phucnt-bazone-vietnam/use-case-writer. Copyright stays with the author.

Use Case Writer — Skill for IT Business Analysts

by Phúc NT · BA Zone · Digital School

This skill helps IT BAs scope, analyze, and document Use Cases in English Markdown following the standard 13-field template (Karl Wiegers / IIBA style), with best practices from Alistair Cockburn's "Writing Effective Use Cases" and the IIBA BABOK Guide.

Developed by Phúc NT as part of the Digital School training program by BA Zone — Vietnam's Business Analyst & Product Owner community.

When to use this skill

Trigger this skill whenever the user needs to:

• Draft a new UC from a feature description, BRD, or PRD
• Refine or review an existing UC (completeness, correctness)
• Split a large feature into multiple smaller UCs (scope identification)
• Write a specific section: Normal Course, Alternative Course, Exceptions
• Validate a UC against the quality checklist

Output rules (non-negotiable)

1. Language: English. Even if the user types in Vietnamese, generate the UC document in English. Use Vietnamese only when chatting with the user about the process.
2. Format: Markdown (.md). Use the 2-column table layout that mirrors the original template.
3. Mode: Sequential — generate section by section, stop and wait for the user to confirm before moving on. Never dump a full UC in one shot unless the user explicitly says "give me the full UC at once".

Workflow: 4 Steps

Step 1: CLASSIFY INPUT     →  identify which mode the user is in
Step 2: SCOPE THE UC       →  apply 4 scoping rules + coffee-break test
Step 3: WRITE THE UC       →  fill the 13 fields ONE SECTION AT A TIME
Step 4: VALIDATE           →  run the 20-point checklist before handover

Step 1: Classify input and pick a mode

Before writing anything, identify which mode the user is in:

Golden rule: If input is vague (just one line), ASK before writing — never make things up. Ask at most 3 questions:

1. Who is the primary actor? (specific role / user class)
2. What is the actor's concrete goal in this UC?
3. Which system / module does this UC belong to?

Communicate with the user in their language (Vietnamese or English), but the UC artifact is always English.

Step 2: Scope the Use Case

This is the most important and most error-prone part of UC writing. Read carefully.

2.1. Four scoping rules

Rule 1 - Coffee-break test (Alistair Cockburn) After completing the UC, can the actor take a coffee break without feeling the task is unfinished? If NO → the UC is too low-level (sub-function), merge it. If YES → scope is right (user-goal level).

Rule 2 - Goal Level (Cockburn's 3 levels)

• Summary level (cloud): UC spans multiple sessions. E.g. "Manage course enrollment lifecycle" → too high, DO NOT write as a single UC.
• User-goal level (sea level) ✅: 1 actor, 1 session, achieves 1 business goal. E.g. "Enroll in a Digital School course" → right level for a UC.
• Sub-function level (fish): A small step inside another UC. E.g. "Verify OTP" → too low, treat as Includes inside another UC.

Rule 3 - One Actor, One Goal, One Session Each UC should have EXACTLY: 1 primary actor + 1 business goal + completion in 1 continuous session. If you see 2 different goals → split into 2 UCs.

Rule 4 - System Boundary A UC describes the interaction between actor and system, NOT the system's internals. Each step must be one of:

• Actor does something to the system (input)
• System responds to the actor (output) If a step has neither actor nor UI → it's a design detail, not part of the UC.

2.2. Three techniques to identify UCs (for Mode B)

When splitting a large feature into a UC list:

Technique 1: Goal-driven (top-down) List all goals for each actor → each goal = 1 candidate UC.

Technique 2: Event-driven (external + internal triggers)

• External events: user actions (click, submit, scheduled time)
• Internal events: system-triggered (cron job, batch process) Each event produces a system response → candidate UC.

Technique 3: CRUD-driven (data-centric) For each business entity (Learner, Course, Enrollment, Certificate…), check whether the system needs Create / Read / Update / Delete. Each = 1 candidate UC (you can merge R-U-D for the same entity if logic is similar).

2.3. Output of Step 2

Mode A: One sentence confirming scope, then ASK USER TO CONFIRM before moving to Step 3:

"Scope confirmed: this UC is at user-goal level. Primary actor: [X]. Goal: [Y]. System boundary: [Z]. Confirm to proceed to Step 3?"

Mode B: A UC List table:

| UC ID | UC Name (verb + noun)              | Primary Actor    | Goal | Priority |
| UC-01 | Enroll in Digital School course    | Learner          | ...  | High     |
| UC-02 | Book 1-on-1 mentor session         | Learner          | ...  | High     |
| UC-03 | Approve learner KYC application    | BO Approver      | ...  | Medium   |

Then ask: "Which UC do you want me to write in detail first?"

Step 3: Write the Use Case — section by section

CRITICAL: Generate ONE SECTION GROUP at a time, then STOP and ask the user to confirm before continuing. Do not dump the whole UC at once.

Read references/template-guide.md for detailed guidance on filling each field. Read references/writing-style.md for writing conventions (active voice, numbering, anti-patterns).

3.1. The template (output structure)

| **Use Case ID:**        | UC-XX-YY                                   |
| **Use Case Name:**      | [Action verb + noun]                       |
| **Created By:**         |          | **Last Updated By:**   |       |
| **Date Created:**       |          | **Date Last Updated:** |       |

| **Actor:**              | [Primary actor] / [Secondary actors]       |
| **Description:**        | [2-3 sentences: why + what + outcome]      |
| **Preconditions:**      | 1. ... 2. ...                              |
| **Postconditions:**     | 1. ... 2. ...                              |
| **Priority:**           | High / Medium / Low                        |
| **Frequency of Use:**   | [X times / unit time]                      |
| **Normal Course of Events:** | 1. Actor... 2. System... 3. ...       |
| **Alternative Courses:**| UC-XX-YY.AC.1: [name]                      |
| **Exceptions:**         | UC-XX-YY.EX.1: [name]                      |
| **Includes:**           | UC-AA-BB                                   |
| **Special Requirements:**| [Non-functional: perf, security…]         |
| **Assumptions:**        | 1. ...                                     |
| **Notes and Issues:**   | TBD-1: [open question] / Owner / Due       |

Copy-ready template lives in assets/uc-template.md.

3.2. Sequential generation — the 5 section groups

Generate in this exact order, pause and ask confirmation after each group:

Group 1 — Identification + Actor + Description Output: Use Case ID, Name, History (Created By / Date), Actor, Description. Then say: "Group 1 done. Confirm to proceed to preconditions, postconditions, priority, frequency?"

Group 2 — Conditions + Priority + Frequency Output: Preconditions, Postconditions, Priority, Frequency of Use. Then say: "Group 2 done. Confirm to proceed to the Normal Course?"

Group 3 — Normal Course of Events Output: numbered, step-by-step happy path. Then say: "Normal Course done. Confirm to proceed to Alternative Courses and Exceptions?"

Group 4 — Alternative Courses + Exceptions Output: AC.1, AC.2…, EX.1, EX.2… Then say: "Group 4 done. Confirm to proceed to the final group (Includes, Special Req, Assumptions, Notes)?"

Group 5 — Includes + Special Requirements + Assumptions + Notes and Issues Output: the remaining fields. Then say: "All sections done. Shall I run the 20-point quality validation now?"

If the user requests changes to a previous group, apply them and reconfirm before continuing.

If the user says "skip ahead" or "give me everything at once", honor that — but warn briefly that sequential mode catches more issues.

3.3. CRITICAL field-filling rules (the most common mistakes)

Use Case ID: Format UC-<module>-<seq>, e.g. UC-LEARN-01. Hierarchical X.Y if you have UC groups.

Use Case Name: MUST be "Verb + Object" (active voice).

• ✅ "Enroll in Digital School course", "Book mentor session", "Issue course completion certificate"
• ❌ "Enrollment" (no verb), "Learner enrolls" (actor included), "Manage courses" (vague verb)

Actor: Distinguish:

• Primary actor: initiates the UC, benefits from the outcome
• Secondary actor: supporting system/person (payment gateway, OTP service, LMS) Never write "User" — be specific (Learner, Mentor, BO Admin, HR Manager, Enterprise Partner…).

Preconditions: Conditions that MUST be true before the UC starts. Distinguish from business rules!

• ✅ "Learner has logged in and has an active Digital School subscription"
• ❌ "Learner is motivated to study" (motivation — not verifiable)

Postconditions: System state AFTER successful UC completion. Must be verifiable.

• ✅ "Enrollment record saved with status='Active'; learner gains access to all course materials"
• ❌ "Learner feels satisfied" (not verifiable)

Normal Course of Events (most important):

• Numbered list, one action per step
• Alternate Actor / System steps (subject must be explicit)
• Each step starts with a clear subject + active verb
• NO embedded if/else, loops, or exceptions — those go in Alternative/Exception sections
• Storytelling style: from trigger to goal achieved
• ✅ "1. Learner selects the course on the Digital School catalog. 2. System displays course details and enrollment options. 3. Learner clicks 'Enroll Now'."
• ❌ "1. If learner has voucher, enter code; otherwise proceed to payment…" (branching embedded)

Alternative Courses: Different paths that still lead to success. E.g. paying with enterprise voucher instead of personal wallet. Format UC-XX.AC.N + "At step Y of Normal Course, if [condition], execute the alternative: …"

Exceptions: Cases where the goal fails (errors, validation fails, timeouts). Format UC-XX.EX.N. Each exception needs: trigger condition + system response + final state.

Includes: List of sub-UCs "called" by this UC (common functionality). E.g. UC "Enroll in course" includes UC "Process payment".

Special Requirements: Non-functional requirements specific to this UC:

• Performance: "Course catalog page loads ≤ 2s for 5,000 concurrent learners"
• Security: "Payment data must be encrypted in transit (TLS 1.3)"
• Usability, Reliability, Compliance…

Assumptions: Things assumed during analysis. Different from Preconditions — a precondition is a hard requirement; an assumption is a belief that hasn't been verified.

Notes and Issues: List of TBDs with format [TBD-N] | Owner | Due date | Resolution.

Step 4: Validate against the 20-point checklist

ALWAYS run this checklist BEFORE handing over the UC. If any item fails, fix it or flag it to the user.

Read references/quality-checklist.md for the full checklist with examples. The 20 items, grouped:

Scope & Identification (5 items)

• C1: UC Name follows "verb + object", active voice
• C2: UC is at user-goal level (passes coffee-break test)
• C3: UC ID is unique and follows naming convention
• C4: Exactly 1 primary actor + 1 clear business goal
• C5: System boundary is clear (not mixed with other UCs)

Actor & Context (3 items)

• C6: Actor is a specific role/class, not "User"
• C7: Description answers WHY (reason) + WHAT (action) + OUTCOME (result)
• C8: Frequency of Use is quantified (not "sometimes")

Pre/Post Conditions (3 items)

• C9: Preconditions are verifiable (not disguised business rules)
• C10: Postconditions cover the success state and all system changes
• C11: Preconditions are not confused with Assumptions

Normal Course (4 items)

• C12: Numbered list, one action per step
• C13: Alternates Actor / System with clear subjects
• C14: NO embedded if/else/loop in the Normal Course
• C15: Flow runs from trigger to postcondition (no dangling step)

Alternative & Exception (3 items)

• C16: Each AC specifies "at step N" + condition
• C17: Each Exception has trigger + system response + final state
• C18: Common failure modes are covered (timeout, invalid input, network, permission denied, concurrency conflict)

Completeness (2 items)

• C19: Includes (if any) point to existing UCs
• C20: Special Requirements don't duplicate functional requirements

Validation output: A Item | Status | Note table with ✅ ❌ ⚠️ markers.

Output format details

• Always produce English Markdown
• Use the 2-column table layout that matches the original template
• Save final output as a .md file if the user wants a downloadable file; otherwise show inline in chat
• File naming convention: <UC-ID>_<UC-Name-kebab>.md, e.g. UC-LEARN-01_enroll-digital-school-course.md

References

• references/template-guide.md - Detailed guidance for each field (with EdTech & Digital School examples)
• references/writing-style.md - Writing conventions (active voice, numbering, anti-patterns)
• references/quality-checklist.md - 20-point checklist with pass/fail examples
• references/examples-edtech.md - 2 complete EdTech UC examples (Course Enrollment, Mentor Session Approval)
• assets/uc-template.md - Copy-ready Markdown template

Anti-patterns (ABSOLUTELY avoid)

1. UC = UI flow: Describing every button click and popup → that's a wireframe spec, not a UC
2. UC = User Story: A UC describes detailed interactions; a US is a one-liner "As a… I want… So that…"
3. UC = Business Process: A BP covers an entire business process (many people, many systems); a UC covers 1 actor + 1 system
4. Vague verbs in UC Name: "Manage", "Handle", "Process" — too generic. Use specific action verbs
5. Mixing concerns: Cramming enrollment, payment, notification into one giant UC → split using Includes
6. Forgetting exceptions: Writing only the happy path with no failure modes → insufficient for dev/QA
7. Vague preconditions: "System is ready" → meaningless. Must be verifiable

Skill developed by Phúc NT · BA Zone · Digital School
Please keep attribution intact when sharing or forking this repo.