# Ziw Grill

> Grills an idea, plan, PRD, ADR set, or existing spec one question at a time and produces authoritative specs ready for ticket slicing. Use when the user asks to be grilled or material product, domain, scope, or architecture ambiguity blocks safe progress.

- Skill: `zaks-io/ziw-grill` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add zaks-io/ziw-grill`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zaks-io/ziw-grill/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: zaks-io (https://skillmd.com/u/zaks-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zaks-io/ziw-grill

---


# Grill

Turn fuzzy or contradictory plans into shared understanding and authoritative
planning artifacts. Grill owns clarification, not tickets or implementation.

## Inputs

- An idea, plan, question, PRD, ADR set, or existing spec to challenge.
- The current repo, caller context, and workflow config when available.

## Invocation Threshold

Explicit invocation always starts. Invoke implicitly only when an unresolved
product, domain, scope, or architecture decision could change behavior, ticket
boundaries, risk, dependencies, or required proof after available evidence is
checked. Say what ambiguity caused the pause. Do not invoke for routine details,
harmless preferences, or discoverable facts.

## Context

Read repo instructions first. Then read the planning-artifact mapping in
`docs/agents/workflow/config.md` when present. Load
[references/planning-artifacts.md](references/planning-artifacts.md) for
authority, default formats, ADR rules, and the readiness contract.

If config does not map planning artifacts, discover existing specs, context or
glossary files, ADRs, roadmaps, and relevant implementation. Preserve the
established convention and report the missing mapping as a Setup gap.

Treat code and external systems as evidence, not automatically as intended
behavior. For existing artifacts, run a contradiction and requirement-coverage
pass first. For a new idea, build the decision tree from scratch. Both paths
converge on the same readiness contract.

## Grilling Loop

1. Build a private decision tree ordered by dependency and impact. Cover only
   applicable outcome, actor, language, scope, behavior, data, security,
   failure, concurrency, integration, operations, rollout, and acceptance
   branches.
2. Resolve discoverable facts from code, docs, config, or authoritative sources.
3. Ask one highest-leverage question with evidence, a recommendation, and its
   consequence.
4. Wait for the user's answer. Do not bundle follow-up questions.
5. Challenge vague terminology and propose one canonical term.
6. Stress-test the answer with concrete scenarios, especially boundary,
   lifecycle, failure, concurrency, authorization, and recovery cases.
7. After explicit confirmation, update the smallest authoritative artifact set
   immediately and keep the active spec `Draft`.
8. Recompute the tree and repeat until the pre-approval gate can pass.

## Artifact Updates

Update the spec that already owns the behavior, or create one focused spec when
none does. Update context docs only for domain language. Create an ADR only
after a confirmed decision passes all three ADR tests in the reference. Never
substitute an ADR, transcript, scratch note, or ticket for current truth. In
conversation-only use, emit a self-contained Markdown spec.

## Readiness

Keep the active spec `Draft`. After the reference's pre-approval gate and final
contradiction pass, present the recommendation, outcome, non-goals, deferred
questions, changed artifacts, risks, and assumptions.

Ask exactly one final question: `Mark this spec ready for slicing?`

Only explicit confirmation may change status to `Ready for slicing`. Run
configured documentation checks. Failed checks return the spec to `Draft`.

## Caller Handoff

Return to an implementation caller only when no ticket scope, risk, dependency,
acceptance, or proof boundary changed. Otherwise stop implementation, never
widen the PR or silently rewrite tracker work. Handoff with:

- File: `$ziw-to-issues <spec-path>`
- Conversation: `$ziw-to-issues use the Ready for slicing spec in this conversation`

## Guardrails

- Do not create or edit tracker tickets.
- Do not invoke To Issues, implement code, open PRs, merge, or deploy.
- Do not edit planning artifacts before the user confirms the decision.
- Do not ask a question that available evidence can answer.
- Do not expose secrets or private customer data in planning artifacts.

## Done

Report spec status and path, decisions and evidence, changed artifacts, blocking
and deferred questions, checks, Setup gaps, and either the next single question
or the exact file-backed or conversation-only To Issues handoff.