arn-spark-use-cases

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, another user being called)
• Supporting actors: External systems or services the system depends on (e.g., the operating system for hardware access, a network for connectivity)

Use cases: For each actor, identify their goals. Each distinct goal becomes a candidate use case. Organize by level:

• Summary level: High-level business goals that span multiple user goals (rare -- most applications have 0-2 of these)
• User goal level: What a user sits down to accomplish in one session. This is the most common level. Each user-goal use case should be completable in a single interaction session.
• Subfunction level: Steps that are reused across multiple user-goal use cases. These become separate use cases when the substep is complex enough to document independently and is included by 2+ user-goal use cases.

Relationships: Identify how use cases connect:

• Includes: UC-A contains UC-B as a substep
• Extends: UC-B adds optional behavior to UC-A
• Follows/Precedes: Temporal ordering (UC-A typically happens before UC-B)

2b: Expert Use Case Discovery

Invoke the arn-spark-product-strategist agent via the Task tool, passing the model from .arness/agent-models/spark.md as the model parameter (see plugins/arn-spark/skills/arn-spark-ensure-config/references/ensure-config.md "Dispatch convention" for fallback). Context:

• The product concept document
• The initial actor and use case extraction from Step 2a
• Product pillars (if present in the product concept)
• Instructions: "Review this initial actor and use case catalog from a business perspective. Identify: (1) Missing actors — are there stakeholders, external systems, or participant roles not captured? (2) Missing use cases — are there business processes, capabilities described in the product concept, or product pillar implications that do not have a corresponding use case? (3) Priority concerns — are any use cases mislabeled as must-have or should-have? (4) Scope concerns — are any proposed use cases out of scope for v1? Do not draft use case details — just identify what is missing or needs adjustment. Return a list of suggested additions and corrections."

Then invoke the arn-spark-ux-specialist agent via the Task tool, passing the model from .arness/agent-models/spark.md as the model parameter (see plugins/arn-spark/skills/arn-spark-ensure-config/references/ensure-config.md "Dispatch convention" for fallback). Context:

• The product concept document
• The initial actor and use case extraction from Step 2a
• Existing prototype screens (if available)
• Instructions: "Review this in