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.
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 →
hotseatfirst. - 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 |
| Triggered behavior | When , the system shall |
| Conditional behavior | While , the system shall |
| Failure/exception | If , the system shall |
| Prohibition/invariant | The system shall not |
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:
- The target actor, triggering condition, and desired outcome are clear.
- Scope and non-goals prevent the most tempting adjacent work.
- Existing paths/commands are observed or visibly provisional.
- Every material behavior has a success and relevant failure/edge condition.
- Permissions, data effects, compatibility, and irreversible actions are explicitly bounded where applicable.
- Acceptance criteria can be proven at the right boundary, not merely acknowledged by a human.
- 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
hotseatfor 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 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 |