09 Use Case Modeling

Use Case Modeling Skill

Use When

• specifying actor-goal use cases with preconditions, main flow, alternatives, exceptions, postconditions, and trace links; use user-story-generation for Agile backlog items.
• Use this procedure when the required source artefacts are available and Use-case model and specifications is the next lifecycle deliverable.

Do Not Use When

• Use user-story-generation when that neighbouring route owns the decision or deliverable.
• Do not invent missing project evidence, standards clauses, thresholds, or stakeholder decisions.

Required Inputs

Workflow

1. Inspect the required inputs and log the exact sources, versions, and unresolved assumptions.
2. Apply this skill's existing domain workflow and decision rules to produce Use-case model and specifications.
3. Stop when a required source, accountable decision owner, or deterministic test oracle is absent.
4. Recover by preserving valid work, marking the blocked scope, and returning the narrowest qualified artefact plus the next evidence needed.

Outputs

Evidence Produced

Capability and permission boundaries

Read and search are required. Editing is allowed only when the request authorises creation or repair of the named requirements artefact. Publishing, production mutation, destructive action, spending, and certification require explicit authority.

Degraded mode

Fallback: if a required file, reviewer, standard source, network check, renderer, or execution capability is unavailable, return the narrowest useful qualified result and mark the affected check not assessed; never convert an unassessed check into a pass.

Decision Rules

Quality Standards

• Preserve stable identifiers and bidirectional traceability from project evidence to Use-case model and specifications and its acceptance checks.
• Apply ISO/IEEE measures only with a named metric, method, threshold, evidence source, and responsible reviewer; run the anti-slop gate before release.

Anti-Patterns

• Producing Use-case model and specifications from assumed context. Fix: cite the project source or mark the scope blocked.
• Accepting a material requirement without a deterministic oracle. Fix: add a measurable result, boundary, and verification method.
• Crossing into user-story-generation without routing the decision. Fix: hand off the named input and preserve trace links.
• Treating an unavailable check as passed. Fix: mark it not assessed and state the release consequence.
• Claiming standards, statutory, or stakeholder approval without evidence. Fix: cite the source and reviewer or qualify the claim.

References

• Skill authoring and release standard
• Skill guidance
• Activity Diagram Guide
• Actor Classification
• Use Case Template

Overview

This skill runs after Phase 05 (Feature Decomposition). It transforms functional requirements from SRS Section 3.2 into a complete use case model that includes actor classification, use case diagrams, fully-dressed use case descriptions, and activity diagrams for complex workflows. The output conforms to UML 2.5.1 notation standards and IEEE 29148-2018 behavioral requirements guidance.

When to Use

• After 05-feature-decomposition has produced Section 3.2 in SRS_Draft.md.
• When stakeholders need a behavioral view of system interactions beyond stimulus-response pairs.
• When complex multi-actor workflows require visual modeling with swimlanes and decision logic.

Quick Reference

Input Files

Output Files

Core Instructions

Follow these nine steps in order. Do not skip or reorder.

Step 1: Read Context Files

Read SRS_Draft.md (Sections 3.1 and 3.2), features.md, and business_rules.md from the specified locations. Optionally read stakeholder_register.md. Log the absolute path of each file read. Halt execution if SRS_Draft.md or features.md is missing.

Step 2: Identify and Classify Actors

Analyze the input files to identify all actors that interact with or have interest in the system.

Two complementary actor taxonomies are available. Choose based on project type:

Option A — Cockburn's 3-Class Model (use for software-centric systems):

Option B — Whitten & Bentley's 4-Class Model (use for enterprise/business information systems):

Guidance: Use Option B when the system is an enterprise business application (ERP, CRM, HR, billing, approval workflows) where the distinction between "who benefits" and "who initiates" is critical for correct workflow design. Use Option A for simpler or software-product contexts.

Temporal Actors: When the system has scheduled or time-triggered processes (nightly batch jobs, billing cycles, session expiry, automated reminders), model time as a Temporal Actor. Document: Temporal Actor: System Clock — initiates [Use Case Name] at [schedule/frequency]. Temporal actors are positioned outside the system boundary like other actors.

Actor Generalization: Apply actor generalization where two or more actors share common behaviors. Use an inheritance arrow from the specialized actor to the general actor. Document the generalization hierarchy. Distinguish human actors from system actors explicitly.

Step 3: Identify Use Cases

Extract use cases from Section 3.2 functional requirements. Each use case shall represent a user-goal-level interaction (not subfunction level). Apply these rules:

1. Every use case shall have a verb-noun name (e.g., "Process Payment", "Register Account").
2. Every use case shall map to at least one functional requirement in Section 3.2.
3. Group related subfunctions under a single use case; do not create one use case per requirement.
4. Assign a unique identifier: UC-[NNN] (e.g., UC-001, UC-002).

Step 4: Generate Use Case Diagram

Produce a system-level use case diagram using Mermaid notation or structured text-based UML. The diagram shall include:

• System boundary enclosing all use cases
• Actors positioned outside the boundary, with primary actors on the left and supporting/offstage actors on the right
• Use cases as labeled ovals inside the boundary
• Associations connecting actors to their use cases (solid lines)
• Include relationships for mandatory shared behavior (<<include>>)
• Extend relationships for optional conditional behavior (<<extend>>)
• Actor generalization using inheritance arrows where applicable
• Depends-on relationships (<<depends on>>) between use cases that have development sequencing dependencies — use case B cannot be built until use case A is complete. This relationship aids sprint planning and release sequencing.

Step 5: Generate Fully-Dressed Use Case Descriptions

For each use case identified in Step 3, produce a fully-dressed description using this template:

### UC-[NNN]: [Use Case Name]

| Field | Value |
|-------|-------|
| **UC-ID** | UC-[NNN] |
| **Name** | [Verb-Noun Name] |
| **Primary Actor** | [Actor Name] |
| **Stakeholders & Interests** | [List each stakeholder and their interest] |
| **Preconditions** | [Conditions that must be true before execution] |
| **Success Guarantee** | [System state after successful completion] |
| **Minimal Guarantee** | [System state guaranteed even on failure] |
| **Priority** | [Critical / High / Medium / Low] |
| **Frequency of Use** | [e.g., 500 times/day, Weekly, On-demand] |
| **Trigger** | [Event or action that initiates this use case] |

#### Main Success Scenario

1. The [Actor] [performs action].
2. The system shall [respond with action].
3. The [Actor] [performs next action].
4. The system shall [respond with next action].
...
[N]. The system shall [confirm completion / display result].

#### Alternative Flows

**[Step]a. [Condition]:**
1. The system shall [alternative action].
2. [Resume at step N / End use case].

**[Step]b. [Different Condition]:**
1. The system shall [alternative action].
2. [Resume at step N / End use case].

#### Exception Flows

**[Step]a. [Error Condition]:**
1. The system shall [log the error / display error message].
2. The system shall [recovery action].
3. [Resume at step N / Abort use case].

#### Business Rules

- BR-[NNN]: [Referenced business rule from business_rules.md]

#### Data Requirements

- [List data entities read, created, updated, or deleted]

#### Assumptions

- [List assumptions made by the analyst that affect this use case — e.g., "Assumes single currency; multi-currency not in scope"]

#### Implementation Constraints

- [Technical constraints that bound implementation choices — e.g., "Must use existing OAuth 2.0 provider", "Response time shall not exceed 2 seconds on 3G connection"]

#### Open Issues

- [Unresolved questions flagged for stakeholder review]

Writing guidelines for use case steps:

• Use active voice: "The system shall..." or "The [Actor] [verbs]..."
• Follow stimulus-response pairing: every actor action receives a system response.
• Do not embed UI details (button names, screen layouts) in the main flow; reference interface specifications instead.
• Number steps sequentially; alternative flows reference the main step they branch from.

Step 6: Generate Activity Diagrams

For each use case that involves two or more actors, decision logic, or parallel activities, produce a Mermaid activity diagram. The diagram shall include:

• Initial node (filled circle) and final node (bullseye)
• Actions as rounded rectangles with verb-noun labels
• Decision nodes (diamonds) with mutually exclusive guard conditions enclosed in brackets
• Fork/join bars for parallel activities
• Swimlanes (partitions) separating responsibilities per actor

Use this Mermaid flowchart pattern for activity diagrams:

flowchart TD
    subgraph Actor1["Actor 1"]
        A1[Action 1]
    end
    subgraph Actor2["Actor 2"]
        A2[Action 2]
    end
    A1 --> D1{Decision?}
    D1 -->|Yes| A2
    D1 -->|No| A3[Alternative Action]

Generate activity diagrams only for complex workflows. Simple CRUD operations do not require activity diagrams.

Step 7: Build Traceability Matrix

Construct a traceability matrix mapping every Section 3.2 functional requirement to at least one use case. Use this format:

Flag any functional requirement that has no corresponding use case with [TRACE-FAIL: FR-[ID] has no use case coverage].

Step 8: Validate Completeness

Perform these validation checks:

1. Actor Coverage: Every actor shall participate in at least one use case. Flag orphan actors with [V&V-FAIL: Actor "[Name]" has no associated use case].
2. Requirement Coverage: Every functional requirement in Section 3.2 shall trace to at least one use case. Flag gaps per Step 7.
3. Stimulus-Response Compliance: Every main success scenario shall alternate between actor stimulus and system response per IEEE 830 Clause 5.3.1.
4. Business Rule Coverage: Every business rule referenced in business_rules.md that relates to a functional requirement shall appear in at least one use case description.
5. Precondition/Postcondition Consistency: No use case shall list a precondition that is not guaranteed as a postcondition of another use case or an initial system state.

Step 9: Write Output

Assemble the complete use case model and write it to projects/<ProjectName>/<phase>/<document>/Use_Case_Model.md.

Output Format

The generated Use_Case_Model.md shall contain the following sections:

# Use Case Model: [Project Name]

- **Date:** [YYYY-MM-DD]
- **Version:** [X.Y]
- **Standard:** UML 2.5.1, IEEE 29148-2018

## 1. Actor Catalog

### 1.1 Actor Summary
| Actor | Type | Description | Generalization |
|-------|------|-------------|----------------|

### 1.2 Actor Generalization Hierarchy
[Diagram or structured list]

## 2. Use Case Diagram
[Mermaid diagram or text-based UML]

## 3. Use Case Descriptions
### UC-001: [Name]
[Fully-dressed template per Step 5]
...

## 4. Activity Diagrams
### AD-001: [Workflow Name]
[Mermaid activity diagram per Step 6]
...

## 5. Traceability Matrix
[Table per Step 7]

## 6. Validation Summary
[Results of Step 8 checks]

## 7. Open Issues
[Consolidated list of unresolved items]

Common Pitfalls

Verification Checklist

• Use_Case_Model.md exists in projects/<ProjectName>/<phase>/<document>/
• Every actor is classified as Primary, Supporting, or Offstage
• Every use case has a unique UC-ID and verb-noun name
• Every fully-dressed description includes preconditions, postconditions, main scenario, alternatives, and exceptions
• Main success scenarios follow stimulus-response pairing
• Activity diagrams exist for all multi-actor or decision-heavy workflows
• Traceability matrix covers 100% of Section 3.2 functional requirements
• No [TRACE-FAIL] or [V&V-FAIL] tags remain unresolved

Integration

Standards

• UML 2.5.1 -- Unified Modeling Language specification for use case and activity diagrams
• IEEE 29148-2018 -- Systems and software engineering: behavioral requirements modeling
• IEEE 830-1998 Clause 5.3.1 -- Stimulus-response pairs for functional requirements
• Dennis, Wixom, Tegarden -- "Systems Analysis and Design with UML" (fully-dressed use case format)
• Whitten & Bentley (2007) -- "Systems Analysis and Design Methods" — 4-class actor taxonomy (Primary Business, Primary System, External Server, External Receiver), use case relationship types including <<depends on>>

Resources

• references/use-case-template.md -- Complete fully-dressed use case template with examples
• references/activity-diagram-guide.md -- Activity diagram construction and Mermaid syntax
• references/actor-classification.md -- Actor identification and classification techniques
• README.md -- Quick-start guide for this skill