distill

name	distill
description	Extract an Allium specification from an existing codebase. Use when the user has existing code and wants to distil behaviour into a spec, reverse engineer a specification from implementation, generate a spec from code, turn implementation into a behavioural specification, or document what a codebase does in Allium terms.
model	sonnet

Distillation guide

This guide covers extracting Allium specifications from existing codebases. The core challenge is the same as forward elicitation: finding the right level of abstraction. In elicitation you filter out implementation ideas as they arise. In distillation you filter out implementation details that already exist. Both require the same judgement about what matters at the domain level.

Code tells you how something works. A specification captures what it does and why it matters. The skill is asking "why does the stakeholder care about this?" and "could this be different while still being the same system?"

Scoping the distillation effort

Before diving into code, establish what you are trying to specify. Not every line of code deserves a place in the spec.

Questions to ask first

1. "What subset of this codebase are we specifying?" Mono repos often contain multiple distinct systems. You may only need a spec for one service or domain. Clarify boundaries explicitly before starting.

2. "Is there code we should deliberately exclude?"

   • Legacy code: features kept for backwards compatibility but not part of the core system
   • Incidental code: supporting infrastructure that is not domain-level (logging, metrics, deployment)
   • Deprecated paths: code scheduled for removal
   • Experimental features: behind feature flags, not yet design decisions

3. "Who owns this spec?" Different teams may own different parts of a mono repo. Each team's spec should focus on their domain.

The "Would we rebuild this?" test

For any code path you encounter, ask: "If we rebuilt this system from scratch, would this be in the requirements?"

• Yes: include in spec
• No, it is legacy: exclude
• No, it is infrastructure: exclude
• No, it is a workaround: exclude (but note the underlying need it addresses)

Documenting scope decisions

At the top of a distilled spec, document what is included and excluded:

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

-- Scope: Interview scheduling flow only
-- Includes: Candidacy, Interview, InterviewSlot, Invitation, Feedback
-- Excludes:
--   - User authentication (use auth library spec)
--   - Analytics/reporting (separate spec)
--   - Legacy V1 API (deprecated, not specified)
--   - Greenhouse sync (use greenhouse library spec)

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

Distillation and elicitation share the same fundamental challenge: choosing what to include. The tests below work in both directions, whether you are hearing a stakeholder describe a feature or reading code that implements it.

The "Why" test

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

Code detail	Why?	Include?
Invitation expires in 7 days	Affects candidate experience	Yes
Token is 32 bytes URL-safe	Security implementation	No
Sessions stored in Redis	Performance choice	No
Uses PostgreSQL JSONB	Database implementation	No
Slot status changes to 'proposed'	Affects what candidate sees	Yes
Email sent when invitation accepted	Communication requirement	Yes

If you cannot articulate why a stakeholder would care, it is probably implementation.

The "Could it be different?" test

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

• If yes: probably implementation detail, abstract it away
• If no: probably domain-level, include it

Detail	Could be different?	Include?
secrets.token_urlsafe(32)	Yes, any secure token generation	No
7-day invitation expiry	No, this is the design decision	Yes
PostgreSQL database	Yes, any database	No
"Pending, Confirmed, Completed" states	No, this is the workflow	Yes

The "Template vs Instance" test

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

Instance (often implementation)	Template (often domain-level)
Google OAuth	Authentication provider
Slack webhook	Notification channel
SendGrid API	Email delivery
timedelta(hours=3)	Confirmation deadline

Sometimes the instance IS the domain concern. See "The concrete detail problem" below.

The distillation mindset

Code is over-specified

Every line of code makes decisions that might not matter at the domain level:

# Code tells you:
def send_invitation(candidate_id: int, slot_ids: List[int]) -> Invitation:
    candidate = db.session.query(Candidate).get(candidate_id)
    slots = db.session.query(InterviewSlot).filter(
        InterviewSlot.id.in_(slot_ids),
        InterviewSlot.status == 'confirmed'
    ).all()

    invitation = Invitation(
        candidate_id=candidate_id,
        token=secrets.token_urlsafe(32),
        expires_at=datetime.utcnow() + timedelta(days=7),
        status='pending'
    )
    db.session.add(invitation)

    for slot in slots:
        slot.status = 'proposed'
        invitation.slots.append(slot)

    db.session.commit()

    send_email(
        to=candidate.email,
        template='interview_invitation',
        context={'invitation': invitation, 'slots': slots}
    )

    return invitation

-- Specification should say:
rule SendInvitation {
    when: SendInvitation(candidacy, slots)

    requires: slots.all(s => s.status = confirmed)

    ensures:
        for s in slots:
            s.status = proposed
    ensures: Invitation.created(
        candidacy: candidacy,
        slots: slots,
        expires_at: now + 7.days,
        status: pending
    )
    ensures: Email.created(
        to: candidacy.candidate.email,
        template: interview_invitation
    )
}

What we dropped:

• candidate_id: int became just candidacy
• db.session.query(...) became relationship traversal
• secrets.token_urlsafe(32) removed entirely (token is implementation)
• datetime.utcnow() + timedelta(...) became now + 7.days
• db.session.add/commit implied by created
• invitation.slots.append(slot) implied by relationship

Ask "Would a product owner care?"

For every detail in the code, ask:

Code detail	Product owner cares?	Include?
Invitation expires in 7 days	Yes, affects candidate experience	Yes
Token is 32 bytes URL-safe	No, security implementation	No
Uses SQLAlchemy ORM	No, persistence mechanism	No
Email template name	Maybe, if templates are design decisions	Maybe
Slot status changes to 'proposed'	Yes, affects what candidate sees	Yes
Database transaction commits	No, implementation detail	No

Distinguish means from ends

Means: how the code achieves something. Ends: what outcome the system needs.

Means (code)	Ends (spec)
requests.post('https://slack.com/api/...')	Notification.created(channel: slack)
candidate.oauth_token = google.exchange(code)	Candidate authenticated
redis.setex(f'session:{id}', 86400, data)	Session.created(expires: 24.hours)
for slot in slots: slot.status = 'cancelled'	for s in slots: s.status = cancelled

The concrete detail problem

The hardest judgement call: when is a concrete detail part of the domain vs just implementation?

Google OAuth example

You find this code:

OAUTH_PROVIDERS = {
    'google': GoogleOAuthProvider(client_id=..., client_secret=...),
}

def authenticate(provider: str, code: str) -> User:
    return OAUTH_PROVIDERS[provider].authenticate(code)

Question: Is "Google OAuth" domain-level or implementation?

It is implementation if:

• Google is just the auth mechanism chosen
• It could be replaced with any OAuth provider
• Users do not see or care which provider
• The code is written generically (provider is a parameter)

It is domain-level if:

• Users explicitly choose Google (vs Microsoft, etc.)
• "Sign in with Google" is a feature
• Google-specific scopes or permissions are used
• Multiple providers are supported as a feature

How to tell: Look at the UI and user flows. If users see "Sign in with Google" as a choice, it is domain-level. If they just see "Sign in" and Google happens to be behind it, it is implementation.

Database choice example

You find PostgreSQL-specific code:

from sqlalchemy.dialects.postgresql import JSONB, ARRAY

class Candidate(Base):
    skills = Column(ARRAY(String))
    metadata = Column(JSONB)

Almost always implementation. The spec should say:

entity Candidate {
    skills: Set<String>
    metadata: String?              -- or model specific fields
}

The specific database is rarely domain-level. Exception: if the system explicitly promises PostgreSQL compatibility or specific PostgreSQL features to users.

Third-party integration example

You find Greenhouse ATS integration:

class GreenhouseSync:
    def import_candidate(self, greenhouse_id: str) -> Candidate:
        data = self.client.get_candidate(greenhouse_id)
        return Candidate(
            name=data['name'],
            email=data['email'],
            greenhouse_id=greenhouse_id,
            source='greenhouse'
        )

Could be either:

Implementation if:

• Greenhouse is just where candidates happen to come from
• Could be swapped for Lever, Workable, etc.
• The integration is an implementation detail of "candidates are imported"

Spec:

external entity Candidate {
    name: String
    email: String
    source: CandidateSource
}

Product-level if:

• "Greenhouse integration" is a selling point
• Users configure their Greenhouse connection
• Greenhouse-specific features are exposed (like syncing feedback back)

Spec:

external entity Candidate {
    name: String
    email: String
    greenhouse_id: String?  -- explicitly modeled
}

rule SyncFromGreenhouse {
    when: GreenhouseWebhookReceived(candidate_data)
    ensures: Candidate.created(
        ...
        greenhouse_id: candidate_data.id
    )
}

The "Multiple implementations" heuristic

Look for variation in the codebase:

• If there is only one OAuth provider, probably implementation
• If there are multiple OAuth providers, probably domain-level
• If there is only one notification channel, probably implementation
• If there are Slack AND email AND SMS, probably domain-level

The presence of multiple implementations suggests the variation itself is a domain concern.

Distillation process

Step 1: Map the territory

Before extracting any specification, understand the codebase structure:

1. Identify entry points. API routes, CLI commands, message handlers, scheduled jobs.
2. Find the domain models. Usually in models/, entities/, domain/.
3. Locate business logic. Services, use cases, handlers.
4. Note external integrations. What third parties does it talk to?

Create a rough map:

Entry points:
  - API: /api/candidates/*, /api/interviews/*, /api/invitations/*
  - Webhooks: /webhooks/greenhouse, /webhooks/calendar
  - Jobs: send_reminders, expire_invitations, sync_calendars

Models:
  - Candidate, Interview, InterviewSlot, Invitation, Feedback

Services:
  - SchedulingService, NotificationService, CalendarService

Integrations:
  - Google Calendar, Slack, Greenhouse, SendGrid

Step 2: Extract entity states

Look at enum fields and status columns:

class Invitation(Base):
    status = Column(Enum('pending', 'accepted', 'declined', 'expired'))

Becomes:

entity Invitation {
    status: pending | accepted | declined | expired
}

Look for enum definitions, status or state columns, constants like STATUS_PENDING = 'pending', and state machine libraries (e.g. transitions, django-fsm).

Step 3: Extract transitions

Find where status changes happen:

def accept_invitation(invitation_id: int, slot_id: int):
    invitation = get_invitation(invitation_id)

    if invitation.status != 'pending':
        raise InvalidStateError()
    if invitation.expires_at < datetime.utcnow():
        raise ExpiredError()

    slot = get_slot(slot_id)
    if slot not in invitation.slots:
        raise InvalidSlotError()

    invitation.status = 'accepted'
    slot.status = 'booked'

    # Release other slots
    for other_slot in invitation.slots:
        if other_slot.id != slot_id:
            other_slot.status = 'available'

    # Create the interview
    interview = Interview(
        candidate_id=invitation.candidate_id,
        slot_id=slot_id,
        status='scheduled'
    )

    notify_interviewers(interview)
    send_confirmation_email(invitation.candidate, interview)

Extract:

rule CandidateAcceptsInvitation {
    when: CandidateAccepts(invitation, slot)

    requires: invitation.status = pending
    requires: invitation.expires_at > now
    requires: slot in invitation.slots

    ensures: invitation.status = accepted
    ensures: slot.status = booked
    ensures:
        for s in invitation.slots:
            if s != slot: s.status = available
    ensures: Interview.created(
        candidacy: invitation.candidacy,
        slot: slot,
        status: scheduled
    )
    ensures: Notification.created(to: slot.interviewers, ...)
    ensures: Email.created(to: invitation.candidate.email, ...)
}

Key extraction patterns:

| Code pattern | Spec pattern |