/arn-code-feature-spec

name: arn-code-feature-spec
description: >-
  This skill should be used when the user says "feature spec", "arness code feature
  spec", "arn-code-feature-spec", "spec this feature", "help me spec", "design this feature", "feature
  design", "write a spec", "create a specification", "I have an idea for a
  feature", "let's flesh out this feature", "decompose feature",
  "spec XL feature", "resume spec", "continue spec", "finish my spec",
  "break down feature", or wants to iteratively develop a feature idea into a
  well-formed specification through guided conversation with architectural
  analysis. For XL features with decomposition hints, creates multiple
  sub-feature specs with full traceability. Produces specification documents
  capturing WHAT to build and WHY, which then feed into plan creation.
version: 1.3.0

Arness Feature Spec

Develop a feature idea into a well-formed specification through iterative conversation, aided by architectural analysis from the `arn-code-architect` agent and, when the feature involves UI, user experience design from the `arn-code-ux-specialist` agent. This is a conversational skill that runs in normal conversation (NOT plan mode). The primary artifact is a **feature specification** written to the project's specs directory that captures requirements, architectural assessment, and decisions from the exploration conversation. The spec then informs plan creation via the `/arn-code-plan` skill.

Step 0: Ensure Configuration

Read `${CLAUDE_PLUGIN_ROOT}/skills/arn-code-ensure-config/references/step-0-fast-path.md` and follow its instructions. This guarantees a user profile exists and `## Arness` is configured with Arness Code fields before proceeding.

Workflow

Step 1: Capture the Feature Idea

1a. Detect Backlog Feature (Greenfield Path)

Before asking the user to describe their feature, check if the trigger includes a greenfield feature backlog entry:

1. Check if the trigger message contains an F-NNN pattern (regex: `F-\d{3}`). Accept natural invocations like:

• `feature spec F-002`
• `spec F-002: Device Pairing`
• `feature spec: Device Pairing` (fuzzy match against feature file names in the features directory)

2. Check if conversation context from `arn-code-pick-issue` includes feature file content (look for markers: `## Description`, `## Journey Steps`, `## Acceptance Criteria` that indicate an F-NNN file was passed inline).

3. **If either condition is met:** extract the feature ID and proceed to **Step 1b**.

4. **If neither condition is met:** fall through to the standard flow below (ask the user to describe the feature).

1b. Load Greenfield Feature Context

Only runs when a backlog entry is detected in Step 1a. Loads the feature file, referenced UC documents, and scope boundary context (related features from the Feature Tracker) to provide rich context for the spec exploration. If any greenfield artifact is missing, falls back gracefully.

> Read `${CLAUDE_PLUGIN_ROOT}/skills/arn-code-feature-spec/references/greenfield-loading.md` for the full loading sequence and error handling.

• If the style-brief has an "Animation and Motion" section, extract it as animation context. This will be passed to both the architect and UX specialist.

1c. Detect XL Decomposition

Only runs after Step 1b successfully loads a greenfield feature.

1. Check if the loaded feature file has:

• `**Complexity:** XL`
• A `## Decomposition Hints` section with at least 2 suggested sub-features

2. **If both conditions are met:** Set a flag: `decomposition_mode = true`. Hold the decomposition hints (suggested sub-features, split rationale, inter-dependencies) for use in Step 5. Inform the user:

"This is an XL feature with decomposition hints. I will create separate sub-feature specs (F-NNN.1, F-NNN.2, ...) instead of a single spec, each scoped to an implementation slice. Let me analyze the implementation approach."

3. **If the feature is XL but has NO or insufficient decomposition hints** (fewer than 2 sub-features): Warn the user:

Ask (using `AskUserQuestion`):

**"Feature F-NNN is estimated as XL but has no decomposition hints (or fewer than 2 sub-features). How would you like to proceed?"**

Options: 1. **Provide decomposition hints now** -- Suggest 2-4 sub-features with journey segment mappings 2. **Proceed with a single spec anyway** -- Not recommended for XL features 3. **Return to the backlog** -- Run `/arn-spark-feature-extract` to add decomposition hints

If **Provide decomposition hints now**: the user provides hints inline, capture them in the same structure as the feature entry template's `## Decomposition Hints` section and set `decomposition_mode = true`. If **Proceed with a single spec anyway**: set `decomposition_mode = false` and continue normally.

4. **If the feature is not XL:** Set `decomposition_mode = false`. Proceed to Step 2.

1d. Standard Flow (No Backlog Entry)

Ask the user to describe their feature idea. Accept anything from a single sentence to a detailed description. Do not require a specific format.

If the user already provided the feature idea in their trigger message (e.g., "feature spec: add WebSocket support for real-time notifications"), use that directly without asking again.

Acknowledge the idea with a brief restatement to confirm understanding.

---

Step 2: Load Codebase Context

Read the project's CLAUDE.md and extract the `## Arness` section to find the Code patterns path and Specs directory path.

Read the stored pattern documentation:

• `<code-patterns-dir>/code-patterns.md`
• `<code-patterns-dir>/testing-patterns.md`
• `<code-patterns-dir>/architecture.md`
• `<code-patterns-dir>/ui-patterns.md` (if it exists)
• `<code-patterns-dir>/security-patterns.md` (if it exists)

**If pattern documentation files are missing** (no `code-patterns.md`, `testing-patterns.md`, or `architecture.md` in the Code patterns directory):

Inform the user: "This is the