mx-feature-spec

name	mx-feature-spec
description	Convert a plain-English Mendix feature description into a structured spec markdown file referencing inventory items by exact name. Output is a spec, not a model change. Auto-invoke when the user describes a Mendix feature in natural language and is about to start designing it. Also invocable as /mx-feature-spec <description>.

mx-feature-spec

The "before-the-design" primitive. Turns "I want a thing where users can pick a customer and see their last 5 orders" into a structured, inventory-grounded spec that the design phase can consume without re-deriving the requirements.

North star

A spec written against the inventory is half the design.

When to invoke

Auto-invoke when:

• Neo describes a Mendix feature in natural language.
• The /mx-discover inventory has been run (or run it as a prerequisite if not).
• About to enter design / implementation work.

Do not invoke for:

• Bug fixes (no new feature surface).
• Refactors that don't change behavior (use /mx-impact instead).

What it does

1. Verify inventory. If /mx-discover has not been run for this feature's surface area, run it first. The spec must reference inventory items by exact name -- no hand-waving.

2. Interview-by-default. Ask Neo at most 3 clarifying questions, all at once (not robotic one-by-one). Cover the most-uncertain dimensions:

   • Who triggers it? (User role, schedule, event, microflow caller.)
   • What's the data scope? (One record, list, paged list, search?)
   • What's the success criterion? ("User sees X" / "Record Y is updated" / "External system Z is notified.")

3. Produce the spec markdown. Write it to <project>/specs/<feature-slug>.md (create specs/ if missing). Spec template:

# Feature spec: <name>

**Status:** draft (not yet designed)
**Author:** <Neo + Claude>
**Date:** <YYYY-MM-DD>
**Inventory snapshot:** <path or commit hash>

## Summary
<1-2 sentence purpose>

## Triggers
- <who/what initiates>: <role / schedule / event>

## Data scope
- **Primary entities** (from inventory): <Module.Entity1>, <Module.Entity2>
- **Read or write?** read-only / read-and-write / write-only
- **Volume:** <one record / paged list / unbounded>

## Behavior
1. <step in order>
2. ...

## Success criterion
- <observable outcome>

## Constraints
- **Security:** <which roles>
- **Performance:** <SLA expectations>
- **Marketplace overlap:** <module that already does this, if any -- recommend reuse>
- **Existing convention to follow:** <pattern from /mx-discover>

## Out of scope
- <explicit non-goals>

## Open questions
- <thing that would need a design call to resolve>

## Acceptance tests (proposed)
- GIVEN <state> WHEN <action> THEN <observable outcome>
- ...

## References
- Inventory: <path>
- Related microflows: <Module.Microflow> ...
- Related pages: <Module.Page> ...

4. Stop. The spec is the deliverable. Design comes next, in a separate skill / session. Do NOT propose entity changes, microflow names, or page layouts in the spec -- those are design decisions.

Hard rules

• No design language in the spec. "User clicks a button" is allowed; "we'll add a Button widget bound to ACT_ConfirmOrder microflow" is not -- that's design.
• Every named entity / microflow / page MUST come from the inventory. If it doesn't exist yet, it's an open question, not a fact.
• Acceptance tests use GIVEN / WHEN / THEN. Forces clarity about state and outcome.
• Refuse to skip the inventory step. The spec's value is its grounding.
• Cap interview questions at 3, presented together. Robotic one-by-one interviews are a banned anti-pattern.

Cross-reference

• Inventory: ~/.claude/skills/mx-discover/SKILL.md.
• Design review (post-design): ~/.claude/skills/mx-design-review/SKILL.md.
• Plan-first: ~/.claude/skills/plan-first/SKILL.md (general; this skill is the Mendix-specific spec primitive).