/arn-spark-use-cases

name: arn-spark-use-cases
description: >-
  This skill should be used when the user says "use cases", "arn use cases",
  "write use cases", "define use cases", "Cockburn use cases", "actor goals",
  "behavioral requirements", "system behavior", "what does the app do",
  "describe the behavior", "use case document", "document the behavior",
  "define system behavior", or wants to create structured use case documents
  that describe the application's behavior from actor perspectives, producing
  a use-cases/ directory with individual Cockburn fully-dressed use case files
  and a README index.
version: 1.0.0

Arness Use Cases

Create structured use case documents in Cockburn fully-dressed format through a team-based conversational process, aided by the `arn-spark-use-case-writer` agent for drafting and revising, `arn-spark-product-strategist` for business relevance review, and `arn-spark-ux-specialist` for flow quality review (both are greenfield agents in this plugin -- if `arn-spark-ux-specialist` is unavailable, the skill proceeds with product strategist review only). This is a conversational skill that runs in normal conversation (NOT plan mode).

The primary artifacts are a **use-cases/ directory** at the project root containing individual use case files (`UC-NNN-title.md`) and a **README.md** index. Use cases are technology-agnostic behavioral descriptions that serve as the source of truth for what the application does from the actors' perspectives.

Use cases bridge the gap between the high-level product concept and the concrete artifacts consumed by downstream skills. They describe the WHAT (system behavior) not the HOW (implementation). Each use case specifies actors, preconditions, main success scenarios, alternate flows, postconditions, and business rules -- structured detail that the product concept alone does not provide.

For a richer review process where experts debate each other's findings (product strategist and UX specialist cross-review and respond to each other), use `/arn-spark-use-cases-teams` instead. The teams variant produces the same output format but through structured expert debate with mandatory per-round reports.

Prerequisites

The following artifacts inform the use cases. Check in order:

Determine the use cases output directory: 1. Read the project's `CLAUDE.md` and check for a `## Arness` section 2. If found, extract the configured Use cases directory path — this is the source of truth 3. If no `## Arness` section exists or Arness Spark fields are missing, inform the user: "Arness Spark is not configured for this project yet. Run `/arn-brainstorming` to get started — it will set everything up automatically." Do not proceed without it. 4. If the directory does not exist, create it

> All references to `use-cases/` in this skill refer to the configured use cases directory determined above.

**Product concept (strongly recommended):** 1. Read the project's `CLAUDE.md` for a `## Arness` section. If found, look for a `Vision Directory` field and check that directory for `product-concept.md` 2. If no `## Arness` section found, check `.arness/vision/product-concept.md` at the project root

**If a product concept is found:** Use it as the primary source for actors, goals, and use case derivation.

**If no product concept is found:** Ask the user: "No product concept found. I recommend running `/arn-spark-discover` first to define your product. Alternatively, describe your application's purpose, users, and main capabilities and I will work from that."

**Architecture vision (optional):** 1. Check the same Vision directory (from the `## Arness` section) for `architecture-vision.md` 2. If no `## Arness` section found, check `.arness/vision/architecture-vision.md` at the project root

If found: use for understanding system capabilities, constraints, and platform scope.

**Existing prototype screens (optional):** 1. Read the configured Prototypes directory from the `## Arness` section (default: `.arness/prototypes`) 2. Check for `[prototypes-dir]/clickable/` directories 3. Check for `[prototypes-dir]/static/` directories 4. Check for `[prototypes-dir]/clickable/screen-list.md` (if clickable prototype was run)

If found: screen references can enrich use case steps with concrete screen paths.

**Style brief is NOT needed.** Use cases describe behavior, not visual presentation.

Workflow

Step 1: Detect Resume or Fresh Start

Check for existing use case output:

1. Look for `use-cases/README.md` at the project root 2. If found, scan for `use-cases/UC-*.md` files

**If existing use cases found:**

Ask (using `AskUserQuestion`):

**"I found an existing use cases directory with [N] use case files. Which would you prefer?"**

Options: 1. **Continue** — I will read the existing use cases and offer to add new ones or revise existing ones 2. **Fresh start** — I will begin from scratch (existing files will be overwritten)

If continuing: read all existing use case files and the README. Present the current catalog to the user. Ask what they want to change, add, or revise. Skip to the appropriate step (Step 3 for new additions, Step 4 for review of existing, Step 7 for direct user edits).

**If no existing use cases:** Proceed to Step 2.

Step 2: Identify Actors and Propose Use Case Catalog

This step uses expert agents to help build a comprehensive catalog before any use cases are drafted. The experts do not write use case details here — they identify actors, goals, and candidate use cases from their specialist perspectives.

2a: Initial Extraction

Load the product concept and perform an initial extraction of actors and use cases.

**Actors:** Identify all entities that interact with the system:

• **Primary actors:** Entities that initiate interactions to achieve a goal (e.g., a human user, another application)
• **Secondary actors:** Entities that participate in interactions initiated by primary actors (e.g., a paired device in a communication app, a