grill-with-docs-lite · diff
git:20260615.a336638 to git:20260726.ed7a980
55 added, 24 removed. Audit A to A.
---
name: grill-with-docs-lite
- description: Run a short boundary-grilling pass for small AI-engineering tasks, clarifying intent, non-goals, terms, constraints, and readiness before mini-spec.
+ description: Run a bounded docs-grounded contradiction hunt before mini-spec, separating source facts from decisions, assumptions, and blockers without building a domain model.
---
# Grill With Docs Lite
## Purpose
- Clarify whether a small AI-engineering task is ready for `mini-spec` by resolving only the ambiguity that could cause wrong work, scope creep, or unsafe implementation.
+ Turn a fuzzy but small AI-engineering request into a compact, source-grounded clarification delta for `mini-spec`.
+ This is not an exhaustive interview or a domain-modeling workflow. It does not build a glossary, write ADRs, or walk every branch of a decision tree. Its job is to find the few contradictions or unknowns that could make the next bounded slice wrong.
+
## When to use
- Use when a request is probably small enough to move quickly, but contains vague terms, unclear success criteria, unknown constraints, hidden assumptions, or boundary risk.
+ Use when a request is probably small enough to move quickly, relevant docs or repo evidence exist, but success criteria, constraints, terminology, or assumptions may conflict with that evidence.
- Use a fuller domain-model grilling workflow instead when the work depends on existing glossary terms, ADRs, cross-context architecture, or deep codebase/domain alignment.
+ Use a fuller domain-model or architecture workflow instead when the work requires canonical vocabulary, multiple hard-to-reverse architectural decisions, cross-context modeling, or an open-ended decision tree.
## Inputs
- User request
- Existing notes or docs
- Relevant repo files
- `CONTEXT.md` if present
## Workflow
- 1. Restate the request in concrete terms.
- 2. Challenge vague words such as "better", "fast", "simple", or "automated".
- 3. Identify domain terms and define them in working language.
- 4. Surface assumptions, decisions, non-goals, and external constraints.
- 5. Ask only questions that block safe progress.
- 6. Update `CONTEXT.md`.
- 7. Give a readiness judgment: ready, ready with assumptions, or blocked.
+ 1. Read the smallest relevant source set before asking questions.
+ 2. Extract only facts that can change scope, acceptance, compatibility, or verification.
+ 3. Classify each unresolved point as:
+ - `FACT` — supported by a source; include the file/path or other locator.
+ - `DECISION` — requires an explicit user/product choice.
+ - `ASSUMPTION` — a reversible working default that can be stated safely.
+ - `UNKNOWN` — missing evidence that blocks safe progress.
+ 4. Hunt for contradictions between the request, source facts, non-goals, constraints, and existing behavior.
+ 5. Answer from docs or code when the repository can settle the point; do not ask the user to repeat discoverable facts.
+ 6. Ask only blocking questions. Default question budget: at most 3. Ask one at a time only when an answer can change the next question.
+ 7. Do not update `CONTEXT.md`, create glossary entries, or write ADRs as part of this skill.
+ 8. Emit one compact **CLARIFICATION DELTA** for `mini-spec` and stop.
+ 9. If the ambiguity cannot fit the bounded question budget without losing important decisions, route to a fuller clarification/domain-model workflow instead of expanding this skill.
## Outputs
- - Clarified request
- - Domain terms
- - Decisions
- - Assumptions
- - Non-goals
- - Unresolved questions
- - Readiness judgment
+ Use this compact shape:
+ ```text
+ CLARIFICATION DELTA
+ Objective: ...
+ Source-backed facts:
+ - FACT — ... [path/locator]
+ Decisions:
+ - ...
+ Assumptions:
+ - ...
+ Non-goals / boundaries:
+ - ...
+ Open blockers:
+ - ... | none
+ Mini-spec readiness: ready | ready with assumptions | blocked
+ ```
+
+ The delta is input to `mini-spec`; it is not a replacement for `SPEC.md`.
+
+ ## Success looks like
+
+ - The next slice is clearer because contradictions were resolved, not because the interview was exhaustive.
+ - Source-backed facts are distinguishable from choices and assumptions.
+ - The agent asked no question that available docs or code could answer.
+ - The result is compact enough to feed directly into `mini-spec`.
+
## Stop conditions
- - The problem language is clear enough for a mini-spec.
- - A blocking question cannot be answered from available context.
+ - The problem is clear enough for `mini-spec`.
+ - The default question budget is exhausted and important ambiguity remains → route to a fuller workflow.
+ - A blocking unknown cannot be resolved from available evidence.
## Anti-patterns
- - Starting implementation before the problem language is clear.
- - Treating unclear business terms as obvious.
- - Asking broad questions when a narrow assumption would work.
- - Turning a short readiness gate into a full domain-model interrogation when the next slice only needs bounded intent.
+ - Building a glossary or ADR trail during a lite pre-spec pass.
+ - Walking every branch of a decision tree after the bounded slice is already clear.
+ - Asking broad questions when a narrow assumption would safely unblock progress.
+ - Treating source silence as a fact.
+ - Restating whole documents instead of extracting decision-relevant evidence.
+ - Asking the user for information the repository can answer.
+ - Starting implementation before the clarification delta is ready for `mini-spec`.