| name | auto-grill |
| description | Workflow-powered autonomous grill — fans out agents to self-answer a topic's decisions from vault/code/web, verifies grounding, and surfaces ONLY the genuine gaps. Use for '/auto-grill <topic>', 'auto-grill this', 'grill this unattended', or as a cron planning front-end. Interactive /grill and /grill-fast are for live human interviews; auto-grill answers itself first. |
Vault Location
Vault path: Read from ${CLAUDE_PLUGIN_ROOT}/brain-os.config.md (real config at ~/.brain-os/brain-os.config.md; default vault /Users/thanhdo/work/brain).
What it does
/auto-grill is /grill with the human taken out of the inner loop. It runs the autogrill loop as a Workflow so most questions are answered from evidence before anyone is asked:
- Detect — decompose the topic into the decisions it implies (ARCH vs PARAM), same partition as
/grill-fast.
- Auto-search — one agent per decision searches vault → code → web and commits to the single best-practice answer with citations.
- Verify grounding — a skeptic re-reads every citation. An answer is resolved only if a citation verifiably supports it; otherwise it becomes a surfaced gap.
- Surface only gaps — the human (interactive) or an issue queue (unattended) sees ONLY what evidence could not settle.
- Write back — the grill-session file is written to the vault so the resolved decisions never need re-asking.
The load-bearing piece is step 3. Auto-grill's whole value is "ask the human only what the vault genuinely doesn't know," and its only dangerous failure is a confidently fabricated answer that buries a real gap. The grounding verifier defaults to not grounded when uncertain, and the Workflow re-reads each cited file — a recommendation with no real citation is reclassified as a gap, never silently accepted.
When to use which grill
| Skill | Who answers | Best for |
|---|
/grill | human, every question | live design interview; taste/strategy where the human IS the evidence |
/grill-fast | human, picks among pre-rendered trees | architecture topic where you want to decide in 2-3 turns |
/auto-grill | agents self-answer; human only on gaps | topics with real vault/code coverage; unattended cron planning; draining "grill design first" issues |
If the topic is pure taste, strategy, or has no vault/code grounding, the auto-search resolves nothing — every decision becomes a gap and you are back to a normal /grill. That is the correct, honest outcome, not a failure. Auto-grill earns its keep on topics with partial coverage.
Usage
/auto-grill <topic> # interactive: surfaces gaps to you via AskUserQuestion
/auto-grill <topic> --unattended # cron mode: gaps become issues + a report, no human prompt
/auto-grill #287 # an issue number: fetches the body as context first
Flow
1. Gather context (deterministic, before the Workflow)
- Resolve
vault_path and gh_task_repo from brain-os.config.md.
- Compute today's date (
date +%Y-%m-%d) — pass it into the Workflow (args.date); Workflow scripts cannot call new Date().
- If the topic is an issue reference (
#N or a tracker URL), run gh issue view N --repo <gh_task_repo> FIRST and pass the body as args.context. The SessionStart cache is stale; never grill an already-closed issue.
- For a free-text topic, pass any user-provided detail as
args.context.
2. Run the Workflow
Invoke the Workflow tool with scriptPath pointing at the canonical script (resolve CLAUDE_PLUGIN_ROOT):
scriptPath: ${CLAUDE_PLUGIN_ROOT}/skills/auto-grill/references/auto-grill.workflow.js
args: { topic, context, vaultPath, taskRepo, date, unattended }
The script runs four phases — Decompose → Auto-answer → Verify-grounding → Synthesize — and returns:
{ metric:{total,resolved,gaps}, framing, sharedAxis, resolved[], gaps[], markdown, gapQuestions[], recommendation }.
This is ultracode territory: the run spawns one agent per decision plus a verifier each, so only invoke the Workflow when the user opted into multi-agent orchestration (said ultracode, asked for a workflow, or invoked this skill). Use the strongest model for the first run on any topic — the grounding gate is only as good as the retriever; do not cost-optimize the auto-answer stage to Sonnet until the topic class is proven.
3. Write the grill-session file
Write the returned markdown to {vault}/daily/grill-sessions/YYYY-MM-DD-<topic-slug>.md, prepending frontmatter:
---
title: "Auto-grill — <topic>"
created: YYYY-MM-DD
tags: [auto-grill, workflow, autogrill]
zone: daily
status: <pass|working|reflection>
sparked_by:
- "/auto-grill <topic>"
grounding: "resolved <R>/<T> from evidence; <G> gaps surfaced"
---
Then append the resolved-decision citations as wiki-links where they point at vault files, so the session participates in vault backlinking.
4. Surface the gaps
- Interactive: present
gapQuestions to the user. If the file is story-tier with ≥3 ARCH decisions, the markdown already holds the ≥4-tree render — present the trees via AskUserQuestion (grill-fast convention). Otherwise ask the gap questions as prose, one batch, with your recommended answer per gap (decide-and-recommend). Write the user's answers back into the file under # Open gaps — resolved by human and flip those gaps to resolved.
- Unattended (
--unattended): do NOT call AskUserQuestion. For each gap, file an issue on gh_task_repo titled [auto-grill gap] <question> with the body = the gap's why + surfacedQuestion + a backlink to the grill-session file. Write a one-line summary to {vault}/daily/auto-grill-reports/YYYY-MM-DD-<slug>.md. The loop owner triages the issues later.
5. Status gate (same contract as /grill)
- Story-tier (implies implementation) → it MUST carry ≥1 acceptance bullet marked
(LIVE E2E) before status: pass. If the synthesized markdown lacks it, add the smallest end-to-end check that would prove the abstraction, or lock status: working and leave the build for a follow-up.
- Reflection-tier (no implementation surface) →
status: reflection; no /slice, no audit menu.
- Any gaps still open and unanswered →
status: working, not pass.
6. Next step
After a story-tier status: pass with all gaps resolved, the canonical next step is the /grill end-step audit menu (/audit --all) then /slice <grill-file>. Auto-grill does not re-implement the audit menu — defer to /grill's for consistency.
Gotchas
- Grounding beats coverage. A high resolved/total ratio is only good if each citation is real. Never tune the verifier toward "grounded" to make the metric look better — the metric exists to expose gaps, not to hide them. Trust the skeptic's default-to-gap bias.
- Unattended mode never blocks. No
AskUserQuestion, no prose question that waits for a human. Gaps go to issues. This is what lets a self-improvement loop use auto-grill as its planning front-end on a cron.
- Do not auto-grill taste. Music/lyric taste, brand voice, and strategy calls have no vault citation that can settle them — every decision correctly becomes a gap. Running auto-grill there wastes a fan-out; route to
/grill with the human.
- Recommend one pick, don't enumerate. Inherited from
/grill: a resolved decision states the single best answer with its citation, not a menu.
Outcome log
Follow skill-spec.md § 11. Append to {vault}/daily/skill-outcomes/auto-grill.log:
{date} | auto-grill | grill | ~/work/brain-os-plugin | daily/grill-sessions/{date}-{slug}.md | commit:{hash} | {result} | args="{topic}" resolved=R total=T gaps=G mode={interactive|unattended}
result: pass if the session locked (status: pass story-tier with live-e2e AC + all gaps resolved, OR status: reflection); partial if gaps remain open (status: working); fail if the Workflow errored or produced no decisions.resolved=R total=T gaps=G is the grounding metric — the primary success signal /improve mines for this skill (rising gaps on a covered topic = retriever or verifier regression).
