Document Grounding Agent

The Document Grounding Agent (atelier-document-grounding) is an internal subagent used by Atelier skills such as Revise, Explore, and Verify.

Do not invoke it directly. Atelier calls it when a skill needs source-backed evidence from markdown plans, specs, ADRs, notes, or other documents.

When it is used

• A revision comment refers to another markdown document or section
• A walkthrough needs grounded passages from design docs or project notes
• Verification needs to compare implementation evidence against written criteria
• A skill needs durable links to document passages that remain stable as nearby lines change

Input

The agent receives a batched request with:

• file — Markdown file to search.
• link_base — Optional output directory used to make generated links relative to the report or walkthrough.
• queries — One or more query IDs with natural-language descriptions of the document evidence needed.

What it does

1. Extracts terms — Pulls out key nouns, domain terms, synonyms, and related phrases from each query.
2. Searches the target document — Looks for matching headings, sections, lists, definitions, and structured content.
3. Captures complete passages — Preserves paragraph boundaries and includes the section heading when useful.
4. Generates deep links — Uses Atelier’s text-fragment helper to produce ready-to-paste markdown links.
5. Explains relevance — Groups passages by query ID and records why each excerpt matters.

Output

The parent skill receives structured markdown grouped by query:

• Query — The query ID supplied by the parent skill.
• File — The searched markdown file.
• Passages — Relevant excerpts with a text-fragment Location, a relevance sentence, and concise markdown content.
• Reasoning — One to three sentences explaining the search result.

If no passage directly answers a query, the agent returns an empty result with an explanation of what it searched.

Quality standards

The agent prefers complete sections, precise matches, and concise excerpts. It excludes boilerplate, passing mentions, duplicate passages, and anything that would require inventing unsupported context.