/arn-spark-spike

name: arn-spark-spike
description: >-
  This skill should be used when the user says "spike", "arn spike",
  "validate risks", "technical validation", "proof of concept",
  "validate architecture", "risk spike", "test this risk", "will this work",
  "technical spike", "validate the stack", or wants to validate critical
  technical risks from the architecture vision by creating minimal
  proof-of-concept code and testing whether the chosen technologies work as
  expected.
version: 1.0.0

Arness Spike

Validate critical technical risks from the architecture vision through minimal proof-of-concept implementations, aided by the `arn-spark-spike-runner` agent for POC creation and execution. This is a conversational skill that runs in normal conversation (NOT plan mode). The primary artifacts are **spike POC code** in isolated directories and a **spike results document**.

This skill addresses the question: "Will the chosen technologies actually work for our use case?" It does not implement features or build the application -- it runs targeted experiments to validate or invalidate specific technical assumptions before committing to them.

Prerequisites

An architecture vision document should exist. Check in order:

1. Read the project's `CLAUDE.md` for a `## Arness` section. If found, check the configured Vision directory for `architecture-vision.md` 2. If no `## Arness` section found, check `.arness/vision/architecture-vision.md` at the project root

**If an architecture vision is found:** Read it and extract the "Known Risks & Mitigations" section.

**If no architecture vision is found:** Inform the user:

"No architecture vision document found. I can still run spikes if you describe the specific technical risks to validate. For a comprehensive risk assessment, run `/arn-spark-arch-vision` first."

If the user provides risks directly, proceed with those.

The project should ideally be scaffolded (via `/arn-spark-scaffold`) so the spike runner can leverage the existing project setup. If not scaffolded, spikes will need to set up their own dependencies, which the spike runner handles.

Determine the spike workspace: 1. Read the project's `CLAUDE.md` and check for a `## Arness` section 2. If found, extract the configured Spikes 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

Workflow

Step 1: Identify Risks

Load the architecture vision and extract all risks from the "Known Risks & Mitigations" section. Parse each risk to identify:

• **Risk title:** Brief name
• **Description:** What could go wrong
• **Validation priority:** Critical (must validate before any code), Important (validate in first sprint), Monitor (keep an eye on)
• **Suggested mitigation:** What the architecture vision proposes as a fallback

If additional validation points were noted in the tech evaluator's recommendations during the architecture vision phase, include those as well.

Present the risk list to the user:

"I found [N] risks in your architecture vision. Here they are by priority:

**Critical:** 1. [Risk title] -- [brief description] 2. [Risk title] -- [brief description]

**Important:** 3. [Risk title] -- [brief description]

**Monitor:** 4. [Risk title] -- [brief description]

Ask (using `AskUserQuestion`) with `multiSelect: true`:

**"Which risks would you like to spike? (select multiple)"**

Options: [List each risk as a numbered option with its title and brief description, e.g.:] 1. **[Risk 1 title]** — [brief description] 2. **[Risk 2 title]** — [brief description] 3. **[Risk 3 title]** — [brief description]

If the user adds custom risks not from the architecture vision, include those.

Step 2: Define Validation Criteria (Per Risk)

For each selected risk, propose a minimal POC approach and clear validation criteria:

"For **[Risk Title]**:

**POC approach:** [What we will build to test this. 1-2 sentences describing the minimal experiment.]

**Validation criteria:**

• [Specific, measurable criterion 1]
• [Specific, measurable criterion 2]

**Spike directory:** `<configured Spikes directory>/spike-[NNN]-[descriptive-name]/`

Does this approach look right, or would you test it differently?"

Wait for user approval or adjustments before running each spike. The user may want to modify the approach, change criteria, or skip the risk.

Step 3: Execute Spikes

**IMPORTANT: Run spikes sequentially, one at a time.** Do NOT launch multiple spike-runner agents in parallel or in the background. The spike-runner agent needs Bash and Write tool access, which requires user permission approval. Parallel or background agents cannot surface permission prompts to the user, causing all tool calls to be denied. Wait for each spike to fully complete before starting the next one.

For each approved spike, in order:

1. Invoke the `arn-spark-spike-runner` agent via the Task tool (foreground, not background), 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:

• Risk description and context
• Validation criteria
• Project context (stack, existing scaffold location)
• Spike workspace path (e.g., `<Spikes directory>/spike-001-webrtc-wkwebview/`)

2. Wait for the agent to complete fully before proceeding.

3. Present the spike runner's results to the user:

• **Validated:** "Risk validated. [Brief evidence summary]. No architecture changes needed."
• **Partially Validated:** "Risk partially validated. [Caveats]. We should discuss whether these limitations are acceptable."
• **Failed:** "Risk failed validation. [Evidence]. Here are the altern