/elicit

name: elicit
description: "Run a structured discovery session to build an Allium specification through conversation. Use when the user wants to create a new spec from scratch, elicit or gather requirements, capture domain behaviour, specify a feature or system, define what a system should do, or is describing functionality and needs help shaping it into a specification."

Elicitation

This skill guides you through building Allium specifications by conversation. The goal is to surface ambiguities and produce a specification that captures what the software does without prescribing implementation.

Scoping the specification

Before diving into details, establish what you are specifying. Not everything needs to be in one spec.

Questions to ask first

**"What's the boundary of this specification?"** A complete system? A single feature area? One service in a larger system? Be explicit about what is in and out of scope.

**"Are there areas we should deliberately exclude?"** Third-party integrations might be library specs. Legacy features might not be worth specifying. Some features might belong in separate specs.

**"Is this a new system or does code already exist?"** If code exists, you are doing distillation with elicitation. Existing code constrains what is realistic to specify.

Documenting scope decisions

Capture scope at the start of every spec:

-- allium: 3
-- interview-scheduling.allium

-- Scope: Interview scheduling for the hiring pipeline
-- Includes: Candidacy, Interview, Slot management, Invitations, Feedback
-- Excludes:
--   - Authentication (use oauth library spec)
--   - Payments (not applicable)
--   - Reporting dashboards (separate spec)
-- Dependencies: User entity defined in core.allium

The version marker (`-- allium: N`) must be the first line of every `.allium` file. Use the current language version number.

Finding the right level of abstraction

Too concrete and you are specifying implementation. Too abstract and you are not saying anything useful.

The "Why" test

For every detail, ask: "Why does the stakeholder care about this?"

| Detail | Why? | Include? | |--------|------|----------| | "Users log in with Google OAuth" | They need to authenticate | Maybe not, "Users authenticate" might be sufficient | | "We support Google and Microsoft OAuth" | Users choose their provider | Yes, the choice is domain-level | | "Sessions expire after 24 hours" | Security/UX decision | Yes, affects user experience | | "Sessions are stored in Redis" | Performance | No, implementation detail | | "Passwords must be 12+ characters" | Security policy | Yes, affects users | | "Passwords are hashed with bcrypt" | Security implementation | No, how not what |

The "Could it be different?" test

Ask: "Could this be implemented differently while still being the same system?"

• If yes, it is probably an implementation detail. Abstract it away.
• If no, it is probably domain-level. Include it.

Examples:

• "Notifications sent via Slack". Could be email, SMS, etc. Abstract to `Notification.created(channel: ...)`.
• "Interviewers must confirm within 3 hours". This specific deadline matters at the domain level. Include the duration.
• "We use PostgreSQL". Could be any database. Do not include.
• "Data is retained for 7 years for compliance". Regulatory requirement. Include.

The "Template vs Instance" test

Is this a category of thing, or a specific instance?

| Instance (implementation) | Template (domain-level) | |---------------------------|-------------------------| | Google OAuth | Authentication provider | | Slack | Notification channel | | 15 minutes | Link expiry duration (configurable) | | Greenhouse ATS | External candidate source |

Sometimes the instance IS the domain concern. "We specifically integrate with Salesforce" might be a competitive feature. "We support exactly these three OAuth providers" might be design scope.

When in doubt, ask the stakeholder: "If we changed this, would it be a different system or just a different implementation?"

Levels of abstraction

Too abstract:          "Users can do things"
                              |
Product level:         "Candidates can accept or decline interview invitations"
                              |
Too concrete:          "Candidates click a button that POST to /api/invitations/:id/accept"

**Signs you are too abstract.** The spec could describe almost any system. No testable assertions. Product owner says "but that doesn't capture..."

**Signs you are too concrete.** You are mentioning technologies, frameworks or APIs. You are describing UI elements (buttons, pages, forms). The implementation team says "why are you dictating how we build this?"

Configuration vs hardcoding

When you encounter a specific value (3 hours, 7 days, etc.), ask:

1. **Is this value a design decision?** Include it. 2. **Might it vary per deployment or customer?** Make it configurable. 3. **Is it arbitrary?** Consider whether to include it at all.

-- Hardcoded design decision
rule InvitationExpires {
    when: invitation: Invitation.created_at + 7.days <= now
    ...
}

-- Configurable
config {
    invitation_expiry: Duration = 7.days
}

rule InvitationExpires {
    when: invitation: Invitation.created_at + config.invitation_expiry <= now
    ...
}

Black boxes

Some logic is important but belongs at a different level:

-- Black box: we know it exists and what it considers, but not how
ensures: Suggestion.created(
    interviewers: InterviewerMatching.suggest(
        considering: {
            role.required_skills,
            Interviewer.skills,
            Interviewer.availability,
            Interviewer.recent_load
        }
    )
)

The spec says there is a matching algorithm, that it considers these inputs and that it produces interviewer suggestions. The spec does not say how matching works, what weights are used or the specific algorithm.

This is the right level w