Use this skill when a new/regenerated PPT lacks an explicit production scheme, or another result-affecting ambiguity remains. Notes-only, narration-only and preview-only tasks do not require a production scheme; ask only about unresolved details within the requested editing scope.
Mandatory production-scheme choice
An unspecified scheme is always blocking for a new or regenerated PPT. MUST ask
the user to choose directly generated editable PPT, full-image reconstruction,
or partial-image reconstruction, using the exact user-facing labels in
workflows/clarification-gate.md. No automatic default; wait for the user's answer
before slide planning, image generation, SVG reconstruction or PPTX production.
An explicit choice already made for the same task must not be asked again.
Mandatory reconstruction-mode choice
In both choice rounds, MUST show Token consumption and time-consumption levels for every option before the user chooses. Explain that levels are relative estimates adjusted for scope and complexity, not exact usage or promised time; disclose image generation separately. Follow the cost and time disclosure in the clarification workflow.
For image reconstruction, confirm full-image vector reconstruction (full_vector) or preserve complex illustrations (preserve_complex_images) through workflows/clarification-gate.md ) before execution. No automatic default, even for “hurry up”; reuse only an explicit choice in the same task. Both modes require native PPT text boxes. Preserve one source line in one text box, merging OCR fragments and using text runs for mixed styling; keep independent labels and table cells separate. Full-vector mode needs approval before any raster exception. Partial rebuilds apply this within selected regions.
Blocking rule
Do not infer a value when two or more reasonable interpretations would change the route, story, page count, template, visible wording, or visual fidelity. Ask the user to choose. A recommendation is allowed, but it only becomes a decision when the user explicitly chooses it or says to use the recommendation.
Do not write deck_plan.json, design_spec.md, spec_lock.md, SVG pages, or
an exported PPTX while a blocking clarification remains unanswered.
Conversation protocol
For academic tasks, read references/academic-orchestration.md before asking.
Use its evidence-aware intake and internal handoffs across all templates and
production schemes. Catalog completion alone does not establish readiness:
resolve the academic brief's material gaps and conflicts before planning.
Default to an adaptive interview in the conversation, using native popup questions. Never open an in-app browser, HTML guide, questionnaire, or require copy/paste to discover requirements unless the user explicitly requests that UI.
- Inspect the conversation and available source metadata first. Maintain confirmed facts, unresolved decisions and contradictions internally. Do not ask for information already visible in the user's files or messages.
- Ask ONE highest-impact question with the host's native question tool
(
request_user_input_asyncin Codex Default mode; use a synchronous question tool only where available). Wait for the answer before dependent work. Group up to three questions only when their answers are genuinely independent. - Give concise context-specific options and a justified recommendation; allow free text. Ask for a missing fact directly when choices would distort it. Explain route/mode tradeoffs without internal IDs; retain token/time disclosure.
- Use each answer to choose the next question. Narrow broad goals, identify what the audience should understand or decide, and surface contradictions such as exhaustive evidence versus a five-minute talk. Offer concrete tradeoffs. Do not mechanically exhaust a catalog or ask for detail that would not change the result.
- Persist explicit answers and skip resolved items. Handle free-text answers faithfully; never coerce them into an inaccurate canned option. Check source access, research scope, length, route, applicable editability/template choices and any preserve/rewrite boundary before execution.
- Stop when the task can be executed without a material guess. Briefly restate the agreed outcome and proceed. No confirmation of the confirmation. Resolve conflicts first. Missing files call for the specific file, not more options.
Do not ask open-ended “please describe it further” questions when a choice set can expose the ambiguity. Do not ask again for a value the user already made explicit.
State contract
Use the repository question catalog and state machine:
For new academic content tasks, add --academic to clarify init. This extends
the same blocking state machine with academic goals, evidence policy, audience,
timing, style and content boundaries. It conditionally requires research scope
and/or a material inventory. Keep this off for notes-only edits and faithful
reconstruction of an already approved deck with no new content planning.
Older saved requests remain compatible; do not restart an approved task.
Free-text questions have no option_ids: save the actual response with
clarify answer ... --answer "field=actual response". Populate explicit facts
via --known-json first. Record inspected file content with --by "inspection:file:page"; record user answers with --by "user:message".
needs_material_inspection has an empty popup payload: inspect the files,
resolve essential missing sources, then record the source-located inventory.
Never mark a missing/unreadable required file as an inspected usable source.
Copy the confirmed decisions into deck_plan.json as academic_brief and
retain the sibling clarification_request.json for the existing plan gate.
python scripts/easyslides.py clarify init --route new_deck --out <project>/clarification_request.json
python scripts/easyslides.py clarify answer <project>/clarification_request.json --answer purpose=defense
python scripts/easyslides.py clarify next <project>/clarification_request.json
python scripts/easyslides.py clarify require <project>/clarification_request.json
The request is confirmed only when every blocking question has an answer. The machine-readable state is the source of truth for the later deck plan and execution lock.
next is a read-only catalog adapter. Its questions array matches Codex's
request_user_input_async payload; map the actual answer using option_ids.
For a different host or a synchronous tool, convert to that tool's declared
schema (including required question IDs, headers and structured options); never
call an unavailable tool. If no popup tool is available, ask one concise question
with options directly in chat and wait. A browser is not the fallback.
The adapter does not display a popup itself. ready_for_summary means catalog
choices and enabled academic requirements are recorded; still check their
substance, contradictions, source rights and partial regions. The program
checks completeness, not the truth of an inspection or scientific claim.
Follow interview examples in workflows/clarification-gate.md.