retrieval-workflow

Retrieval Workflow

Use this skill when the task is to retrieve the strongest published evidence bundles for a question or topic.

This is an evidence-focused workflow. Use it directly for explicit evidence requests, or let ask route here automatically.

Direct public retrieve remains a legal operator evidence surface. It does not substitute for canonical ask when the user is really asking for ordinary answer completion.

Required Capabilities

• local file access
• shell or command execution
• ability to inspect structured JSON output

If the agent cannot run local commands or inspect the published file-only knowledge base, stop and explain that reliable retrieval is not possible.

Procedure

1. Confirm that the published knowledge base exists with docmason status --json when needed.
2. Run docmason retrieve "<query>" --json --compact for host-visible inspection.
   • when full nested unit or artifact detail is genuinely required, rerun full --json to a local file and inspect it selectively instead of streaming the raw payload into the live chat context
   • keep user-native source references inside the freeform query rather than inventing internal source IDs when the user already knows a file name, path, page, slide, sheet, or heading
   • keep DocMason workspace commands sequential inside the same workspace session; do not overlap retrieve, trace, sync, status, or validate-kb while a lease-owning command is still active
3. Inspect:
   • reference_resolution
   • ranked source bundles
   • compact bundle fields such as matched_unit_ids, matched_artifact_ids, matched_overlay_unit_ids, and collection counts
   • artifact-aware score details such as structure_context_bonus, semantic_overlay_bonus, and compare_coverage_bonus
   • when exact artifact fields such as section_path, caption_text, continuation_group_ids, procedure_hints, or semantic_labels matter, inspect a file-first full JSON capture or the published artifact sidecars rather than dumping the full raw payload into chat
   • focus_render_assets when present
   • recommended_hybrid_targets when the published artifact plan still reports a hard-artifact semantic gap
   • graph-expansion summary fields
   • render references when relevant
   • any published-evidence plan fields such as preferred channels, matched channels, and whether published artifacts already look sufficient
   • for image-only or scanned PDF questions, check whether page-image artifacts or unit semantic_gap_hints are present before assuming the KB has enough semantics already
4. Narrow or widen the query by:
   • --document-type
   • --source-id
   • --top
   • --graph-hops
   • when reference_resolution.status is exact, expect the source filter and any exact unit targeting to have already narrowed the candidate set decisively
   • when reference_resolution.status is approximate but unit_match_status is exact, expect retrieval to narrow to the resolved source while still preserving the approximate notice
   • when reference_resolution.status is approximate or unresolved, preserve the notice boundary rather than pretending the narrowing was exact
   • for artifact-hint or compare-style questions, prefer reformulations that keep the named table, chart, diagram, caption, or compared objects explicit
5. If the strongest results are weak or empty, say so explicitly instead of pretending the query succeeded.
6. For compare-style retrieval, verify that more than one source survives the top support set before calling the bundle comparison-ready.
7. Open the cited source, unit, artifact, and render assets before claiming confidence on difficult evidence judgments.
8. When the task is moving toward a final answer or deliverable draft, return retrieval bundles to the main agent for provenance tracing, grounded-answer, or grounded-composition.
9. If you need to export a scratch evidence note and the user did not specify a destination, place it under runtime/agent-work/.