@fredcallagan/arn-spark 5.1.0

package/plugins/arn-spark/skills/arn-spark-discover/references/discovery-questions.md

@@ -0,0 +1,120 @@
+# Product Discovery Questions
+
+Structured question bank for guided product discovery in greenfield projects. These are conversation guides, not a rigid questionnaire. Select questions based on what is weakest or most unclear in the user's description. Never ask all questions at once.
+
+## 1. Vision & Problem
+
+- What specific problem does this solve? Who has this problem today?
+- What do people currently do without this product? What is painful or inefficient about their current approach?
+- In one sentence, what is this product? (Forces clarity)
+- What would success look like six months after launch?
+- Is this a "vitamin" (nice to have) or a "painkiller" (solves an urgent need)?
+- How severe is this problem? Is it a daily frustration or an occasional inconvenience?
+- Can you describe a specific recent moment when someone experienced this problem?
+- If this problem disappeared tomorrow, what would change in the user's daily workflow?
+- Who else is affected when this problem occurs? (teammates, customers, family, downstream systems)
+
+## 2. Target Users & Personas
+
+- Who is the primary user? Describe them specifically -- not "developers" but "solo developers working on side projects who need quick feedback."
+- What is the user doing when they reach for this product? What triggered that moment?
+- Are there secondary users or stakeholders who benefit but are not the primary user?
+- How technically sophisticated is the target user? Does the product need to be zero-configuration or is customization expected?
+- What does a typical day look like for your primary user? When does the problem surface in their routine?
+- What has your target user already tried to solve this problem? Why did those attempts fail or fall short?
+- How does the target user currently discover new tools? (peer recommendation, search, app store, conference talks, social media)
+- What would make someone stop using your product after trying it? What is their breaking point?
+- Are there users you explicitly do NOT want to serve? Who is this product NOT for?
+
+## 3. Core Experience
+
+- What is the primary interaction? Walk me through the "moment of magic" -- what does the user experience that makes this product valuable?
+- What does the user see and feel when they first open this product?
+- What is the single most important thing this product does? If it could only do one thing, what would that be?
+- How frequently will users interact with this? Multiple times a day, daily, weekly?
+- Is this product used actively (user initiates) or passively (runs in background)?
+
+## 4. Trust & Security Model
+
+- How do users discover each other or access the product? Is discovery automatic or manual?
+- What trust model applies? (No auth, device pairing, user accounts, invite codes, OAuth, etc.)
+- What is the security posture? (Casual/personal, team/workplace, regulated/enterprise)
+- What data is sensitive? What would be the impact of unauthorized access?
+- Does the product need to work without an internet connection?
+
+## 5. Platform & Constraints
+
+- What platforms must be supported on day one? (Desktop, mobile, web, specific OS versions)
+- Are there performance requirements? (Latency, throughput, response time, battery usage)
+- What about offline support? Does it need to work without network access?
+- Are there size or resource constraints? (Embedded, low-memory, bandwidth-limited)
+- How will users install or access this? (App store, installer, browser, CLI)
+
+## 6. Participants & Scale
+
+- How many simultaneous users or devices are expected?
+- What is the communication or interaction topology? (1:1, room/group, broadcast, hub-and-spoke)
+- How does the experience change with more participants? Is there a natural upper limit?
+- Do all participants have equal roles or are there different permission levels?
+
+## 7. Scope Boundaries
+
+- What is explicitly NOT part of v1? What features have you thought about but want to defer?
+- What features sound essential but could actually wait?
+- What is the absolute minimum version that delivers the core value?
+- Are there adjacent products or features that should remain separate?
+- What would you cut if you had to ship in half the time?
+
+## 8. Product Pillars
+
+These questions surface the non-negotiable qualities that define the product's soul -- the standards that every feature, design choice, and trade-off should be measured against. Pillars are not features; they are commitments. Ask these throughout the conversation, not as a separate block. Look for moments when the user expresses strong conviction ("it HAS to feel...", "the whole point is...", "I refuse to compromise on...").
+
+- What quality or feeling should this product absolutely nail? If the product does everything else right but gets this wrong, would it still feel like a failure?
+- When you imagine a user recommending this product to someone else, what would they say about it? What one word or phrase would they use?
+- Are there products you admire not for what they do, but for how they do it? What specifically about their approach resonates?
+- If you had to cut a feature to protect the quality of the experience, would you? What would you never compromise even under deadline pressure?
+- What would make this product feel cheap or wrong? What is the opposite of what you are trying to build?
+
+## 9. Business Model & Constraints
+
+These questions surface business-model constraints that directly affect architecture and technology choices. Multi-tenancy models, regulatory requirements, budget caps, and vendor preferences can eliminate technology options entirely — a SaaS with 500 tenants cannot use a service with hard per-project connection limits, and HIPAA compliance restricts which cloud providers are viable. Capture concrete numbers, not vague aspirations.
+
+- What is the business model? (B2C, B2B SaaS, marketplace, self-hosted, white-label, enterprise on-prem)
+- Is this multi-tenant? If so, how many tenants/clients are expected at launch? At scale? (10, 100, 500, 1000+)
+- What tenant isolation level is needed? (shared database, schema-per-tenant, database-per-tenant, infrastructure-per-tenant)
+- Are there regulatory or compliance requirements? (GDPR, HIPAA, SOC2, PCI-DSS, FedRAMP, ISO 27001)
+- Are there data residency requirements? (data must stay in EU, US, specific country)
+- What is the budget constraint for cloud/infrastructure costs? (monthly spend target, per-tenant cost target)
+- Is there a preference for or against specific vendors? (must use AWS, avoid Google, open-source only)
+- What is the licensing constraint? (open-source only, no AGPL, commercial licenses acceptable)
+- What is the team's technical experience? (languages, frameworks, cloud providers they know)
+- Is there a hard timeline or market window? (MVP by Q3, launch before competitor X)
+- Are there existing systems this must integrate with? (legacy APIs, specific databases, SSO providers)
+- Is vendor lock-in acceptable? (fully managed services OK, or must be portable/self-hostable)
+
+## 10. Competitive Landscape
+
+These questions surface the competitive context. Not all products need deep research (internal tools, hobby projects, genuinely novel spaces may have few competitors). The goal is understanding what users do today and what alternatives exist, not building a competitive strategy. When the user cannot name competitors, offer AI-assisted market research via arn-spark-market-researcher.
+
+- What do people use today to solve this problem? (Include manual processes, spreadsheets, and "doing nothing" as valid answers)
+- Can you name any direct competitors? What do they do well? What do they get wrong?
+- Are there adjacent products that partially solve this problem even though it is not their main purpose?
+- Why would someone choose your product over the alternatives? What is your unfair advantage?
+- Is the market for this solution growing, stable, or shrinking? What is driving the trend?
+- Are there competitors you admire? What specifically about their approach do you want to learn from or avoid?
+
+## 11. Assumptions & Success Criteria
+
+These questions are typically NOT asked directly. The AI synthesizes assumptions from the conversation and presents them for validation. The questions below are fallbacks for when direct probing is needed.
+
+Assumptions:
+- What is the biggest bet you are making with this product? What has to be true for it to work?
+- What do you believe about your users that you have not yet verified?
+- What market or behavioral trend are you counting on?
+- If you had to name one thing that could make this product fail, what would it be?
+
+Success Criteria:
+- How will you know this product is working? What does success look like in concrete numbers?
+- What is the minimum number of users, transactions, or interactions that would make this worth continuing?
+- Six months after launch, what metric would make you feel this is succeeding? What would make you feel it is failing?
+- Is there a leading indicator you could measure in the first week to predict long-term success?

package/plugins/arn-spark/skills/arn-spark-discover/references/persona-profile-template.md

@@ -0,0 +1,97 @@
+# Persona Profile Template
+
+This template defines the dual-layer persona format for the Target Personas section of `product-concept.md`. Each persona archetype includes two layers: an **abstracted profile (mould)** and a **concrete example persona**.
+
+The abstracted profile is a generative template -- it defines ranges, patterns, and variation axes rather than single data points. Future skills (e.g., Synthetic User Panel) use moulds to generate fresh concrete persona instances for stress-testing and simulation. The concrete example is a specific, vivid character that was validated during the discovery conversation. Both layers are required for every archetype.
+
+## Instructions for arn-spark-discover
+
+When populating this template:
+
+- Populate from the `arn-spark-persona-architect` agent's output. The agent produces concrete examples first (for user interaction and critique), then derives abstracted moulds after user approval. Write both layers per archetype.
+- When the user provides concrete personas directly (names, roles, specific details), those become seeds. The persona-architect expands them into full profiles and derives moulds. Do not discard user-provided personas -- they represent domain expertise.
+- Every archetype MUST include both layers. Do not flatten the mould into a summary paragraph or merge it with the concrete example. The dual-layer structure is required for downstream reuse.
+- The moulds are the primary reusable artifact. Concrete examples are illustrative; moulds are generative.
+- Include 2-4 archetypes. 2-3 is ideal. At least one should represent a skeptic or reluctant adopter.
+- End with a Differentiation Summary table that maps all personas across key distinguishing dimensions.
+- If the user declines persona generation entirely, write: `Not explored during discovery.`
+- If personas are genuinely not applicable (e.g., fully automated system with no user-facing interaction -- rare), write: `Not applicable -- [reason].`
+
+---
+
+## Template
+
+```markdown
+## Target Personas
+
+[2-4 persona archetypes identified during discovery. Each includes an abstracted profile (the "mould" -- a generative template for producing concrete instances) and one concrete example persona that was validated during conversation. The moulds can be used by future skills to generate additional concrete personas for stress-testing, simulation panels, and validation.]
+
+### Archetype: The [Archetype Label]
+
+#### Abstracted Profile (Mould)
+
+**Demographic range:** [Age range, profession spectrum, sophistication range -- expressed as ranges, not single points]
+
+**Personality spectrum:** [Range of personality traits for this archetype -- e.g., "pragmatic <-> idealistic", "risk-tolerant <-> risk-averse", "vocal <-> reserved". Concrete instances pick specific positions along these spectrums.]
+
+**Core motivation pattern:** [The underlying drive shared by all instances of this archetype]
+
+**Pain pattern:** [The category of frustrations -- what kind of problems they face, not specific instances]
+
+**Adoption pattern:** [What type of trigger drives them to seek solutions, what type of threshold makes them leave]
+
+**Variation axes:**
+- [Dimension 1 that varies between instances, e.g., "technical depth: self-taught -> CS degree"]
+- [Dimension 2, e.g., "urgency: casual exploration -> deadline-driven"]
+- [Dimension 3 if applicable]
+
+**Boundary conditions:** [What would NOT be this archetype -- helps distinguish from other moulds]
+
+#### Concrete Example: [Persona Name]
+
+**Demographics:** [Age, profession, technical sophistication, context (solo/team/enterprise)]
+
+**Personality Traits:** [3-5 traits that define how this person thinks, decides, and communicates -- e.g., pragmatic, risk-averse, vocal in meetings, data-driven, impatient with slow tools]
+
+**Goals:** [What they are trying to achieve -- primary and secondary]
+
+**Pain Points:**
+- [Specific frustration #1 with current state]
+- [Specific frustration #2]
+- [Specific frustration #3]
+
+**Current Workarounds:** [Tools or processes they use today, and why they fall short]
+
+**Decision Factors:** [What drives adoption for this person -- price, ease of use, peer validation, trust, feature completeness]
+
+**Day-in-the-Life:** [2-3 sentences showing a specific moment when the problem surfaces -- time, place, what goes wrong, how they feel]
+
+**Adoption Trigger:** [The specific event or moment that makes them actively seek a solution]
+
+**Frustration Threshold:** [What would make them stop using the product after trying it]
+
+[Repeat "### Archetype: The [Label]" block for each persona archetype (2-4 total)]
+
+### Differentiation Summary
+
+| Dimension | [Persona 1 Name] | [Persona 2 Name] | [Persona 3 Name] |
+|-----------|-------------------|-------------------|-------------------|
+| Primary motivation | [key driver] | [key driver] | [key driver] |
+| Technical sophistication | [level] | [level] | [level] |
+| Adoption posture | [eager/cautious/skeptical] | [posture] | [posture] |
+| Pain severity | [high/medium/low] | [severity] | [severity] |
+| Decision style | [style] | [style] | [style] |
+```
+
+---
+
+## Section Guidance
+
+| Section | Source | Depth |
+|---------|--------|-------|
+| Archetype Label | arn-spark-persona-architect output, user-validated | Short, memorable label (e.g., "The Solo Indie Dev", "The Reluctant Enterprise Admin") |
+| Abstracted Profile (Mould) | Derived by persona-architect after user approves concrete examples | All 7 fields required: demographic range, personality spectrum, core motivation pattern, pain pattern, adoption pattern, variation axes (2-3), boundary conditions. Express everything as ranges or patterns, never single data points. |
+| Concrete Example | Generated by persona-architect (discovery mode), or expanded from user-provided seeds, then user-validated | All 10 fields required: name, demographics, personality traits (3-5), goals, pain points (3), current workarounds, decision factors, day-in-the-life, adoption trigger, frustration threshold. Must be vivid and specific. |
+| Differentiation Summary | Synthesized from approved personas | Table with one row per distinguishing dimension, one column per persona. Highlights what makes each archetype distinct. |
+| User-provided personas | User provides names, roles, and partial details during conversation | Accept as seeds. Persona-architect expands into full profiles (filling demographics, personality, pain points, workarounds, day-in-the-life, etc. grounded in domain research). Present expanded profiles for approval. Derive moulds from approved expanded profiles. Never discard user-provided input. |
+| Vague user descriptions | User says "developers" or "small business owners" without specifics | Persona-architect researches the domain and generates 2-4 distinct concrete examples from the vague description. Each must be differentiated on at least 2 axes (motivation, sophistication, urgency, adoption posture). Present for user critique and refinement. |

package/plugins/arn-spark/skills/arn-spark-discover/references/product-concept-template.md

@@ -0,0 +1,253 @@
+# Product Concept Template
+
+This template defines the structure for product concept documents written by the `arn-spark-discover` skill. The document is saved to the project's vision directory as `product-concept.md`.
+
+A product concept captures the WHAT and WHY of the product at a high level: the vision, core experience, target users, trust model, platform scope, and explicit boundaries. It does not address HOW to build it -- that is the architecture vision's job.
+
+## Instructions for arn-spark-discover
+
+When populating this template:
+
+- Every section below MUST appear in the output, even if the content is brief
+- Replace all bracketed placeholders with concrete content from the discovery conversation
+- If information is missing for a section, write what you know and add the gap to a note at the end
+- Adapt subsection names to match the product (e.g., "The Widget" for a desktop app, "The Feed" for a social app)
+- Core Experience subsections should reflect the product's actual interaction modes, not generic categories
+- Product Pillars must come from the user's own convictions, not generic best practices. If the user said "polish is everything," that is a pillar. Do not invent pillars the user did not express. If fewer than 3 emerged from the conversation, ask the user to confirm whether any are missing before writing.
+- Future Considerations should list items that were explicitly discussed and deferred, not speculative features
+- Write in present tense, as if the product exists ("Talkie lives as a small widget" not "Talkie will live as a small widget")
+- For AI-assisted sections (Problem Statement, Target Personas, Competitive Landscape, Key Assumptions, Success Criteria): use the user-approved content. If a section was offered but declined, write "Not explored during discovery." If not applicable, write "Not applicable -- [reason]." Never leave these sections blank without explanation.
+- Target Personas must include BOTH layers: (1) abstracted persona profiles ("moulds") that define the archetype's ranges, patterns, and variation axes, and (2) concrete example personas that were validated during conversation. The moulds are the primary reusable artifact — future skills use them to generate fresh concrete instances. Do not flatten either layer into a single paragraph.
+- Competitive Landscape must include source URLs if market research was conducted. Mark unverified claims accordingly.
+- Key Assumptions are hypotheses, not facts. Frame them as testable statements with confidence levels.
+
+---
+
+## Template
+
+```markdown
+# [Product Name] - Product Concept
+
+## Vision
+
+[2-4 sentences. What is this product, who is it for, and what makes it different from existing solutions. Core value proposition. Tone: aspirational but concrete. Avoid buzzwords.]
+
+## Problem Statement
+
+**The problem:** [1-2 sentences — what specific problem exists, stated clearly and concretely]
+
+**Who experiences it:** [Specific roles, situations, or contexts — not generic categories]
+
+**Current workarounds:** [How people cope today — tools, manual processes, or "nothing"]
+
+**Why existing solutions fall short:** [What is painful, slow, expensive, or missing about current approaches]
+
+**Severity:** [Painkiller (urgent, frequent pain) / Vitamin (nice-to-have, gradual improvement) / Infrastructure (invisible but essential) — with justification]
+
+## Target Personas
+
+[2-4 persona archetypes identified during discovery. Each includes an abstracted profile (the "mould" — a generative template for producing concrete instances) and one concrete example persona that was validated during conversation. The moulds can be used by future skills to generate additional concrete personas for stress-testing, simulation panels, and validation.]
+
+### Archetype: The [Archetype Label]
+
+#### Abstracted Profile (Mould)
+
+**Demographic range:** [Age range, profession spectrum, sophistication range — expressed as ranges, not single points]
+
+**Personality spectrum:** [Range of personality traits for this archetype — e.g., "pragmatic ↔ idealistic", "risk-tolerant ↔ risk-averse", "vocal ↔ reserved". Concrete instances pick specific positions along these spectrums.]
+
+**Core motivation pattern:** [The underlying drive shared by all instances of this archetype]
+
+**Pain pattern:** [The category of frustrations — what kind of problems they face, not specific instances]
+
+**Adoption pattern:** [What type of trigger drives them to seek solutions, what type of threshold makes them leave]
+
+**Variation axes:**
+- [Dimension 1 that varies between instances, e.g., "technical depth: self-taught → CS degree"]
+- [Dimension 2, e.g., "urgency: casual exploration → deadline-driven"]
+- [Dimension 3 if applicable]
+
+**Boundary conditions:** [What would NOT be this archetype — helps distinguish from other moulds]
+
+#### Concrete Example: [Persona Name]
+
+**Demographics:** [Age, profession, technical sophistication, context (solo/team/enterprise)]
+
+**Personality Traits:** [3-5 traits that define how this person thinks, decides, and communicates — e.g., pragmatic, risk-averse, vocal in meetings, data-driven, impatient with slow tools]
+
+**Goals:** [What they are trying to achieve — primary and secondary]
+
+**Pain Points:**
+- [Specific frustration #1 with current state]
+- [Specific frustration #2]
+- [Specific frustration #3]
+
+**Current Workarounds:** [Tools or processes they use today, and why they fall short]
+
+**Decision Factors:** [What drives adoption for this person — price, ease of use, peer validation, trust, feature completeness]
+
+**Day-in-the-Life:** [2-3 sentences showing a specific moment when the problem surfaces — time, place, what goes wrong, how they feel]
+
+**Adoption Trigger:** [The specific event or moment that makes them actively seek a solution]
+
+**Frustration Threshold:** [What would make them stop using the product after trying it]
+
+[Repeat "### Archetype: The [Label]" block for each persona archetype (2-4 total)]
+
+### Differentiation Summary
+
+| Dimension | [Persona 1 Name] | [Persona 2 Name] | [Persona 3 Name] |
+|-----------|-------------------|-------------------|-------------------|
+| Primary motivation | [key driver] | [key driver] | [key driver] |
+| Technical sophistication | [level] | [level] | [level] |
+| Adoption posture | [eager/cautious/skeptical] | [posture] | [posture] |
+| Pain severity | [high/medium/low] | [severity] | [severity] |
+| Decision style | [style] | [style] | [style] |
+
+## Product Pillars
+
+[3-5 non-negotiable qualities that define this product's soul. These are not features — they are the standards every feature, design choice, and architectural trade-off must be tested against. If a decision compromises a pillar, it should be reconsidered or rejected. Pillars flow through the entire pipeline: architecture must serve them, use cases must respect them, prototypes must demonstrate them, and features must embody them.]
+
+### [Pillar Name]
+
+[What this quality means for the product — not an abstract value, but a concrete commitment. Why it is non-negotiable: what happens to the product if this is compromised. Litmus test: a practical question to test any decision against this pillar. Example: "If a feature can't meet this standard within the timeline, defer it rather than ship it rough."]
+
+### [Pillar Name]
+
+[Same structure. Each pillar should be distinct — if two pillars overlap significantly, merge them.]
+
+### [Pillar Name]
+
+[Same structure. 3 pillars is the minimum. 5 is the maximum — more than 5 means nothing is truly prioritized.]
+
+## Competitive Landscape
+
+[Identified alternatives in this problem space, curated by the user. This is a landscape map — who exists and what they do — not a deep analysis. Detailed feature comparison and gap analysis can be performed separately via dedicated skills. The full research is preserved in tiers so future skills can draw from any level.]
+
+### Primary Competitors (Focus)
+[The user-validated top 5 — these are the most relevant alternatives to track and compare against]
+
+1. **[Name]** ([URL]) — [one-line description of approach and target user]
+   **Why primary:** [1 sentence rationale — relevance to problem space, user overlap, market presence]
+   **Confidence:** [Verified / Inferred / Unverified]
+
+2. **[Name]** ([URL]) — [one-line]
+   **Why primary:** [rationale]
+   **Confidence:** [tag]
+
+[... up to 5]
+
+### Extended Landscape
+[Additional validated alternatives kept for reference — may become relevant as the product evolves]
+
+- **[Name]** ([URL]) — [one-line] [Confidence: tag]
+[... up to ~10]
+
+### Indirect Alternatives
+- **Manual / "Do Nothing"** — [How people cope without a dedicated tool]
+- **[Generic tool]** — [How people repurpose general tools for this]
+
+**Initial positioning:** [1-2 sentences — where the proposed product sits relative to these alternatives and what gap it fills]
+
+### Research Metadata
+- **Research date:** [ISO 8601 date]
+- **Search coverage:** [N] queries across [M] search angles
+- **Raw candidates found:** [X]
+- **Validated alternatives:** [Y]
+- **Research mode:** Identification (landscape mapping only — deep analysis available via dedicated skills)
+
+## Core Experience
+
+### [Primary Interaction Mode]
+
+[Describe the main way users interact with the product. What do they see, what do they do, what happens? This is the "moment of magic" -- the experience that makes the product valuable. Be specific about the UX, not the technology.]
+
+### [Secondary Interaction Mode(s)]
+
+[Additional interaction patterns essential to v1. Each gets its own subsection with a descriptive name. Only include modes that are core to the product -- defer nice-to-haves to Future Considerations.]
+
+### [Discovery / Onboarding]
+
+[How do users get started? What is the first-run experience? How do they discover other users, content, or features? Keep it simple -- the best onboarding is minimal.]
+
+## Trust & Security Model
+
+### First-Time Setup
+
+[What happens when the user first installs or opens the product? What information do they provide? What identity is established?]
+
+### [Trust Establishment Mechanism]
+
+[How do users establish trust with each other or with the system? Device pairing, user accounts, invite codes, OAuth, etc. Describe the flow from the user's perspective.]
+
+### Per-[Entity] Settings
+
+[What can be configured per relationship, per device, per user, or per workspace? List the key settings that affect how the product behaves between entities.]
+
+## [Resource / Platform] Management
+
+[Platform-specific considerations relevant to the user experience. Device selection (camera, microphone, etc.), system permissions, hot-plug handling, system tray behavior, notification preferences, or other OS integration points. Name the section to match the product domain.]
+
+## Target Platforms
+
+[Supported platforms with version requirements. Be specific: "Windows 10/11" not just "Windows." Note any platform-specific considerations that affect the user experience.]
+
+## Participants
+
+[How many users or devices participate simultaneously? What is the topology (1:1, room, mesh, broadcast)? Is there an upper limit? Note any scaling considerations that affect the v1 design.]
+
+## Business Constraints
+
+**Business model:** [B2C / B2B SaaS / marketplace / self-hosted / white-label / enterprise. How revenue is generated.]
+
+**Tenancy:** [Single-tenant / multi-tenant. Expected tenant count at launch and at scale. Required isolation level (shared DB, schema-per-tenant, DB-per-tenant, infra-per-tenant). "Not applicable" for consumer products.]
+
+**Compliance:** [Regulatory requirements: GDPR, HIPAA, SOC2, PCI-DSS, FedRAMP, or none. Data residency constraints (EU-only, US-only, etc.). "None" if no regulatory requirements.]
+
+**Cost constraints:** [Monthly cloud/infrastructure budget target. Per-tenant cost target if multi-tenant. Licensing constraints (open-source only, commercial OK). "No hard limit" if unconstrained.]
+
+**Vendor & technology constraints:** [Required or excluded vendors/clouds. Required integrations with existing systems. Team technical experience that constrains technology choices. "No constraints" if flexible.]
+
+**Timeline:** [Hard deadlines, market windows, or competitive pressures that affect build-vs-buy decisions. "No hard deadline" if flexible.]
+
+## Key Assumptions
+
+[Assumptions underlying the product concept — things stated or implied during discovery that have not been empirically validated. Each is a testable hypothesis.]
+
+| Assumption | Confidence | What Would Disprove It |
+|-----------|-----------|----------------------|
+| [Market/user/tech/business assumption] | High / Medium / Low | [Observable evidence that would invalidate this] |
+
+## Success Criteria
+
+[Measurable outcomes that define whether the product is succeeding.]
+
+| Metric | Target | Timeframe | Why It Matters |
+|--------|--------|-----------|----------------|
+| [What to measure] | [Specific target value] | [By when] | [Connection to product vision] |
+
+## Future Considerations (Not in v1)
+
+[Explicitly scoped-out items. Each should have a brief note explaining why it was deferred and, if relevant, how v1's design accommodates it later. These are items that were actively discussed and decided against for v1, not a wishlist.]
+```
+
+---
+
+## Section Guidance
+
+| Section | Source | Depth |
+|---------|--------|-------|
+| Vision | User's initial idea + refined through conversation | 2-4 sentences, sharp and specific |
+| Problem Statement | AI-drafted from conversation, user-approved | 3-5 sentences structured as problem/who/workarounds/gap/severity |
+| Target Personas | AI-generated by persona-architect (discovery mode), user-approved | 2-4 archetypes, each with: abstracted mould (ranges, patterns, variation axes, boundaries) + concrete example (full detailed profile). Both layers user-approved. |
+| Product Pillars | Conversation exploration of non-negotiable qualities | 3-5 pillars, each with meaning, rationale, and litmus test |
+| Competitive Landscape | AI-identified by market-researcher (identification mode), user-approved | Tiered list: Primary (top 5 with rationale and confidence tags), Extended (~10), Indirect. Includes research metadata and initial positioning. Source URLs required. Identification only — deep analysis deferred to Gap Analysis skill. |
+| Core Experience | Conversation exploration of interaction modes | 1-3 subsections, each 1-3 paragraphs. UX-focused, not technical. |
+| Trust & Security Model | Conversation exploration of trust/security category | 2-3 subsections covering setup, trust mechanism, and per-entity config |
+| Resource / Platform Management | Conversation exploration of platform category | 1-2 paragraphs on platform integration relevant to UX |
+| Target Platforms | Conversation exploration of platform category | Bullet list with version specifics |
+| Participants | Conversation exploration of participants category | 1 paragraph covering count, topology, and limits |
+| Business Constraints | Conversation exploration of business model, tenancy, compliance, cost, vendor preferences | 1-2 sentences per subsection; concrete numbers for tenant count, budget, and compliance requirements. Skip subsections that don't apply (write "Not applicable" or "None"). |
+| Key Assumptions | AI-derived from conversation, user-validated | 5-8 testable assumptions with confidence levels |
+| Success Criteria | AI-suggested based on product type + business model, user-approved | 3-5 measurable outcomes with targets and timeframes |
+| Future Considerations | Accumulated deferred items from conversation | Bullet list, each with brief rationale for deferral |

package/plugins/arn-spark/skills/arn-spark-ensure-config/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: arn-spark-ensure-config
+description: >-
+  This skill should be used when the user says "ensure config", "check arn spark config",
+  "arn-spark-ensure-config", "verify arn spark setup", "configure spark", "setup arness spark",
+  "spark config", or wants to verify that Arness Spark configuration is present for the
+  current project. This skill is primarily consumed as a reference by entry-point skills
+  (arn-brainstorming, arn-spark-discover, arn-spark-arch-vision) which read the
+  `references/step-0-fast-path.md` reference as Step 0 before proceeding with their workflow.
+version: 1.1.0
+---
+
+# Arness Spark Ensure Config
+
+Verify and establish Arness Spark configuration for the current project. This skill guarantees that a valid user profile and `## Arness` section exist before any Arness Spark workflow proceeds. It runs automatically as Step 0 of all entry-point skills via a hash-based fast-path cache.
+
+**Entry points should NOT read this SKILL.md directly.** They should read `${CLAUDE_PLUGIN_ROOT}/skills/arn-spark-ensure-config/references/step-0-fast-path.md`, which runs the cache-check shell script and only falls through to the full validation when needed. This indirection is what saves ~95% of ensure-config token cost.
+
+When invoked DIRECTLY (rare — typically via `/arn-spark-ensure-config`), this skill bypasses the cache and runs the full validation flow.
+
+## Workflow
+
+Read `${CLAUDE_PLUGIN_ROOT}/skills/arn-spark-ensure-config/references/ensure-config.md` and follow its instructions (Layers 1–2, then Layer 3 cache write).