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

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?" Interaction modes This skill runs in two modes. Every instruction below that asks, prompts or validates with the user follows the mode: Interactive — running inline in a conversation. Ask the user directly and wait for the answer. Non interactive — running as the distill subagent (for example inside the Allium loop), where no user is reachable. Scope the distillation from the goal you were given, and do not guess at judgement calls: record each unconfirmed judgement — intended vs accidental behaviour, actor identity, candidate processes, scope exclusions — as an open question declaration in the distilled spec, and list the parked questions in your final output. 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: 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: 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: 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: Almost always implementation. The spec should say: 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: 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: Product level if: "Greenhouse integration" is a selling point Users configure their Greenhouse connection Greenhouse specific features are exposed (like syncing feedback back) Spec: 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 Distillation reads a lot of code but produces a small spec. The expensive mistake is letting all that source pile up in one context window where it is re read on every turn. Keep the working set lean: orchestrate the read heavy steps as subagents and keep only their distilled output. The orchestration model For anything beyond a handful of files, do not read the whole codebase yourself. Instead: 1. Map the codebase into bounded contexts — a light scan (Step 1), not a deep read. 2. Fan out. Spawn one subagent per bounded context. Each reads only its slice and returns distilled fragments — draft entities (states + transition edges), draft rules (trigger / requires / ensures), external boundaries, actors and config — each with file:line evidence. Subagents return spec fragments and evidence, never raw source. Give each subagent its target paths, the shared entity vocabulary from the map (so contexts agree on names), and the extraction guidance in Steps 2–5; ask for a compact fragment, not prose commentary. 3. Assemble. You, the orchestrator, hold only the map and the returned fragments — not the source. Merge fragments into one spec: dedupe cross cutting entities ( Email , Notification , AuditLog ), reconcile terminology (one name per concept, see the challenges reference), and resolve cross context references. 4. Abstract and validate the assembled spec (Steps 6–7). Why this matters: raw source never accumulates in your context, so it is not re processed turn after turn; each subagent's slice is discarded once its fragment returns. You still read every relevant line — just not all at once, and not repeatedly. The result is the same spec at a fraction of the tokens. For a genuinely small codebase (a handful of files) the fan out overhead is not worth it — read it directly and apply Steps 1–7 inline. Step 1: Map the territory Scan — do not deeply read — to carve the codebase into bounded contexts and a shared vocabulary, and to plan the fan out. Identify: 1. Entry points. API routes, CLI commands, message handlers, scheduled jobs. 2. Domain models. Usually in models/ , entities/ , domain/ . 3. Business logic. Services, use cases, handlers. 4. External integrations. What third parties does it talk to? 5. Bounded contexts. Group the above into cohesive slices (by module, package or feature area) — these become the fan out units. Note the entities that appear in more than one slice; they are the shared vocabulary every subagent must use consistently. Create a rough map: Steps 2–5 are the extraction guidance each fan out subagent applies to its slice (and that you apply directly for a small codebase). Hand them to each subagent along with its target paths and the shared vocabulary; collect the fragments and assemble per the orchestration model. Step 2: Extract entity states Look at enum fields and status columns: Becomes: Look for enum definitions, status or state columns, constants like STATUS PENDING = 'pending' , and state machine libraries (e.g. transitions , django fsm ). Step 2.5: Identify candidate processes After extracting entities and their states, scan for state machines that suggest end to end processes. Trace where each status value gets set across the codebase (where does status = 'interviewing' happen?). Present candidate processes to the user for validation: "I see an entity with states applied → screening → interviewing → deciding → hired/rejected . Is this a process the system is meant to support?" Also trace cross entity data flow. If a rule on entity A requires a field from entity B, follow the chain: where does entity B's field get set, and what triggers that? Present the chain: "The hirin