---
name: grounded-answer
description: Answer a user question through DocMason's canonical grounded workflow using retrieval, provenance tracing, render escalation, and a final answer-state check.
---

# Grounded Answer

Use this skill when the task is to answer a question from the published DocMason knowledge base rather than only retrieve evidence.

This is the inner specialist answer workflow behind the user-facing `ask` entry surface.
Ordinary users should not need to name this workflow explicitly before asking business questions.

## Front-Door Precondition

- `grounded-answer` is not a free-standing ordinary front door.
- Start only from canonical ask turn metadata and canonical ask runtime ownership.
- Start only after canonical `ask` has already handed the live turn here with `status = execute` and `inner_workflow_id = grounded-answer`.
- If the current turn is missing that ask-owned handoff, stop and route back to `ask`.

## Required Capabilities

- local file access
- shell or command execution
- ability to inspect structured JSON output
- ability to inspect rendered images when the cited evidence requires visual confirmation

If the agent cannot inspect required rendered evidence, stop and explain that the environment is not capable enough for grounded answering.

## Procedure

1. Start from canonical ask turn metadata instead of assuming every direct answer is purely KB-grounded.
   - honor the ask-owned `work_brief`, resolved decisions, accepted scopes, and affected-output
     boundary; use them to preserve the intended medium and critical distinctions without
     reopening decisions this workflow does not own
   - treat `answer_state` as the top-level four-state answer contract
   - choose an explicit `support_basis` for the overall answer:
     - `kb-grounded`
     - `external-source-verified`
     - `model-knowledge`
     - `mixed`
   - honor ask-provided `reference_resolution`, `source_scope_policy`, `evidence_requirements`, and `support_contract`; when `evidence_requirements` is present, treat it as the canonical odd-question inspection contract before widening scope or changing evidence basis
   - write a short support ledger before drafting:
     - which source boundary must survive
     - which comparison sources must both survive
     - which published evidence channels are required
     - whether this turn still has the one allowed contract-repair chance
2. Normalize the user question and decompose it only when that improves grounded retrieval.
3. Run `docmason retrieve "<query>" --json --compact` for the initial question or sub-question when KB evidence is part of the answer path.
   - if you truly need the full nested retrieve payload, redirect full `--json` to a local file and inspect it selectively instead of streaming it into the live chat context
   - treat compact retrieve as the stable host-facing projection; inspect `results`, `reference_resolution`, `source_scope_policy`, and `recommended_hybrid_targets` before reaching for nested JSON
   - do not build alternate compact schemas with ad hoc `jq` assumptions such as `.matches`
   - prefer published affordance sidecars and already-published evidence channels over ad hoc source inspection
   - inspect `reference_resolution` first when the user has named a document or locator in user-native terms
   - keep DocMason workspace commands sequential inside the same live answer path; do not overlap `retrieve`, `trace`, `sync`, `status`, or `validate-kb` while a lease-owning step is still running
4. Inspect the strongest evidence bundles, matched units, graph expansions, render references, and published-evidence sufficiency judgment.
   - when `reference_resolution.status` is `exact`, preserve that narrowing and do not let neighboring documents silently dilute it
   - when `reference_resolution.status` is `approximate` but `unit_match_status` is `exact`, preserve the approximate notice but still treat the resolved source narrowing as intentional
   - when `reference_resolution.status` is `approximate` or `unresolved`, keep the inline notice and answer wording honest about that boundary
    - when the question is artifact-sensitive, inspect compact retrieval fields first:
       - `matched_artifact_ids`
       - `matched_unit_ids`
       - `matched_overlay_unit_ids`
       - `focus_render_assets`
       - `recommended_hybrid_targets`
       - score details such as `structure_context_bonus`, `semantic_overlay_bonus`, and `compare_coverage_bonus`
    - when the answer boundary truly depends on exact artifact metadata such as `section_path`, `caption_text`, `continuation_group_ids`, `procedure_hints`, or `semantic_labels`, inspect a file-first full retrieve capture or the published artifact sidecars rather than pasting the nested payload into chat
   - treat those published payloads as an ordered evidence path: first decide whether retrieved text, structure, notes, or media already settle the claim, then inspect cited `focus_render_assets`, render refs, or page spans when visual confirmation would materially change the answer, and only then escalate
   - when published sufficiency fails because of hard-artifact semantic gaps, the grounded-answer path must enter the governed ask-time multimodal refresh before any raw source inspection
     - use `recommended_hybrid_targets` as the only legal query-aware narrowing entrypoint
     - if the turn becomes a waiter on that governed refresh, keep the same turn paused and reuse the shared result
     - once the governed refresh picks a source, complete that source's current hybrid candidates, inspect listed render or focus-render assets when present and answer-relevant, reretrieve, and retrace before treating the ask as ready to answer
     - record lightweight settlement audit fields such as `render_inspection_used` and `inspected_render_assets` when the work packet exposes visual assets
     - after one `covered` refresh and post-refresh retrieve/trace, close honestly with the remaining support boundary instead of starting a second same-turn refresh
     - if the governed refresh settles `blocked`, close the turn as `abstained + governed-boundary`
5. Run provenance tracing for the strongest support when you need corroboration, contradiction checks, or answer-state clarification:
   - `docmason trace --source-id <source_id> --json --compact`
   - `docmason trace --answer-file <path> --json --compact`
   - `docmason trace --session-id <session_id> --json --compact`
   - if you truly need nested segment support objects, redirect full `--json` to a local file and inspect it selectively instead of loading the full raw trace payload into the live chat context
   - treat compact trace as the stable host-facing projection; inspect `answer_state`, `reference_resolution`, `source_scope_policy`, `issue_codes`, and `recommended_hybrid_targets` before reaching for nested JSON
   - when the same live turn creates more than one ask-owned retrieve session or more than one plausible final trace candidate, keep an explicit artifact ledger while you work:
     - preserve the selected ask-owned `session_ids` that support the final answer
     - preserve the selected `trace_ids` that bind the final answer-file version
     - return those selected IDs to the main agent for finalize-time use instead of leaving commit-time disambiguation to `complete_ask_turn()`
   - if the turn produced only one ask-owned retrieve session and one final trace, ordinary automatic hydration remains sufficient
6. Inspect renders when:
   - the strongest support uses low-confidence extracted text
   - a cited unit has little or no text but does have rendered evidence
   - layout, tables, diagrams, screenshots, or visual style are part of the answer boundary
   - the odd-question plan explicitly prefers `render` or `media`
   - artifact supports expose `render_page_span`, `bbox`, or `normalized_bbox` that materially narrow what must be checked
   - artifact or segment supports expose `focus_render_assets`, which should be preferred over full-page renders when present
   - do not treat every multimodal source as a reason to reopen the raw file; render inspection is for questions whose answer boundary actually depends on visual semantics or a published render-only gap
7. Draft the canonical answer file under `runtime/answers/` when conversation context exists.
   - if you need auxiliary drafts or exported scratch artifacts and the user did not specify a path, place them under `runtime/agent-work/`
8. When the answer is externally verified, persist the lightweight external support manifest before or alongside the final trace so the combined support contract stays machine-readable.
9. Run `docmason trace --answer-file <path> --json --compact` as the final grounding check.
    - when the answer depends on artifact-level support, inspect compact trace fields first:
       - `supporting_artifact_ids`
       - segment `supporting_artifact_ids`
       - segment `supporting_overlay_unit_ids`
       - segment support-lane counts and compact support counts
    - when you genuinely need nested `artifact_supports`, `semantic_supports`, render refs, page spans, or region boxes, inspect a file-first full trace capture or the published artifact surfaces rather than streaming the nested trace payload into chat
   - hand the same answer-file path, plus any selected `session_ids` / `trace_ids`, back for hidden `finalize`; prefer the structured `workflow_outcome` handoff when the workflow already knows the correct `support_basis`, selected IDs, or other finalize-owned facts
   - if finalize returns `status = execute` together with a repairable `support_fulfillment`, do one contract-aware rewrite and retrace on the same turn, then finalize once more
   - if finalize returns `status = execute` together with `admissibility_repair`, use its issue codes and suggested action to rewrite the same answer file, rerun trace, and finalize once more
   - do not render terminal closure metadata yourself; return the exact business answer and
     workflow-owned support facts to `ask`, which alone decides whether a separate status line or
     boundary explanation is user-visible
10. Emit one of these final answer states:
   - `grounded`
   - `partially-grounded`
   - `unresolved`
   - `abstained`
11. Return the final answer, final `answer_state`, overall `support_basis`, support boundary, and next steps to the main agent.

## Escalation Rules

- If the final answer trace returns `partially-grounded` or `unresolved`, do not relabel the result as `grounded`.
- If the answer is externally verified or intentionally based on stable model knowledge, do not relabel it as a degraded product failure solely because the final answer is not KB-grounded.
- If the final answer trace still requires render inspection, inspect the cited renders before issuing a confident answer.
- If the evidence is contradictory, ambiguous, or insufficient, qualify the answer or abstain.
- If source-reference resolution only succeeded approximately, do not phrase the answer as though the cited document or locator was matched exactly.
- If the answer is comparative, do not finalize it from a support set dominated by one source when the trace or retrieval payload still shows weak comparative coverage.
- Treat trace `grounding_reason_codes` and coverage ratios as diagnostics for repair and explanation. They do not override the final `answer_state`.
- Do not treat retrieval alone as a complete grounded-answer workflow.
- If published KB artifacts already satisfy the required evidence channels, do not rerender source files or rummage through `original_doc/` as a first reflex.

## Completion Signal

- The workflow is complete when the main agent has a final answer text, a final answer state, and an explicit support or uncertainty boundary grounded in retrieval and trace results.

## Notes

- This is an inner agent-facing workflow behind `ask`. It is not a new public `docmason answer` command.
- New runtime artifacts use the same four-state `answer_state` contract:
  - `grounded`
  - `partially-grounded`
  - `unresolved`
  - `abstained`
- `support_basis` remains an explicit orthogonal field. Interpret `answer_state` relative to that declared support basis.
- When a narrower KB-specific grounding view is needed, use trace grounding summaries, segment grounding statuses, and `kb_answer_state` rather than overloading the top-level answer contract.