Grounded File Qa

Grounded File QA

Overview

Use this skill for source-grounded reading workflows. The job is not just "summarize this once", but "read these files now and keep answering later questions from them."

Workflow

1. Identify the source bundle.

• Collect the exact local file paths the user provided.
• Start reading immediately unless the goal changes the reading strategy in a material way.
• Treat the provided files as the primary source of truth unless the user explicitly asks for outside knowledge.

1. Build a scratch bundle when the task is larger than one quick answer.

• Prefer a scratch folder such as /tmp/grounded-file-qa//.
• Run scripts/ingest_documents.sh ... to extract PDF text and normalize text-like files.
• Read manifest.tsv first to see which files were extracted cleanly and which need fallback handling.
• Read source_map.md for a fast human-readable overview and page_manifest.tsv when page-level anchors matter.
• If the user only gave one short text file, skip the scratch folder and read it directly.

1. Read in passes.

• First pass: map each file's purpose, structure, and likely relevant sections.
• Second pass: extract the evidence needed for the current question.
• For PDFs, prefer the page shards under pages//pNNN.txt so answers can cite filename p.N.
• For multiple files, record agreements, conflicts, and gaps instead of merging everything blindly.

1. Maintain a compact evidence sheet for later turns.

• Prefer a markdown note in the scratch dir such as evidence.md.
• Use [references/evidence-sheet-template.md](references/evidence-sheet-template.md) when the task has multiple files or many follow-up questions.
• Keep only high-signal items: per-file summary, glossary, timeline, formulas, unresolved ambiguities, and page anchors.
• Update the sheet instead of re-reading everything from zero when the conversation continues.
• If the user wants study or interview prep, also maintain question_bank.md with likely follow-up questions.

1. Answer with grounded claims.

• Cite the source file for non-obvious claims.
• Add page anchors for PDFs and section headings or line spans for text files when practical.
• Separate direct evidence from your inference.
• If a question cannot be answered from the files, say that before adding outside knowledge.

PDF Handling

• Prefer pdftotext -layout through the ingest script for readable extraction.
• Prefer pdfinfo page counts plus the generated pages/ directory when page-level lookup will matter later.
• If extraction is noisy but usable, answer cautiously and cite short anchors.
• If the PDF is image-only or badly scanned, say OCR is needed and do not pretend the text is reliable.
• Ignore headers, footers, page numbers, watermarks, and repeated slide chrome unless they matter.

Multi-file Patterns

• For comparison requests, build a table with columns such as source, claim, evidence, and confidence.
• For study or report files, keep a glossary of terms, symbols, acronyms, and formulas.
• For policy or requirement sets, track conflicts and the latest controlling source if dates or versions are present.
• For code plus PDF/context mixes, treat executable behavior and source files as first-party evidence and use the PDF as explanatory context.

Extra Capabilities

Use the same source bundle to optionally provide:

• a 5-10 line executive summary
• a glossary or concept map
• a question bank for revision or interview prep
• a comparison matrix across files
• a list of contradictions or open questions
• a reusable brief file for later turns
• a per-page lookup path for later precise quoting or citation

Reliability Rules

• Do not claim to have read a file you have not opened or extracted.
• Do not turn weak OCR or garbled extraction into confident prose.
• Prefer "the file suggests" over certainty when evidence is partial.
• Keep quotes short and only when they materially help.
• If later answers depend on a cached note, refresh the original source before making a high-stakes claim.

Fast Prompt Patterns

• Use $grounded-file-qa to read these PDFs first, then answer my later questions from them.
• Use $grounded-file-qa to compare these two papers and keep a running evidence note.
• Use $grounded-file-qa to ingest this folder of PDFs and build a glossary plus summary for follow-up Q&A.
• Use $grounded-file-qa to read the provided files and answer only from those sources unless I ask otherwise.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: lyh843
• Source: lyh843/AgentSkills
• License: MIT

Install and usage instructions live in the source repository linked above.