use-case-authoring

What this skill does

# Use Case Authoring Skill

Use Case 2.0 methodology for capturing functional requirements and documenting actor-system interactions.

## MANDATORY: Documentation-First Approach

Before authoring use cases:

1. **Invoke `docs-management` skill** for requirements patterns
2. **Verify Use Case 2.0 methodology** via MCP servers
3. **Base all guidance on Ivar Jacobson's Use Case 2.0**

## Use Case 2.0 Overview

Use Case 2.0 is a scalable, agile practice for capturing requirements:

| Aspect | Description |
|--------|-------------|
| Lightweight | Start minimal, elaborate as needed |
| Scalable | Works for small and large systems |
| Agile-Friendly | Supports iterative development |
| Traceable | Links to tests and implementation |

## Use Case Structure

### Use Case Specification Template

```markdown
# Use Case: Submit Order

**ID:** UC-ORD-001
**Version:** 1.2
**Author:** System Analyst

## Brief Description
Customer submits a draft order for processing, triggering inventory reservation and payment processing.

## Actors
| Actor | Type | Description |
|-------|------|-------------|
| Customer | Primary | Person placing the order |
| Payment Gateway | Supporting | External payment processor |
| Inventory System | Supporting | Manages product stock |

## Preconditions
1. Customer is authenticated
2. Order exists in Draft status
3. Order contains at least one item
4. Customer has valid payment method on file

## Postconditions
### Success Postconditions
1. Order status changed to Submitted
2. Inventory reserved for all items
3. Payment authorization obtained
4. Confirmation notification sent to customer

### Failure Postconditions
1. Order remains in Draft status
2. No inventory changes made
3. Customer notified of failure reason

## Basic Flow (Happy Path)

| Step | Actor | System |
|------|-------|--------|
| 1 | Customer selects "Submit Order" | |
| 2 | | System validates order contents |
| 3 | | System checks inventory availability |
| 4 | | System reserves inventory for all items |
| 5 | | System calculates order total (subtotal + tax + shipping) |
| 6 | | System requests payment authorization from Payment Gateway |
| 7 | | Payment Gateway authorizes payment |
| 8 | | System updates order status to Submitted |
| 9 | | System sends confirmation email to Customer |
| 10 | | System displays order confirmation page |

## Alternative Flows

### AF1: Partial Inventory Available
**Trigger:** Step 3 - Some items unavailable
| Step | Actor | System |
|------|-------|--------|
| 3a | | System identifies unavailable items |
| 3b | | System displays unavailable items to Customer |
| 3c | Customer chooses: Remove items / Wait for restock / Cancel | |
| 3d | | If remove: System updates order, returns to step 3 |
| 3e | | If wait: System creates backorder, continues to step 4 |
| 3f | | If cancel: End use case (order unchanged) |

### AF2: Payment Declined
**Trigger:** Step 7 - Payment authorization fails
| Step | Actor | System |
|------|-------|--------|
| 7a | | Payment Gateway returns decline reason |
| 7b | | System releases reserved inventory |
| 7c | | System displays payment error to Customer |
| 7d | Customer updates payment method | |
| 7e | | System returns to step 6 |
| 7f | | After 3 failed attempts: End use case (Failure) |

### AF3: Customer Cancels
**Trigger:** Any step - Customer clicks Cancel
| Step | Actor | System |
|------|-------|--------|
| *a | Customer selects "Cancel" | |
| *b | | System releases any reserved inventory |
| *c | | System returns to order details page |
| *d | | End use case (order remains Draft) |

## Exception Flows

### EF1: System Unavailable
**Trigger:** Any step - System component unreachable
| Step | System |
|------|--------|
| 1 | System detects component unavailability |
| 2 | System logs error with correlation ID |
| 3 | System displays "Service temporarily unavailable" message |
| 4 | System suggests retry in 5 minutes |
| 5 | End use case |

### EF2: Session Timeout
**Trigger:** Any step - Customer session expires
| Step | System |
|------|--------|
| 1 | System detects expired session |
| 2 | System saves order state (if possible) |
| 3 | System redirects to login page |
| 4 | After re-login: Resume at last completed step |

## Business Rules
| ID | Rule |
|----|------|
| BR-001 | Order must contain at least one item |
| BR-002 | All items must have positive quantity |
| BR-003 | Payment authorization must be obtained before status change |
| BR-004 | Inventory must be reserved atomically (all or none) |
| BR-005 | Confirmation email must be sent within 30 seconds |

## Non-Functional Requirements
| ID | Category | Requirement |
|----|----------|-------------|
| NFR-001 | Performance | Order submission completes within 3 seconds (p95) |
| NFR-002 | Availability | Service available 99.9% of time |
| NFR-003 | Scalability | Support 1000 concurrent submissions |
| NFR-004 | Security | All payment data encrypted in transit |

## UI Mockups / Wireframes
- Order Summary Page: [Link to mockup]
- Payment Confirmation: [Link to mockup]
- Error States: [Link to mockup]

## Related Use Cases
| Use Case | Relationship |
|----------|--------------|
| UC-ORD-002: Cancel Order | Extension |
| UC-PAY-001: Process Payment | Include |
| UC-INV-001: Reserve Inventory | Include |
| UC-NOT-001: Send Notification | Include |

## Test Scenarios
| Scenario ID | Description | Steps Covered |
|-------------|-------------|---------------|
| TS-001 | Happy path submission | Basic Flow 1-10 |
| TS-002 | Partial inventory | AF1 |
| TS-003 | Payment decline and retry | AF2 |
| TS-004 | Customer cancellation | AF3 |
| TS-005 | Session timeout recovery | EF2 |

## Revision History
| Version | Date | Author | Changes |
|---------|------|--------|---------|
| 1.0 | 2025-01-01 | J. Smith | Initial version |
| 1.1 | 2025-01-10 | J. Smith | Added AF2 payment retry logic |
| 1.2 | 2025-01-15 | M. Jones | Added NFR-003 scalability requirement |
```

## Use Case Diagram

### PlantUML Syntax

```plantuml
@startuml
left to right direction
skinparam packageStyle rectangle

actor Customer
actor "Payment Gateway" as PG <<system>>
actor "Inventory System" as INV <<system>>

rectangle "Order Management System" {
    usecase "Browse Products" as UC1
    usecase "Add to Cart" as UC2
    usecase "View Cart" as UC3
    usecase "Submit Order" as UC4
    usecase "Track Order" as UC5
    usecase "Cancel Order" as UC6
    usecase "Request Refund" as UC7

    usecase "Process Payment" as UC_PAY
    usecase "Reserve Inventory" as UC_INV
    usecase "Send Notification" as UC_NOT
}

Customer --> UC1
Customer --> UC2
Customer --> UC3
Customer --> UC4
Customer --> UC5
Customer --> UC6
Customer --> UC7

UC4 ..> UC_PAY : <<include>>
UC4 ..> UC_INV : <<include>>
UC4 ..> UC_NOT : <<include>>

UC6 ..> UC4 : <<extend>>\n{order submitted}
UC7 ..> UC5 : <<extend>>\n{order delivered}

UC_PAY --> PG
UC_INV --> INV

@enduml
```

### Mermaid Syntax

```mermaid
graph LR
    subgraph Actors
        C[Customer]
        PG[Payment Gateway]
        INV[Inventory System]
    end

    subgraph "Order Management System"
        UC1[Browse Products]
        UC2[Add to Cart]
        UC3[View Cart]
        UC4[Submit Order]
        UC5[Track Order]
        UC6[Cancel Order]

        UC_PAY[Process Payment]
        UC_INV[Reserve Inventory]
    end

    C --> UC1
    C --> UC2
    C --> UC3
    C --> UC4
    C --> UC5
    C --> UC6

    UC4 -.->|include| UC_PAY
    UC4 -.->|include| UC_INV
    UC6 -.->|extend| UC4

    UC_PAY --> PG
    UC_INV --> INV
```

## Use Case Slices

Use Case 2.0 introduces **slices** for incremental implementation:

### Slice Definition

```markdown
# Use Case Slice: Submit Order - Basic Flow

**Use Case:** UC-ORD-001: Submit Order
**Slice ID:** UC-ORD-001-S01
**Priority:** High
**Sprint:** Sprint 3

## Scope
This slice implements the basic happy path for order submission without alternative flows.

## Flows Included
- Basic Flow: Steps 1-10

## Flows Excluded (Fut