mostalive/rpg-combat-pi-01
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

skills I believed were committed

Browse Source
This commit is contained in:
mostalive
2026-06-12 22:08:36 +01:00
parent 8450f90e89
commit e05572bcec
9 changed files with 183 additions and 116 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.pi/skills/distill/SKILL.md
+86 -52
View File
@@ -1,6 +1,6 @@
---
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."
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.'
disable-model-invocation: true
license: MIT
metadata:
@@ -12,7 +12,7 @@ metadata:
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?"
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
@@ -68,14 +68,14 @@ Distillation and elicitation share the same fundamental challenge: choosing what
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 |
| 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.
@@ -86,23 +86,23 @@ 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 |
| 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 |
| ------------------------------- | ----------------------------- |
| 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.
@@ -168,6 +168,7 @@ rule SendInvitation {
```
What we dropped:
- `candidate_id: int` became just `candidacy`
- `db.session.query(...)` became relationship traversal
- `secrets.token_urlsafe(32)` removed entirely (token is implementation)
@@ -179,26 +180,26 @@ What we dropped:
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 |
| 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` |
| 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
@@ -207,6 +208,7 @@ The hardest judgement call: when is a concrete detail part of the domain vs just
### Google OAuth example
You find this code:
```python
OAUTH_PROVIDERS = {
'google': GoogleOAuthProvider(client_id=..., client_secret=...),
@@ -219,12 +221,14 @@ def authenticate(provider: str, code: str) -> User:
**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
@@ -235,6 +239,7 @@ def authenticate(provider: str, code: str) -> User:
### Database choice example
You find PostgreSQL-specific code:
```python
from sqlalchemy.dialects.postgresql import JSONB, ARRAY
@@ -244,6 +249,7 @@ class Candidate(Base):
```
**Almost always implementation.** The spec should say:
```
entity Candidate {
skills: Set<String>
@@ -256,6 +262,7 @@ The specific database is rarely domain-level. Exception: if the system explicitl
### Third-party integration example
You find Greenhouse ATS integration:
```python
class GreenhouseSync:
def import_candidate(self, greenhouse_id: str) -> Candidate:
@@ -271,11 +278,13 @@ class GreenhouseSync:
**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
@@ -285,11 +294,13 @@ external entity Candidate {
```
**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
@@ -329,6 +340,7 @@ Before extracting any specification, understand the codebase structure:
4. **Note external integrations.** What third parties does it talk to?
Create a rough map:
```
Entry points:
- API: /api/candidates/*, /api/interviews/*, /api/invitations/*
@@ -355,6 +367,7 @@ class Invitation(Base):
```
Becomes:
```
entity Invitation {
status: pending | accepted | declined | expired
@@ -400,6 +413,7 @@ def accept_invitation(invitation_id: int, slot_id: int):
```
Extract:
```
rule CandidateAcceptsInvitation {
when: CandidateAccepts(invitation, slot)
@@ -425,15 +439,15 @@ rule CandidateAcceptsInvitation {
**Key extraction patterns:**
| Code pattern | Spec pattern |
|--------------|--------------|
| `if x.status != 'pending': raise` | `requires: x.status = pending` |
| `if x.expires_at < now: raise` | `requires: x.expires_at > now` |
| `if item not in collection: raise` | `requires: item in collection` |
| `x.status = 'accepted'` | `ensures: x.status = accepted` |
| `Model.create(...)` | `ensures: Model.created(...)` |
| `send_email(...)` | `ensures: Email.created(...)` |
| `notify(...)` | `ensures: Notification.created(...)` |
| Code pattern | Spec pattern |
| ---------------------------------- | ------------------------------------ |
| `if x.status != 'pending': raise` | `requires: x.status = pending` |
| `if x.expires_at < now: raise` | `requires: x.expires_at > now` |
| `if item not in collection: raise` | `requires: item in collection` |
| `x.status = 'accepted'` | `ensures: x.status = accepted` |
| `Model.create(...)` | `ensures: Model.created(...)` |
| `send_email(...)` | `ensures: Email.created(...)` |
| `notify(...)` | `ensures: Notification.created(...)` |
Assertions, checks and validations found in code (e.g. `assert balance >= 0`, class-level validators) may map to expression-bearing invariants rather than rule preconditions. Consider whether they describe a system-wide property or a rule-specific guard.
@@ -471,6 +485,7 @@ def send_reminders():
```
Extract:
```
rule InvitationExpires {
when: invitation: Invitation.expires_at <= now
@@ -512,6 +527,7 @@ def import_from_greenhouse(webhook_data):
```
Suggests:
```
external entity Candidate {
name: String
@@ -526,6 +542,7 @@ When repeated interface patterns appear across service boundaries (e.g. the same
Now make a pass through your extracted spec and remove implementation details.
**Before (too concrete):**
```
entity Invitation {
candidate_id: Integer
@@ -537,6 +554,7 @@ entity Invitation {
```
**After (domain-level):**
```
entity Invitation {
candidacy: Candidacy
@@ -549,6 +567,7 @@ entity Invitation {
```
Changes:
- `candidate_id: Integer` became `candidacy: Candidacy` (relationship, not FK)
- `token: String(32)` removed (implementation)
- `DateTime` became `Timestamp` (domain type)
@@ -565,6 +584,7 @@ The extracted spec is a hypothesis. Validate it:
3. **Look for gaps.** Code often has bugs or missing features; the spec might reveal them.
Common findings:
- "Oh, that retry logic was a hack, we should remove it"
- "Actually we wanted X but never built it"
- "These two code paths should be the same but aren't"
@@ -578,6 +598,7 @@ The same principle applies in elicitation. When a stakeholder describes "we use
### Signals in the code
**Third-party integration modules:**
```python
# Finding code like this suggests a library spec
class StripeWebhookHandler:
@@ -594,6 +615,7 @@ class GoogleOAuthProvider:
```
**Generic patterns with specific providers:**
- OAuth flows (Google, Microsoft, GitHub)
- Payment processing (Stripe, PayPal)
- Email delivery (SendGrid, Postmark, SES)
@@ -602,6 +624,7 @@ class GoogleOAuthProvider:
- File storage (S3, GCS)
**Configuration-driven integrations:**
```python
# Heavy configuration suggests the integration itself is separable
OAUTH_CONFIG = {
@@ -627,6 +650,7 @@ OAUTH_CONFIG = {
**Option 1: Reference an existing library spec**
If a standard library spec exists for this integration:
```
use "github.com/allium-specs/stripe-billing/abc123" as stripe
@@ -640,6 +664,7 @@ rule ActivateSubscription {
**Option 2: Create a separate library spec**
If no standard spec exists but the integration is generic:
```
-- greenhouse-ats.allium (library spec)
-- Specifies: Greenhouse webhook events, candidate sync, etc.
@@ -656,6 +681,7 @@ rule ImportCandidate {
**Option 3: Abstract and move on**
If the integration is minor, just abstract it:
```
-- Don't specify Slack details, just:
ensures: Notification.created(
@@ -683,6 +709,7 @@ rule ProcessStripeWebhook {
```
Instead:
```
-- Application responds to payment events (integration handled elsewhere)
rule PaymentReceived {
@@ -693,14 +720,14 @@ rule PaymentReceived {
### Common library spec extractions
| Code pattern found | Library spec candidate |
|-------------------|----------------------|
| OAuth token exchange, refresh, session management | `oauth2.allium` |
| Stripe webhook handling, subscription lifecycle | `stripe-billing.allium` |
| Email sending with templates, bounce handling | `email-delivery.allium` |
| Calendar event sync, availability checking | `calendar-integration.allium` |
| ATS candidate import, status sync | `greenhouse-ats.allium`, `lever-ats.allium` |
| File upload, virus scanning, thumbnail generation | `file-storage.allium` |
| Code pattern found | Library spec candidate |
| ------------------------------------------------- | ------------------------------------------- |
| OAuth token exchange, refresh, session management | `oauth2.allium` |
| Stripe webhook handling, subscription lifecycle | `stripe-billing.allium` |
| Email sending with templates, bounce handling | `email-delivery.allium` |
| Calendar event sync, availability checking | `calendar-integration.allium` |
| ATS candidate import, status sync | `greenhouse-ats.allium`, `lever-ats.allium` |
| File upload, virus scanning, thumbnail generation | `file-storage.allium` |
See patterns.md Pattern 8 for detailed examples of integrating library specs.
@@ -719,11 +746,13 @@ When you find two terms for the same concept (across specs, within a spec, or be
This is not a resolution. When different parts of a codebase are built against different specs, both terms end up in the implementation: duplicate models, redundant join tables, foreign keys pointing both ways.
**What to do:**
- Choose one term. Cross-reference related specs before deciding.
- Update all references. Do not leave the old term in comments or "see also" notes.
- Note the rename in a changelog, not in the spec itself.
**Warning signs in code:**
- Two models representing the same concept (`Order` and `Purchase`)
- Join tables for both (`order_items`, `purchase_items`)
- Comments like "equivalent to X" or "same as Y"
@@ -745,11 +774,13 @@ class FeedbackRequest:
```
The implicit states are:
- `pending`: requested_at set, feedback_id null, reminded_at null
- `reminded`: reminded_at set, feedback_id null
- `submitted`: feedback_id set
Extract to explicit:
```
entity FeedbackRequest {
interview: Interview
@@ -784,6 +815,7 @@ def process_acceptance(invitation, slot):
```
Consolidate into one rule:
```
rule CandidateAccepts {
when: CandidateAccepts(invitation, slot)
@@ -800,6 +832,7 @@ rule CandidateAccepts {
Codebases accumulate features that were built but never used, workarounds for bugs that are now fixed, and code paths that are never executed.
Do not include these in the spec. If you are unsure:
1. Check if the code is actually reachable
2. Ask developers if it is intentional
3. Check git history for context
@@ -817,6 +850,7 @@ def send_notification(user, message):
```
The spec should capture the intended behaviour, not the bug:
```
ensures: Notification.created(to: user, channel: slack)
```