Skip to content

Kartik-Doye/Ravengard-AI-Recruiter / agent/skills/distill

distill

Verified

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:

ClassMeaningTreatment
Confirmed factuser statement or observed repository evidencecite compactly
Constraintexplicit requirement, policy, compatibility, budget, or authority limitpreserve verbatim when material
Assumptionreasonable choice that does not need user input yetnumber it and make it falsifiable
Open decisionplausible answers materially change outcomeask or route to hotseat
Suggestionnon-binding improvement beyond the requestisolate; 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:

SituationRequirement form
Ubiquitous behaviorThe system shall
Triggered behaviorWhen , the system shall
Conditional behaviorWhile , the system shall
Failure/exceptionIf , the system shall
Prohibition/invariantThe 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 typeBrief shape
tiny task (button rename, copy fix)goal + acceptance criterion + where: 5–10 lines, no template ceremony
featurefull template below
large feature / migrationfull template + NFRs, rollout constraints, backward-compatibility and data-migration notes
bug/change requestreproduction facts + expected behavior + scope guard (what NOT to fix along the way)
greenfield productfull 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 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.

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: 119kUpdated Claude CodeCodexVerifiedInstall
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: 118kUpdated Claude CodeCodexVerifiedInstall
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: 108kUpdated Claude CodeCodexVerifiedInstall
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: 108kUpdated Claude CodeCodexVerifiedInstall