Stress-test and refine an OpenSpec change through a structured grilling session. Use when the user wants Codex to interrogate, complete, or improve an existing or planned OpenSpec change, maintain a visible problem panorama and progress map, resolve unclear requirements and design decisions one question at a time, and write confirmed decisions back into proposal.md, design.md, specs, and tasks.md.
Stress-test and refine an OpenSpec change through a structured grilling session. Use when the user wants Codex to interrogate, complete, or improve an existing or planned OpenSpec change, maintain a visible problem panorama and progress map, resolve unclear requirements and design decisions one question at a time, and write confirmed decisions back into proposal.md, design.md, specs, and tasks.md.
Apply the grill-with-docs working mode to an OpenSpec change.
Interview the user relentlessly until the change is coherent across requirements, design, specification deltas, and implementation tasks. Walk the decision tree one branch at a time. Resolve dependencies between decisions before moving on. Write confirmed decisions into the relevant OpenSpec artifacts as they crystallize.
Ask exactly one user-facing question at a time and wait for the answer before continuing. If a structured user-input tool is available, use it; otherwise ask the question in plain text. Include a recommended answer whenever the decision is not obvious.
Do not implement application code while using this skill. Edit OpenSpec artifacts only.
If the user asks a clarifying side question, answer it directly, then return to
the same panorama node unless the answer changes the decision tree. If it does
change the tree, redraw the panorama before the next question.
Inputs
Accept any of these inputs:
A change id, such as add-guard-management-plane
A vague reference, such as "this change" or "the current OpenSpec change"
A design concern, goal, or partial change idea
If the target change is unclear, inspect active changes before asking:
openspec list --json
If exactly one active change exists, use it. If several active changes exist, ask the user which one to grill. If no change exists, ask whether to create a new change or refine a proposed one.
Inspect First
Before asking product or design questions, inspect what can be discovered locally.
Run:
openspec status --change "<change-id>" --json
Read existing artifacts for the change:
openspec/changes/<change-id>/proposal.md
openspec/changes/<change-id>/design.md
openspec/changes/<change-id>/tasks.md
openspec/changes/<change-id>/specs/**/spec.md
If an expected artifact is missing, get its OpenSpec instructions before creating it:
Follow returned templates, rules, and context. Do not copy instruction metadata into artifact files.
Also inspect project context that explains the change:
Existing OpenSpec specs touched by the change
Project docs or ADRs referenced by the proposal
Code paths named by tasks or design notes
Validation commands already used for the affected surfaces
If a question can be answered from these sources, answer it from the sources and continue instead of asking the user.
Build A Change Map
Create an internal map before grilling:
Problem statement and desired outcome
Actors, operators, and affected users
Scope boundaries and explicit non-goals
Changed capabilities and requirement deltas
Concrete scenarios already covered
Design commitments, alternatives, and trade-offs
Implementation tasks and validation tasks
Open questions, contradictions, weak assumptions, and missing failure paths
Prefer a map that exposes dependency order, not just document order. For
agent-platform workflows, map the full path across client skill, MCP helper,
API validation, persisted state, worker/runtime behavior, readiness or status
query, review or execution gate, UI copy, feedback or handoff evidence, and
regression coverage.
Maintain A Visible Panorama
Before asking the first design or product question, show the user a compact
problem panorama for the change. Keep it simple enough to scan, but complete
enough that the user can see the remaining discussion space.
The panorama must include:
Current phase: Requirements, Design, Specs, Tasks, or Final Sweep.
A compact progress bar or fraction, updated as phases or major branches are
resolved.
Major branches still to resolve.
Current branch and question position.
Known decisions already confirmed.
Open or risky areas that may change the map.
Use a low-height ASCII map for the normal view. Node labels should be short.
Show a more detailed explanation only the first time, or when the discussion
tree changes materially. On ordinary turns, show only the compact map and the
current node. Include enough progress signal that the user can tell when the
discussion is likely to finish.
Before each user-facing question, briefly mark where the question sits in the
panorama. After each user answer, update the panorama if the answer changes the
discussion tree, scope, order, or unresolved risks.
Also maintain a tasklist or plan for your own progress. Update it as the
grilling session moves through phases so you do not lose track of unresolved
branches. The plan can be internal tool state, a short visible checklist, or
both. Do not let the plan replace the one-question-at-a-time discipline.
When the user asks "how much remains" or appears lost, show the panorama and the
remaining branches before asking the next question.
Look for these defects:
Terms used inconsistently between proposal, design, specs, and tasks
Requirements without observable scenarios
Scenarios that are not supported by requirements
Tasks that are not justified by requirements or design
Design decisions without rationale
Hidden scope expansion inside tasks
Missing compatibility, migration, rollback, authorization, or failure behavior
Missing tests or validation commands for the changed surfaces
For interaction contracts, also look for:
A capability advertised by skills, UI, docs, or helpers before the downstream
platform path can complete or actionably reject it
Matrices used as permissive runtime flags instead of release guidance
Pseudo-states that represent partial implementation rather than real product
states
Diagnostic-only evidence routed through formal production objects
Failure states that hide who can remediate the issue and whether retry,
re-upload, review, or downstream execution is required
Grilling Order
1. Requirements
Challenge the problem and boundaries first.
Ask about:
Who the affected user, operator, or system is
What success looks like
What behavior changes by default
What stays backward compatible
What is explicitly out of scope
What security, privacy, safety, or governance constraints apply
What should happen on failure or partial availability
When a requirement is confirmed:
Update proposal.md for problem, scope, impact, or non-goal changes
Update specs/<capability>/spec.md with ADDED, MODIFIED, or REMOVED requirements
Add concrete scenarios using the repository's OpenSpec scenario style
2. Design
Challenge architecture only after the requirement boundary is clear.
Ask about:
Ownership and source of truth
Data flow and control flow
APIs, schemas, and versioning
State transitions and persistence
Authorization, confirmation, and audit requirements
Failure modes and degraded behavior
Migration, rollback, and compatibility
Alternatives rejected and why
For workflows that cross agents and platform runtime, ask which boundary owns
truth and which boundary owns remediation. Split states or references when that
distinction changes the correct user action. For example, do not collapse an
ingest failure that requires re-upload with a downstream materialization failure
that requires mapping, review, or worker remediation.
When a design decision is confirmed:
Update design.md immediately
Record rationale and trade-offs when future readers would otherwise miss the reason
Reflect behavior changes back into specs
Add or refine tasks needed to implement the decision
Validate the change after meaningful write-backs when validation is cheap
3. Specs
Validate every changed capability.
For each capability:
Make requirement names precise and behavior-oriented
Ensure each requirement has observable scenarios
Add negative, conflict, and degraded-path scenarios where correctness depends on them
Keep specs focused on what the system SHALL do, not implementation steps
Create missing capability spec files only after checking OpenSpec instructions
4. Tasks
Finalize tasks after proposal, design, and specs are coherent.
Ensure tasks.md:
Covers every confirmed requirement and scenario that needs implementation
Orders dependencies clearly
Includes schema or contract work before consumers
Includes tests for new behavior, negative paths, and degraded states
Includes documentation or migration work when needed
Includes validation commands for the changed surfaces
Avoids implementation work outside confirmed scope
Names known residual code, skill, docs, or copy locations when a sweep has
found them, so implementation does not rely on memory
Question Discipline
Ask one focused question at a time.
Every question should include:
The decision that needs confirmation
Why it matters
A recommended answer first when a recommendation is defensible
Concrete alternatives when useful
Prefer this shape:
Which component should own desired guard configuration revisions? This matters because it determines conflict handling and source-of-truth semantics.
Recommended: The guard manager owns desired revisions; defenders own effective validation.
Alternatives: Defenders own both desired and effective revisions; gateway owns desired revisions and pushes them to defenders.
Do not ask questions that local inspection can answer. Do not ask several branches in one message.
Write-Back Rules
Use this mapping when capturing confirmed decisions:
Write updates as soon as the decision is confirmed. If the user explicitly defers a blocking answer, record the deferral in the most relevant artifact as an open question or deferred task.
After each write-back, check whether the same decision must also update related
capability specs, concept docs, skill guidance, frontend copy, or validation
tasks. Do not leave a confirmed cross-surface decision captured in only one
artifact.
Final Sweep
Before finishing:
Re-read every changed artifact.
Confirm proposal, design, specs, and tasks tell the same story.
Run targeted searches for deprecated terms, pseudo-states, removed tools, or
advertised capabilities that should no longer appear.
Run:
openspec validate "<change-id>"
openspec status --change "<change-id>"
Fix OpenSpec artifact issues and validate again.
Finish with a concise summary:
Change id and location
Artifacts updated
Key decisions confirmed
Remaining open questions, if any
Validation result
Do not call the grilling session complete while unresolved questions still block coherent OpenSpec artifacts.
