Kartik-Doye/Ravengard-AI-Recruiter / .agents/skills/distill
distill
VerifiedTurns a vague software request into a compact implementation brief with actors, triggers, preconditions, behavior, failures, permissions, data effects, edge cases, and observable acceptance conditions. Use before planning when product intent or scope is ambiguous.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 10.0 KB |
| references/brief-template.md | markdown | 3.4 KB |
| references/research.md | markdown | 832 B |
SKILL.md
View on GitHub---
name: distill
description: Turns a vague software request into a compact implementation brief with actors, triggers, preconditions, behavior, failures, permissions, data effects, edge cases, and observable acceptance conditions. Use before planning when product intent or scope is ambiguous.
---
# distill: weak request in, sharp brief out
A great brief removes ambiguity. It does not add volume. Your output should
be executable by a weaker model without access to this conversation: every
fact it needs is on the page, and nothing on the page is filler.
## When NOT to use
- The idea hasn't survived critique yet → `hotseat` first.
- The request is already precise (goal, scope, and definition of done are
unambiguous) → skip straight to planning.
- The task is a small mechanical fix ("rename this variable") → just do it.
## Prerequisites
The triggering request. A quick look at the repository for context (what
exists, what conventions apply): lighter than a `spelunk` pass; read only
what the request names or obviously touches.
## Evidence, authority, and assumption model
Distill clarifies intent; it does not silently become a product owner,
architect, security approver, or implementation agent. Separate all brief
content into these classes:
| Class | Meaning | Treatment |
| --- | --- | --- |
| Confirmed fact | user statement or observed repository evidence | cite compactly |
| Constraint | explicit requirement, policy, compatibility, budget, or authority limit | preserve verbatim when material |
| Assumption | reasonable choice that does not need user input yet | number it and make it falsifiable |
| Open decision | plausible answers materially change outcome | ask or route to hotseat |
| Suggestion | non-binding improvement beyond the request | isolate; never smuggle into scope |
Never infer permission to delete data, break a public contract, change pricing,
send external communication, access production data, spend money, or deploy.
Those are explicit approval boundaries in the brief when relevant.
## Brief decision framework
Distill only the ambiguity that matters to a downstream implementer. For each
candidate detail, ask: does an alternative change user outcome, scope, data,
permission, compatibility, risk, verification, cost, or release behavior? If
not, omit it or make a narrow assumption. If yes, decide it, ask it, or record
it as a deliberately unresolved decision with a safe discovery step.
Write observable requirements as behavior under conditions:
| Situation | Requirement form |
| --- | --- |
| Ubiquitous behavior | The system shall <response> |
| Triggered behavior | When <trigger>, the system shall <response> |
| Conditional behavior | While <condition>, the system shall <response> |
| Failure/exception | If <failure>, the system shall <safe response> |
| Prohibition/invariant | The system shall not <forbidden outcome> |
The form is a tool, not a ritual. Pair each material requirement with an
oracle: visible result, returned contract, persisted state, log/audit event, or
testable absence of a forbidden side effect. "Intuitive", "fast", "secure",
and "production-ready" are labels until their observable condition is named.
## Scale the brief to the request
| Request type | Brief shape |
| --- | --- |
| **tiny task** (button rename, copy fix) | goal + acceptance criterion + where: 5–10 lines, no template ceremony |
| **feature** | full template below |
| **large feature / migration** | full template + NFRs, rollout constraints, backward-compatibility and data-migration notes |
| **bug/change request** | reproduction facts + expected behavior + scope guard (what NOT to fix along the way) |
| **greenfield product** | full template + target user + success metric; defer tech choices to `masterplan` unless the user named them |
A brief for a button rename that mentions "non-goals" and "rollout" is
enterprise cosplay: match depth to blast radius.
## Workflow
### 1. Extract the goal
Restate the request as one sentence: *what* will be true after the work
that isn't true now, *for whom*. If you cannot write this sentence, that's
a clarifying question, not a brief.
### 2. Ground in the repo first (lightly)
Before drafting a single question, confirm the surfaces the brief touches
actually exist: the page/module named, the data involved, the commands
available. Briefs referencing nonexistent files are how hallucinated work
starts. Most "ambiguities" die here: what remains is genuinely missing.
### 3. Ambiguity detection (max 5 questions)
Actively scan the request for linguistic, semantic, and functional
ambiguities. List what's genuinely blocking:
- Undefined boundaries ("make it fast" → what is the target metric?)
- Contradictory constraints
- Missing definitions of "good" or failure states
For each candidate question, apply the materiality test: name the two most
plausible answers and what each would change about implementation, security,
data handling, or UX. If nothing material changes, it is not a question,
it becomes an explicit numbered assumption in the brief.
Ask **only blocking questions, max 5, in one batch**. Anything non-blocking
becomes an explicit numbered assumption in the brief. Never run a
back-and-forth interrogation.
### 4. Write the brief
Use the template in `references/brief-template.md` (it includes a filled
example). Core sections:
- goal (one sentence) + user outcome;
- context: relevant existing pieces, with file paths;
- constraints and conventions to respect;
- scope: what's in;
- non-goals: what's explicitly out (as valuable as scope);
- agent-executable specifications: statements another agent can objectively verify without human judgment;
- edge cases: empty/loading/error/malformed states worth handling;
- non-functional requirements **only when they bite** (performance
budget, accessibility bar, i18n, security constraint): omitted means
"nothing beyond the project's existing bar";
- backward compatibility / migration notes when existing data or users
are affected;
- UX expectations (only if user-facing);
- verification: how "done" gets **proven**: which commands must pass,
what a human/browser check confirms;
- known unknowns + numbered assumptions.
### 5. One-pass confirmation
Show the brief. Ask for corrections once, integrate, done. Don't loop on
polish: downstream skills (`masterplan`) will surface anything structural.
### 6. Run the implementation-readiness review
Read the finished brief as an implementer with no conversation history. Check:
1. The target actor, triggering condition, and desired outcome are clear.
2. Scope and non-goals prevent the most tempting adjacent work.
3. Existing paths/commands are observed or visibly provisional.
4. Every material behavior has a success and relevant failure/edge condition.
5. Permissions, data effects, compatibility, and irreversible actions are
explicitly bounded where applicable.
6. Acceptance criteria can be proven at the right boundary, not merely
acknowledged by a human.
7. Assumptions have identifiers, are falsifiable, and carry an owner/review
trigger when they are material.
If a missing item would change implementation substantially, ask the compact
question batch or return a conditional brief. Do not conceal ambiguity in
polished prose.
## Failure handling and scope change
- **Conflicting user statements:** quote the conflict neutrally and ask for the
decision; do not choose the more convenient interpretation.
- **Repository contradicts request:** preserve the request, report the observed
conflict and path, then offer a revised scope or discovery task.
- **Unsettled product tradeoff:** frame options, consequences, and evidence
needed; route to hotseat instead of pretending it is a requirement.
- **Insufficient repository access:** emit a provisional brief with every
path/command marked assumption, then name the minimum inspection needed.
- **Mid-implementation scope change:** update the goal, scope, non-goals,
affected acceptance criteria, and assumptions together. Do not patch only a
task line while leaving the original definition of done misleading.
- **Approval-bound action:** stop at a precise decision/authorization request.
The brief may specify preparation but not authorize execution.
## Anti-bloat rules
- Every line must remove ambiguity or it gets deleted.
- No restating general knowledge ("React is a component library"): the
reader is a coding agent, not a student.
- No invented requirements the user never implied. Suggestions go in a
clearly marked non-binding suggestions list.
- Stop when the brief removes implementation-blocking ambiguity; brevity is a
quality signal, not a fixed line target.
## Tool selection / fallback
- Repository artifacts and the user's words outrank generic templates.
- Ask only when alternatives materially change behavior, data, permissions, or risk.
- Without repository access, produce a provisional brief and label path or command assumptions.
## Quality gates
- A reader who never saw this chat could implement without guessing on
scope: test your draft against this before showing it.
- Every agent-executable specification is objectively checkable by another agent without human intervention.
- The verification section names real commands/checks (that exist in this
repo or are standard).
- Assumptions are numbered and falsifiable ("A1: single-user, no roles").
## Stop conditions
- User confirms the brief → hand off to `masterplan` (or implement
directly if the task is small), then stop.
- The request reveals an unsettled product decision → stop and route back
to `hotseat` for that decision.
## Output contract
In chat: the brief. On disk (when the task will span sessions or feed
planning): `docs/briefs/<slug>.md` with provenance header
(`<!-- generated by distill on YYYY-MM-DD -->`).
`<slug>`: short kebab-case text derived from the task title.
## Research basis
Read [references/research.md](references/research.md) when a decision depends on
an external standard, a numerical claim, or a fast-moving practice. The ledger
records what the source supports, what it does not support, and when to reverify.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies. | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |
| meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要". | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |