arn-spark-spike

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:

1. [Risk title] -- [brief description]

Monitor:

1. [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:
2. Risk description and context
3. Validation criteria
4. Project context (stack, existing scaffold location)
5. Spike workspace path (e.g., <Spikes directory>/spike-001-webrtc-wkwebview/)

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

1. Present the spike runner's results to the user:
2. Validated: "Risk validated. [Brief evidence summary]. No architecture changes needed."
3. Partially Validated: "Risk partially validated. [Caveats]. We should discuss whether these limitations are acceptable."
4. Failed: "Risk failed validation. [Evidence]. Here are the alternatives the spike runner identified: [list]. How would you like to proceed?"
5. Deferred: "Could not test this in the current environment. [What is needed]. The spike files and manual execution instructions are saved at [spike directory] -- you can run this spike manually on the required platform. This should be validated when [condition]."

1. If a spike failed:

Ask (using AskUserQuestion):

"Risk [Risk Title] failed validation. How would you like to proceed?"

Options:

1. Accept the risk — Proceed anyway with the current approach
2. Choose an alternative — Discuss trade-offs and pick a different approach
3. Update architecture vision — Revise the architecture to address the failure

1. Proceed to the next spike only after presenting results and resolving any failures.

Step 4: Write Spike Results Document

After all spikes have been run:

1. Read the spike report template:

> Read ${CLAUDE_PLUGIN_ROOT}/skills/arn-spark-spike/references/spike-report-template.md

1. Populate the template with all spike results

1. Determine the output directory:
2. Read the project's CLAUDE.md and check for a ## Arness section
3. If found, extract the configured Vision directory path — this is the source of truth
4. 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.

1. Write the document as spike-results.md

1. Present a summary:

"Spike results saved to [path]/spike-results.md.

Summary: | Risk | Result | |------|--------| | [Risk 1] | Validated | | [Risk 2] | Failed -- chose Alternative A | | [Risk 3] | Deferred -- needs macOS |

[N] of [M] risks validated. [Note any architecture changes decided.]"

Step 5: Update Architecture Vision (If Needed)

If any spikes failed and the user chose an alternative approach:

"Based on the spike results, the following sections of architecture-vision.md should be updated:

1. [Section]: [What to change and why]
2. [Section]: [What to change and why]

Ask (using AskUserQuestion):

Should I update the architecture vision now?

1. Yes — Update the affected sections

2. No — Skip for now, I will update manually later"

If the user chooses Yes, make the targeted updates to the architecture vision document. Only change the specific sections affe