@fredcallagan/arn-spark 5.1.0

package/plugins/arn-spark/skills/arn-spark-use-cases/SKILL.md

@@ -0,0 +1,359 @@
+---
+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 `arness.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 `arness.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 the user:
+
+**"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 initial actor and use case catalog from a user experience perspective. Identify: (1) Missing user goals — are there interaction patterns, user journeys, or common user needs not captured? Think about first-run experience, error recovery, settings management, and lifecycle events (install, update, uninstall). (2) Missing actors — are there user roles or external systems that participate in UX flows but are not listed? (3) Granularity concerns — are any proposed use cases too broad (should split) or too narrow (should merge)? (4) Missing interaction patterns — cancel, undo, timeout, retry, empty states, accessibility needs. Do not draft use case details — just identify what is missing or needs adjustment. Return a list of suggested additions and corrections."
+
+If `arn-spark-ux-specialist` is unavailable, proceed with the product strategist's suggestions only. Note the limitation.
+
+#### 2c: Merge and Present Consolidated Catalog
+
+Merge the initial extraction with expert suggestions:
+- Add any actors or use cases both experts agree are missing
+- Add any actors or use cases one expert raised that do not conflict with the other
+- Note any disagreements (one expert suggests adding something the other considers out of scope) — present these to the user for resolution
+- Apply priority corrections if both experts agree
+
+Present the consolidated actor catalog and proposed use case catalog:
+
+"Based on your product concept and expert analysis, here are the actors and use cases identified:
+
+[If experts contributed additions:] The product strategist suggested [N] additions (business processes, missing actors) and the UX specialist suggested [M] additions (user flows, interaction patterns). These are marked with their source below.
+
+**Actors:**
+| Actor | Type | Description | Source |
+|-------|------|-------------|--------|
+| [Name] | Primary | [brief description] | Initial |
+| [Name] | Secondary | [brief description] | Product strategist |
+| [Name] | Supporting | [brief description] | UX specialist |
+
+**Proposed Use Cases:**
+| UC-ID | Title | Primary Actor | Level | Priority | Source | Notes |
+|-------|-------|---------------|-------|----------|--------|-------|
+| UC-001 | [Title] | [Actor] | User Goal | Must-have | Initial | [brief note] |
+| UC-002 | [Title] | [Actor] | User Goal | Must-have | Product strategist | [brief note] |
+| UC-003 | [Title] | [Actor] | Subfunction | Should-have | UX specialist | [included by UC-001, UC-002] |
+| ... | ... | ... | ... | ... | ... | ... |
+
+**Relationships:**
+```
+UC-001 [Title]
+  |-- includes UC-003 [Title]
+  +-- follows --> UC-002 [Title]
+
+UC-002 [Title]
+  +-- extended by UC-004 [Title]
+```
+
+[If disagreements exist:] **Needs your input:**
+- [Expert A] suggests [addition/change] because [reason]. [Expert B] considers it [out of scope / too granular / etc.] because [reason]. What do you think?
+
+Adjust actors, use cases, priorities, or relationships before I proceed."
+
+Wait for user confirmation or adjustments. The user may add, remove, rename, re-prioritize, or restructure the catalog. The user has final authority — expert suggestions are recommendations, not mandates.
+
+### Step 3: Draft All Use Cases (Parallel)
+
+Draft use cases in parallel by invoking multiple `arn-spark-use-case-writer` agents simultaneously. Each writer receives the full shared context but is assigned a subset of use cases to write.
+
+**Grouping strategy:**
+- Group use cases that have direct includes/extends relationships into clusters (e.g., if UC-001 includes UC-005, they go to the same writer). This keeps closely related use cases together for consistent cross-referencing.
+- Independent use cases (no includes/extends relationship to other UCs) can each be assigned to their own writer or batched into small groups of 2-3.
+- Aim for 3-5 parallel writer invocations. For small catalogs (5 or fewer use cases), a single writer is fine.
+
+**Each writer receives:**
+- **Product concept:** document path
+- **Actor catalog:** the confirmed actor table
+- **Use case catalog:** the FULL confirmed catalog with all relationships (not just the assigned subset)
+- **Assigned use cases:** the specific UC-IDs this writer should draft
+- **Use case template:** `${CLAUDE_PLUGIN_ROOT}/skills/arn-spark-use-cases/references/use-case-template.md`
+- **Output directory:** `use-cases/`
+- **Existing prototype screens (if any):** paths to prototype directories
+- **Architecture vision (if available):** for system capability context
+
+After all parallel writers complete, invoke one final `arn-spark-use-case-writer` 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:
+- **Index template:** `${CLAUDE_PLUGIN_ROOT}/skills/arn-spark-use-cases/references/use-case-index-template.md`
+- **Output directory:** `use-cases/`
+- **Product concept:** document path
+- **Actor catalog and use case catalog:** for populating the index
+- Instruction: "Write only the README index. All use case files already exist."
+
+Present a brief summary: "**[N] use cases drafted.** Files written to `use-cases/`. Starting expert review."
+
+### Step 4: Product Strategist Review (Batch)
+
+Read the review protocol for the team process:
+> Read `${CLAUDE_PLUGIN_ROOT}/skills/arn-spark-use-cases/references/review-protocol.md`
+
+Create the `[use-cases-dir]/reviews/` directory if it does not exist.
+
+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:
+- All drafted use case content (read each file and provide the content)
+- Product concept for context
+- Actor catalog
+- Expert review template path: `${CLAUDE_PLUGIN_ROOT}/skills/arn-spark-use-cases/references/expert-review-template.md`
+- File path to write to: `[use-cases-dir]/reviews/round-1-business-review.md`
+- Review focus instructions: "Review these use cases from a business perspective. For each use case, assess: Is the goal business-relevant and aligned with the product concept? Is the actor correct? Are the priority and level appropriate? Are there missing alternate flows from a business perspective (policy limits, resource constraints, edge cases)? Are business rules complete? Cross-cutting: are there missing actors or missing use cases for capabilities in the product concept? Is scope appropriate? Write your complete review to the specified file path using the expert review template. Return a brief summary in conversation."
+
+After the strategist completes, read the review file at the specified path to extract the full feedback.
+
+### Step 5: UX Specialist Review (Batch)
+
+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:
+- All drafted use case content
+- Product concept for context
+- Existing prototype screens (if available)
+- Expert review template path: `${CLAUDE_PLUGIN_ROOT}/skills/arn-spark-use-cases/references/expert-review-template.md`
+- File path to write to: `[use-cases-dir]/reviews/round-1-flow-review.md`
+- Review focus instructions: "Review these use cases from a user experience perspective. For each use case, assess: Is the main success scenario natural from the actor's perspective? Are steps at the right granularity? Are common interaction patterns covered (cancel, undo, timeout, retry, empty states)? Are error recovery flows present for likely failures? Is accessibility considered? Do preconditions and postconditions make sense as observable states? Are related use cases properly connected? Cross-cutting: is step granularity consistent across use cases? Write your complete review to the specified file path using the expert review template. Return a brief summary in conversation."
+
+If `arn-spark-ux-specialist` is unavailable: proceed with product strategist feedback only. Note the limitation: "UX specialist was unavailable. Review is based on product strategist feedback only."
+
+After the UX specialist completes, read the review file at the specified path to extract the full feedback.
+
+### Step 6: Revise All Use Cases (Batch)
+
+Read the review files written by the experts (not from conversation context):
+- `[use-cases-dir]/reviews/round-N-business-review.md`
+- `[use-cases-dir]/reviews/round-N-flow-review.md`
+
+Combine feedback from both review files into a consolidated per-use-case list. For each use case, merge product strategist and UX specialist feedback items.
+
+**If feedback conflicts exist** (one expert says something contradicts the other), present the conflict to the user for resolution before sending to the writer:
+
+"Expert feedback conflict on **UC-NNN [Title]**:
+- **Product strategist:** [position]
+- **UX specialist:** [position]
+
+Which direction should the use case take?"
+
+Once conflicts are resolved, revise use cases in parallel using the same grouping strategy as Step 3. Each `arn-spark-use-case-writer` receives:
+- **Existing draft paths:** the current use case files for its assigned UC-IDs
+- **Combined per-use-case feedback:** only the feedback for its assigned UCs
+- **Use case catalog:** the FULL catalog (for cross-reference awareness)
+- **Use case template:** (same path)
+- **Output directory:** `use-cases/` (overwrites existing files)
+
+After all parallel writers complete, invoke one final writer to update the README index.
+
+#### Step 6b: Convergence Check
+
+Evaluate the writer's revision report against the convergence criteria in the review protocol:
+
+**Proceed to Step 7 (convergence reached) when:**
+- No missing actors flagged by either reviewer
+- No missing use cases flagged
+- No goals challenged as fundamentally wrong
+- All feedback was refinement-level (wording, granularity, additional extensions)
+- No conflicting business rules remain
+
+**Trigger one more review round (repeat Steps 4-6) when ANY of these exist:**
+- A reviewer flagged a missing actor that was not added
+- A reviewer flagged a missing use case that was not created
+- A use case goal was challenged and not resolved
+- Business rules conflict between use cases
+- The writer reported feedback that could not be addressed
+
+Maximum 2 review rounds total. This keeps total agent invocations to 4-7.
+
+Present the revision summary: "[N] use cases revised based on expert feedback. [Summary of major changes]. [Review round status: complete / one more round needed]."
+
+### Step 7: User Review
+
+Present the final use case catalog:
+
+"**Use case authoring complete.**
+
+**Summary:**
+- **Use cases:** [N] total ([X] user-goal, [Y] subfunction, [Z] summary)
+- **Actors:** [N] actors ([X] primary, [Y] secondary, [Z] supporting)
+- **Review rounds:** [N]
+
+**Use Case Catalog:**
+| UC-ID | Title | Actor | Level | Priority | Status |
+|-------|-------|-------|-------|----------|--------|
+| UC-001 | [Title] | [Actor] | User Goal | Must-have | Final |
+| UC-002 | [Title] | [Actor] | User Goal | Should-have | Final |
+| ... | ... | ... | ... | ... | ... |
+
+All files are in the `use-cases/` directory. Read any use case: `use-cases/UC-001-device-pairing.md`.
+
+Ask the user:
+
+**"What would you like to do?"**
+
+Options:
+1. **Adjust a specific use case** — Tell me which one and what to change
+2. **Add new use cases** — I will extend the catalog
+3. **Proceed** — Use cases are complete"
+
+If the user wants adjustments: invoke `arn-spark-use-case-writer` with the specific use case and the user's change request.
+If the user wants new use cases: return to Step 2 with the additions (existing use cases are preserved).
+If the user is satisfied: proceed to Step 8.
+
+### Step 8: Recommend Next Steps
+
+"Use cases saved to `use-cases/`.
+
+These use cases are now available as input for downstream skills:
+1. **Scaffold the project:** Run `/arn-spark-scaffold` to set up the development skeleton
+2. **Explore visual style:** Run `/arn-spark-style-explore` to establish the visual direction
+3. **Prototype the UI:** Run `/arn-spark-clickable-prototype` -- use cases will enrich screen derivation and replace manually defined journeys
+4. **Extract features:** Run `/arn-spark-feature-extract` -- use cases provide structured behavioral specs for richer feature extraction
+
+Use cases are living documents. As the project evolves, run `/arn-spark-use-cases` again to add or revise them."
+
+## Agent Invocation Guide
+
+| Situation | Action |
+|-----------|--------|
+| Expert use case discovery (Step 2b) | Invoke `arn-spark-product-strategist` with product concept + initial catalog for missing actors/use cases from business perspective. Then invoke `arn-spark-ux-specialist` with same + screen refs for missing user flows and interaction patterns. |
+| Draft all use cases (Step 3) | Invoke multiple `arn-spark-use-case-writer` agents in parallel, each with full catalog + assigned UC subset. Then one final writer for the README index. |
+| Product strategist review (Step 4) | Invoke `arn-spark-product-strategist` with all UC content, business review focus instructions, expert review template path, and file path to write to (`reviews/round-N-business-review.md`). Read the file after completion. |
+| UX specialist review (Step 5) | Invoke `arn-spark-ux-specialist` with all UC content, screen refs, flow review focus instructions, expert review template path, and file path to write to (`reviews/round-N-flow-review.md`). Read the file after completion. |
+| Revise all use cases (Step 6) | Invoke multiple `arn-spark-use-case-writer` agents in parallel, each with its assigned UC drafts + feedback. Then one final writer for the README index. |
+| Second review round (Step 6b) | Repeat Steps 4-6 if convergence criteria not met. Max 2 rounds. |
+| User requests specific UC adjustment (Step 7) | Invoke `arn-spark-use-case-writer` with the specific UC path and the user's change description |
+| User wants to add new use cases | Return to Step 2 with additions to the catalog |
+| User asks about technology choices | Defer: "Use cases describe behavior, not implementation. Technology choices are in `/arn-spark-arch-vision`." |
+| User asks about screen design | Defer: "Screen design is handled by `/arn-spark-style-explore` and `/arn-spark-clickable-prototype`. Use cases focus on what the system does, not how it looks." |
+| User asks about features | Defer: "Feature extraction happens in `/arn-spark-feature-extract`, which will consume these use cases as input." |
+| User asks about implementation specs | Defer: "Implementation specifications are created by `/arn-code-feature-spec`. Use cases provide the behavioral foundation that feature specs build on." |
+| Product strategist returns vague feedback | Re-invoke with more specific prompt: "Review each use case individually. For each, provide at least one Critical or Minor feedback item with a specific observation and suggestion." |
+| UX specialist unavailable | Proceed with product strategist review only. Note the limitation in all subsequent summaries. |
+
+## Error Handling
+
+- **No product concept found and user declines to describe:** Cannot proceed meaningfully. Suggest: "Run `/arn-spark-discover` first to define what you are building."
+- **Product concept is very brief:** Proceed but warn: "The product concept has limited detail. Use cases may be thin and need more revision. Consider expanding the product concept with `/arn-spark-discover` first."
+- **arn-spark-use-case-writer fails to write files:** Print the use case content in conversation so the user can copy it manually. Suggest checking file permissions or the output directory path.
+- **arn-spark-product-strategist returns unhelpful review:** Re-invoke with more specific instructions referencing the review protocol format. If still unhelpful, proceed to UX specialist review and note the limitation.
+- **arn-spark-ux-specialist unavailable:** Proceed with product strategist review only. Note the limitation. The review will be less thorough on flow quality and interaction completeness.
+- **User cancels mid-process:** Inform the user that partial use case files exist in `use-cases/` and they can resume later by running `/arn-spark-use-cases` again.
+- **Very large number of use cases (>15):** Warn the user: "This is a large number of use cases, which increases review time and token cost. I recommend focusing on must-have use cases first and adding should-have and nice-to-have in a follow-up run."
+- **Expert feedback conflicts:** Present the specific conflict to the user with both positions. User resolves before the writer revises.
+- **Revision introduces new issues:** Caught by the second review round (Step 6b). Maximum 2 rounds prevents infinite loops.
+- **No actors identified from product concept:** Ask the user directly: "I could not identify clear actors from the product concept. Who uses this application and what do they want to accomplish?"
+- **Product strategist returns no suggestions in Step 2b:** The initial extraction was already comprehensive. Proceed with the initial catalog.
+- **UX specialist unavailable in Step 2b:** Proceed with the initial extraction + product strategist suggestions only. Note the limitation — user flow gaps may be caught later during the UX review in Step 5.
+- **Use case level ambiguity:** Default to user-goal level. Only create subfunction use cases when a substep is clearly reused by 2+ user-goal use cases and is complex enough to warrant its own document.
+- **Prototype screens change after use cases are written:** Use cases remain valid because they describe behavior, not screens. Screen references can be updated by running `/arn-spark-use-cases` again with the "Continue" option.
+- **Writing the index/README fails:** Print the index content in conversation so the user can save it manually.
+- **User wants to add a use case during review (Steps 4-6):** Accept the addition. Add it to the catalog and include it in the current or next writer invocation.
+- **Resume with corrupted or incomplete files:** Offer a fresh start. If the user wants to preserve partial work, read what exists and present it for the user to decide what to keep.

package/plugins/arn-spark/skills/arn-spark-use-cases/references/expert-review-template.md

@@ -0,0 +1,94 @@
+# Expert Review Template
+
+This template defines the file format that expert agents (arn-spark-product-strategist, arn-spark-ux-specialist) use when writing their use case review reports to disk. Writing reviews to files ensures they survive context compression and provides a full audit trail.
+
+## File Naming Convention
+
+All review files go in `[use-cases-dir]/reviews/`. Create the directory if it does not exist.
+
+### arn-spark-use-cases (independent reviews, no debate)
+
+```
+reviews/
+├── round-N-business-review.md       ← Product strategist review
+└── round-N-flow-review.md           ← UX specialist review (if available)
+```
+
+### arn-spark-use-cases-teams (debate reviews)
+
+```
+reviews/
+├── round-N-business-review.md       ← Product strategist Phase 1
+├── round-N-flow-review.md           ← UX specialist Phase 1 (+Phase 2 in sequential mode)
+├── round-N-business-cross-review.md ← Product strategist Phase 2 response
+├── round-N-flow-cross-review.md     ← UX specialist Phase 2 response (Agent Teams mode only)
+├── round-N-review-report.md         ← Synthesized debate report (written by skill)
+└── final-report.md                  ← Aggregated final report (written by skill)
+```
+
+## Template
+
+When an expert writes their review, the file must follow this structure:
+
+```markdown
+# Expert Review: Round [N] — [Business Reviewer / Flow Reviewer]
+
+**Agent:** [arn-spark-product-strategist / arn-spark-ux-specialist]
+**Phase:** [Phase 1: Independent Review / Phase 2: Cross-Review / Phase 1 + Phase 2 Combined]
+**Mode:** [Sequential / Agent Teams / Single-Reviewer / Independent]
+**Use cases reviewed:** [count]
+
+---
+
+## Per-Use-Case Feedback
+
+**UC-NNN: [Title]**
+- **[Critical]:** [Specific observation] --> [Specific suggestion]
+- **[Minor]:** [Specific observation] --> [Specific suggestion]
+
+[Repeat for each use case with findings. Use cases with no findings may be omitted.]
+
+## Cross-Cutting Observations
+
+- **Missing use case:** [Description of what behavior is not captured]
+- **Missing actor:** [Who is not represented and what they do]
+- **Scope concern:** [What appears out of scope or missing from scope]
+- **Consistency issue:** [What is inconsistent across use cases]
+
+[For Phase 2 cross-review, add the following section after the above:]
+
+## Cross-Review Response
+
+### Response to [Business/Flow] Reviewer's Findings
+
+**UC-NNN: [Title]**
+- **Agree:** [item from other expert] -- [supporting reason or additional evidence]
+- **Disagree:** [item from other expert] -- [counterargument with specific reasoning]
+- **New concern prompted:** [description of something their finding revealed]
+
+### Response to Cross-Cutting Observations
+- **Agree:** [item] -- [reason]
+- **Disagree:** [item] -- [counterargument]
+- **New concern prompted:** [description]
+```
+
+## Instructions for Expert Agents
+
+When instructed to write a review:
+
+1. Read all use case files provided
+2. Perform the review according to your focus area
+3. Read this template to understand the expected format
+4. Write your review to the file path specified by the caller
+5. Return a brief summary in conversation (what you reviewed, how many findings, key concerns) — the full detail is in the file
+
+The file contains the COMPLETE review. The conversation summary is just an acknowledgment — downstream steps read from the file, not from the conversation.
+
+## Instructions for the Skill (Facilitator)
+
+When orchestrating expert reviews:
+
+1. Tell each expert agent the exact file path to write to and the path to this template
+2. When invoking the next expert (cross-review), tell it to READ the previous expert's file — pass the file path, not the file content
+3. When synthesizing the debate report, read ALL review files from the current round
+4. Never rely on the expert's conversation summary for synthesis — always read the file

package/plugins/arn-spark/skills/arn-spark-use-cases/references/review-protocol.md

@@ -0,0 +1,150 @@
+# Use Case Review Protocol
+
+This document defines the team review process for use case documents. The `arn-spark-use-cases` skill follows this protocol to coordinate expert reviews and writer revisions efficiently while keeping token costs manageable.
+
+## Team Roles
+
+| Role | Agent | Perspective |
+|------|-------|-------------|
+| Writer | `arn-spark-use-case-writer` | Drafts and revises use case documents in Cockburn format |
+| Business Reviewer | `arn-spark-product-strategist` | Business relevance, scope alignment, actor/goal accuracy, priority |
+| Flow Reviewer | `arn-spark-ux-specialist` | Flow quality, user-friendliness, interaction completeness, accessibility |
+
+The skill acts as the **facilitator**: it does not participate in the review but orchestrates the agents, combines feedback, checks convergence, and presents results to the user.
+
+## Review Process
+
+### Round 1: Draft + Full Review
+
+**Step 1: Writer drafts all use cases** (1 invocation)
+- Reads product concept, templates, and any existing screen references
+- Writes all UC files and the README index
+- Reports gaps and assumptions made during drafting
+
+**Step 2: Business reviewer reviews all use cases** (1 invocation)
+
+Focus areas:
+- Are all business-relevant actors identified?
+- Does each use case goal align with the product concept's stated capabilities?
+- Are priorities consistent with product scope boundaries (v1 vs. future)?
+- Are there missing use cases for capabilities described in the product concept?
+- Do extensions cover business-relevant exceptions (payment failures, policy violations, resource limits)?
+- Are business rules complete, correct, and specific to each use case?
+- Is scope appropriate -- no use cases that exceed the product concept's boundaries?
+- Do the use case levels make sense (are subfunctions actually reused, are user goals actually what a user sits down to do)?
+
+**File output:** The business reviewer writes its review to `[use-cases-dir]/reviews/round-N-business-review.md` using the expert review template (`${CLAUDE_PLUGIN_ROOT}/skills/arn-spark-use-cases/references/expert-review-template.md`). The skill tells the agent the exact file path and template path. The agent returns a brief summary in conversation — the full review is in the file.
+
+**Step 3: Flow reviewer reviews all use cases** (1 invocation)
+
+Focus areas:
+- Is the main success scenario natural from the actor's perspective?
+- Are actor-system steps at the right granularity (not too detailed, not too vague)?
+- Are common interaction patterns covered? Specifically:
+  - Cancel/abort at reasonable points
+  - Undo or back-navigation where applicable
+  - Timeout or inactivity handling
+  - Retry after failure
+  - Empty states (no items found, no devices available)
+- Are error recovery flows present for likely failures?
+- Is accessibility considered (alternative interaction paths, non-visual feedback)?
+- Do preconditions and postconditions make sense as observable, verifiable states?
+- Are related use cases properly connected (bidirectional references)?
+- Is step granularity consistent across use cases (one UC has 4 steps while a similar one has 12)?
+
+**File output:** The flow reviewer writes its review to `[use-cases-dir]/reviews/round-N-flow-review.md` using the same expert review template. The skill tells the agent the exact file path and template path.
+
+**Step 4: Writer revises all use cases** (1 invocation)
+- The skill reads the review files written by the experts (not from conversation context)
+- Combines feedback from both review files into a consolidated per-use-case list
+- Sends combined feedback to the writer
+- Writer applies changes to all use case files
+- Updates README index if relationships or actors changed
+- Reports: changes made per UC, any feedback that could not be fully addressed, any conflicting feedback between reviewers
+
+### Round 2: Convergence Check (Conditional)
+
+The skill evaluates the writer's revision report to decide whether a second round is needed.
+
+**Proceed without Round 2 (convergence reached) when:**
+- No missing actors were flagged by either reviewer
+- No missing use cases were flagged
+- No use case goals were challenged as fundamentally wrong or out of scope
+- All feedback was refinement-level: wording improvements, additional extensions, granularity adjustments, minor precondition/postcondition fixes
+- No conflicting business rules between use cases remain unresolved
+
+**Trigger Round 2 when ANY of these exist after revision:**
+- A reviewer flagged a missing actor that was not added
+- A reviewer flagged a missing use case that was not created
+- A use case goal was challenged as wrong or out of scope and was not resolved
+- Business rules conflict between use cases (e.g., UC-001 says max 4 participants, UC-002 says max 8)
+- The writer reported feedback items that could not be addressed
+
+**Round 2 steps** (if triggered):
+
+**Step 5: Business reviewer re-reviews** (1 invocation)
+- Focuses only on previously flagged critical issues
+- Verifies that major concerns from Round 1 were addressed
+- May flag NEW issues discovered in the revisions
+- Writes review to `[use-cases-dir]/reviews/round-N-business-review.md` (N=2 for Round 2)
+
+**Step 6: Flow reviewer re-reviews** (1 invocation)
+- Focuses only on previously flagged critical issues
+- Verifies that flow concerns were addressed
+- May flag new issues in revised flows
+- Writes review to `[use-cases-dir]/reviews/round-N-flow-review.md` (N=2 for Round 2)
+
+**Step 7: Writer applies final revisions** (1 invocation)
+- The skill reads the Round 2 review files written by the experts
+- Addresses Round 2 feedback
+- Updates all affected files
+
+### Maximum Invocations
+
+| Scenario | Writer | Strategist | UX Specialist | Total |
+|----------|--------|-----------|---------------|-------|
+| Single review round (no structural issues) | 2 | 1 | 1 | 4 |
+| Two review rounds (structural issues found) | 2 | 2 | 2 | 6-7* |
+
+*The writer's final revision in Round 2 is the 7th invocation. If only one reviewer triggered Round 2, the other reviewer may be skipped in Round 2, reducing to 6.
+
+The process never exceeds 7 agent invocations.
+
+## Feedback Format
+
+Expert reviewers should structure their feedback as follows:
+
+### Per-Use-Case Feedback
+
+```markdown
+**UC-NNN: [Title]**
+- **[Critical]:** [Specific observation] --> [Specific suggestion]
+- **[Minor]:** [Specific observation] --> [Specific suggestion]
+```
+
+**Critical** feedback indicates issues that affect the use case's correctness, completeness, or alignment with the product concept. These MUST be addressed.
+
+**Minor** feedback indicates improvements to clarity, granularity, or style. These SHOULD be addressed but are not blockers.
+
+### Cross-Cutting Feedback
+
+```markdown
+**Missing use case:** [Description of what behavior is not captured by any existing use case]
+**Missing actor:** [Who is not represented in the actor catalog and what they do]
+**Scope concern:** [What appears to be out of scope or missing from scope relative to the product concept]
+**Consistency issue:** [What is inconsistent across use cases -- step granularity, terminology, business rules, actor naming]
+```
+
+Cross-cutting feedback is addressed by the writer across all affected use cases, not in a single UC.
+
+## Skill's Facilitation Responsibilities
+
+The `arn-spark-use-cases` skill (not the agents) is responsible for:
+
+1. **Telling each expert where to write:** Provide the exact file path and template path when invoking each expert. Create the `[use-cases-dir]/reviews/` directory if it does not exist.
+2. **Reading review files:** After each expert completes, read the review file (not the conversation summary) to extract feedback.
+3. **Combining feedback:** Merge per-UC feedback from both review files into a single combined list per UC before sending to the writer.
+4. **Flagging conflicts:** If both reviewers give contradictory feedback on the same UC, note the conflict and present it to the user for resolution before sending to the writer.
+5. **Convergence decision:** Evaluate the writer's revision report against the convergence criteria above.
+6. **User communication:** Present review summaries and revision results to the user between rounds.
+7. **Budget management:** Never exceed 2 review rounds (7 invocations).