Ask

Ask

ask is the canonical skill at skills/canonical/ask/SKILL.md. It is the user-facing top-level workflow for ordinary natural-language requests. Use this skill as the default top-level workflow for a new ordinary user request in this workspace unless the request is clearly explicit operator work.

The user should be able to ask naturally. They should not need to name internal workflow IDs or repository mechanics first.

If the request is clearly an explicit setup, status, sync, adapter-maintenance, or operator-review request, switch to the matching top-level workflow instead of forcing it through ask.

Front-Door Law

• Reading this skill is not legal ask execution.
• Native-thread reconciliation is not legal ask execution.
• ask itself remains the only ordinary natural-language front door, and a request counts as ordinary front-door execution only after it has been opened as a canonical ask turn under this workflow.
• Plan Mode or a similar host planning/collaboration mode should not discourage the host from opening canonical ask for an ordinary user request; if the current mode still blocks ask, the host should use a concise in-band alert or approval question and continue the same user task in the most natural available way rather than silently defaulting to operator-direct or side-path work.
• See Canonical Ask Contract below for the exact ordinary-ask opening and completion rules. Generated adapter guidance may restate that contract, but it does not replace this workflow surface, and compatible hosts must use that supported entry surface rather than helper stitching, ad hoc probing, or direct lifecycle calls.
• Direct evidence commands such as public retrieve or trace remain legal operator tools, but they do not complete the ordinary ask contract by themselves.

ask owns front-door legality, same-turn governance, workspace gating, and routing. The routed inner workflow owns the deeper evidence loop.

Turn Terms

• native turn means the host's own chat turn before DocMason opens canonical ask handling.
• canonical ask turn means the governed DocMason turn for the current request.
• runtime ownership means the current request has been opened into that canonical ask turn and is now governed by DocMason.
• native ledger means host-side audit capture that is not canonical ask truth by itself.
• interaction-ingest means the runtime holding area for reconciled host activity before any governed promotion.
• A practical sign that canonical ask really opened is that the request leaves linked runtime artifacts rather than only a host-visible reply, typically under runtime/answers/, runtime/runs/, and runtime/logs/.

Canonical Ask Contract

• This section is the authoritative ordinary-ask execution contract for compatible hosts.
• workflow.json remains routing metadata. It does not define the executable host call contract.
• A request counts as an opened canonical ask turn only when both are true:
  • the supported ask entry surface has returned stable conversation_id, turn_id, run_id, answer_file_path, and log_context
  • the underlying turn has been upgraded to front_door_state = canonical-ask
• For compatible-host execution, the supported ask entry surface is the hidden host wrapper:

cat <<'JSON' | ./.venv/bin/python -m docmason _ask
{ ...payload... }
JSON

• Hidden wrapper actions:
  • open
  • progress
  • finalize
• open request envelope:

{
  "action": "open",
  "question": "<user question>",
  "host_provider": "<provider>",
  "host_thread_ref": "<stable host thread ref>",
  "host_identity_source": "<host identity source>",
  "semantic_analysis": {
    "question_class": "answer",
    "question_domain": "workspace-corpus",
    "route_reason": "<one concise reason>"
  }
}

• Minimal host hinting rule:
  • semantic_analysis is best-effort. For an ordinary native Codex ask, question_class, question_domain, and one concise route_reason are usually enough.
  • classify by deliverable and evidence basis, not by perceived difficulty:
    • question_class chooses workflow shape. It is not a difficulty score: use answer for a direct answer, explanation, or source-backed summary; use composition for a new evidence-backed work product or synthesis; use retrieval, provenance, or runtime-review only for explicit evidence, citation, or runtime-review requests.
    • question_domain chooses evidence basis. It is not a mirror of question_class: prefer workspace-corpus, external-factual, or general-stable when one of those is the real basis, and reserve composition for composition-shaped evidence planning rather than setting it merely because question_class = composition.
    • a compare, draft, or plan request over workspace materials is therefore usually question_class = composition with question_domain = workspace-corpus.
  • open normalizes missing supported routing fields, derives defaults such as support_strategy, and may refine reference resolution or workspace notices from repository truth.
• Native Codex fast path:
  • for an ordinary request on the native Codex path, once repo-local .venv is available, call hidden open directly with best-effort semantic_analysis
  • prefer the real native CODEX_THREAD_ID identity from the execution environment; do not hand-fill placeholder host thread references such as codex-desktop-thread or codex-native-thread
  • do not read other workflow skills, workspace-status, workspace-bootstrap, source search, implementation source, or tests first just to decide whether canonical ask may open, whether a named source exists, or which semantic_analysis fields are accepted
  • use those surfaces only after open returns a governed blocker, waiting state, or explicit operator route
• After open, preserve the returned conversation_id, turn_id, run_id, answer_file_path, log_context, and support_contract for the rest of the same canonical ask turn.
• Hidden wrapper status meanings:
  • execute means canonical ask is open and the host should continue through the chosen inner workflow.
  • awaiting-confirmation means pause the same turn and wait for the user's confirmation reply.
  • awaiting-user-decision means pause the current work for a material decision that only the user can authorize. It never implies a timeout, default, or skip.
  • waiting-shared-job means pause the same turn and wait for governed shared-job settlement.
  • completed means the turn is committed and a final business answer may be returned.
  • boundary means the turn is committed as a governed boundary and that boundary reply may be returned.
  • blocked means no final business answer may be returned yet.
• Hidden wrapper next_step is a derived convenience field and should stay aligned with that status law:
  • execute -> continue-inner-workflow
  • awaiting-confirmation -> wait-for-user-confirmation
  • awaiting-user-decision -> wait-for-user-decision
  • waiting-shared-job -> wait-for-shared-job
  • completed -> return-final-answer
  • boundary -> return-boundary-answer
  • blocked -> do-not-return-final-answer
• Hidden wrapper result_explanation is a derived convenience field, not a new truth surface.
  • When result_explanation.show_to_user = true for a blocker or evidence boundary, translate its summary, why, and next_step into one concise user-facing explanation in the user's language.
  • Do not append it to a successful copy-ready artifact; successful completion returns only the exact business answer plus the separate user_status_line.
  • When show_to_user = false, do not add extra result-explanation prose.
  • Do not write result_explanation text into the canonical answer markdown.
• Hidden wrapper admissibility_repair is present only for same-turn repairable finalize failures.
  • Treat it as repair metadata for the next rewrite/retrace attempt, not as permission to bypass trace or admissibility.
• In compatible-host execution, open or same-turn reuse already performs governed preanswer work:
  • question classification and support-strategy selection
  • workspace gating and knowledge-base freshness checks
  • initial inner-workflow routing plus any confirmation or waiting-state settlement
• After open, treat the returned status, question_class, question_domain, analysis_origin, route_reason, inner_workflow_id, support_strategy, reference_resolution, source_scope_policy, support_contract, and notices as the source of truth for the next step. Do not re-derive them from side-path probing before honoring that result.
• Retrieve / trace binding rule:
  • when using public docmason retrieve or docmason trace inside the same canonical ask turn, export each returned log_context field as DOCMASON_<FIELD> and then call the public command normally
  • in chat-host execution, prefer --json --compact for interactive inspection; if full nested retrieve or trace detail is genuinely needed, redirect full --json to a local file and inspect it selectively instead of loading the raw payload straight into the live chat context
  • treat compact payloads as the stable host-facing inspection contract; do not rebuild alternate schemas with ad hoc jq assumptions such as .matches
  • compact retrieve inspection should normally start from:
    • session_id
    • results
    • reference_resolution
    • source_scope_policy
  • compact trace inspection should normally start from:
    • trace_id
    • session_id
    • answer_state
    • reference_resolution
    • source_scope_policy
    • issue_codes
  • do not switch to direct Python helpers such as prepare_ask_turn(), complete_ask_turn(), or trace_answer_file(...) as a substitute for the supported path
• Example retrieve / trace binding:

export DOCMASON_CONVERSATION_ID="<conversation_id>"
export DOCMASON_TURN_ID="<turn_id>"
export DOCMASON_RUN_ID="<run_id>"
export DOCMASON_ENTRY_WORKFLOW_ID="ask"
export DOCMASON_INNER_WORKFLOW_ID="<inner_workflow_id>"
export DOCMASON_FRONT_DOOR_STATE="canonical-ask"

./.venv/bin/python -m docmason retrieve "<query>" --json --compact
./.venv/bin/python -m docmason trace --answer-file "<answer_file_path>" --json --compact

• progress request envelope:

{
  "action": "progress",
  "conversation_id": "<conversation_id>",
  "turn_id": "<turn_id>",
  "completion_status": "covered | blocked",
  "hybrid_refresh_summary": { "...": "..." }
}

• A material professional judgment may instead persist a decision gate:

{
  "action": "progress",
  "conversation_id": "<conversation_id>",
  "turn_id": "<turn_id>",
  "decision_frontier": {
    "class": "judgment-authority-gap | high-cost-expression-choice",
    "question": "<material decision question>",
    "why_user_is_required": "<why evidence and reasoning cannot decide it>",
    "evidence_boundary": "<what evidence establishes and cannot decide>",
    "options": [
      {
        "id": "<stable option id>",
        "label": "<short label>",
        "impact": "<real downstream consequence>",
        "recommended": true
      },
      {
        "id": "<stable option id>",
        "label": "<short label>",
        "impact": "<real downstream consequence>",
        "recommended": false
      }
    ],
    "affected_outputs": ["<specific model or artifact scope>"],
    "invalidates": []
  }
}

• A legal gate has two or three real options, explains their downstream impact, marks exactly one current recommendation, and names the affected output scope. Do not persist a vague or non-material question.

• After progress returns awaiting-user-decision, present the same gate through the host's native Plan or structured-input UI, without a timeout or default, and wait. If no such UI is available, ask the one material question concisely in-band.

• The user's answer opens a new linked turn with continuation_type=decision-resolution, the exact gate_id as resolves_gate_id, and either one legal option_id or a non-empty free_form decision. Never settle the old turn in place or reinterpret an unrelated message as consent.

• completion_status is optional when the caller is only re-entering a waiting-shared-job turn to let the hidden wrapper reconcile deterministic repo-owned shared-job truth.

• supply completion_status only when the host is actively settling a still-unsettled governed multimodal refresh.

• when the current-turn hybrid_refresh_work.json lists render or focus-render assets and the host can inspect images, inspect the relevant assets lightly and include render_inspection_used plus inspected_render_assets in hybrid_refresh_summary.

• when a turn is paused in waiting-shared-job, re-enter through hidden open reuse, hidden progress, or hidden finalize; do not grep runtime/control_plane/ or shared-job files manually.

• finalize request envelope:

{
  "action": "finalize",
  "conversation_id": "<conversation_id>",
  "turn_id": "<turn_id>",
  "answer_text": "<exact final business answer>",
  "answer_file_path": "<answer_file_path>",
  "response_excerpt": "<short excerpt>",
  "session_ids": ["<selected_session_id>"],
  "trace_ids": ["<selected_trace_id>"],
  "workflow_outcome": {
    "support_basis": "kb-grounded | mixed | external-source-verified | model-knowledge | governed-boundary",
    "session_ids": ["<selected_session_id>"],
    "trace_ids": ["<selected_trace_id>"],
    "bundle_paths": ["<composition bundle path>"]
  }
}

• answer_text is the preferred terminal input. The wrapper writes it atomically to the canonical answer path, binds the exact digest, reuses only a digest-matching trace, and runs one exact trace when necessary. The successful response keeps answer_text clean and returns one separate user_status_line; internal IDs and support state remain in governance_detail. When the exact final answer is already present at answer_file_path, callers may omit answer_text and use the file-based handshake below.

• session_ids and trace_ids are optional advanced-caller fields. Omit them when the turn has exactly one ask-owned retrieve session and one final trace candidate. Supply them only when the caller has already selected the canonical pair among multiple ask-owned candidates.

• workflow_outcome is the preferred finalize-time handoff for workflow-owned facts. Supply it when the inner workflow already knows the correct support_basis, selected session_ids / trace_ids, support-manifest linkage, bundle linkage, or bounded degradation metadata. Older callers may keep using the compatible top-level finalize fields.

• Legal closure handshake for one canonical ask turn:

./.venv/bin/python -m docmason trace --answer-file "<answer_file_path>" --json --compact

cat <<'JSON' | ./.venv/bin/python -m docmason _ask
{
  "action": "finalize",
  "conversation_id": "<conversation_id>",
  "turn_id": "<turn_id>",
  "answer_file_path": "<answer_file_path>",
  "response_excerpt": "<short excerpt>"
}
JSON

• Completion rule:
  • only completed or boundary permits a final business reply to the user
  • execute, awaiting-confirmation, awaiting-user-decision, waiting-shared-job, and blocked do not

Required Capabilities

• local file access
• shell or command execution
• ability to inspect structured JSON output
• ability to inspect rendered images when the answer boundary requires it

If the environment cannot satisfy those capabilities, stop and explain the blocker instead of improvising.