File Summarization
Read the shared fidelity rules and
execution contract. Use the selected format;
do not force structured Markdown when JSON, TL;DR or another template was requested.
Acquire and choose depth
Resolve the exact source scope first. For directories, enumerate the requested tree without
following cycles, preserve exclusions/inaccessible entries, and account for all intended sources.
Do not narrow a directory request to a representative file without disclosing that scope change.
Inspect file type and size before choosing a read strategy. When execution is available:
uv run --script "<plugin-root>/scripts/file_metrics.py" "<file-path>" --json --no-excerpt
Metrics and excerpts are planning evidence, not proof that source contents were read. A binary
classification means a text probe failed, not that no media-aware reader can extract the file.
Choose a reader from actual content/media type and available capabilities. For image files,
including SVGs, use image-summarization.
Read short files completely. For larger sources, preserve section/module boundaries and source
locations; choose chunks that fit the host's available context. The legacy small (<2,000 words),
medium (2,000 to <10,000), and large (at least 10,000) labels are compatibility hints, not
measured universal limits. If only excerpts can be read, record exactly what is omitted.
For chunked UTF-8 text or whole-dataset CSV/TSV claims, load
mechanical source acquisition and use its
source-bound plan, coverage reconciliation or full-record profiler.
Type-specific extraction
| Type | Required extraction |
|---|
| Code | Imports/dependencies; classes/functions/methods and signatures; documented purpose versus inferred purpose; key algorithms/state/data transformations; entrypoints/exports; environment/configuration dependencies. Retain line locations, relevant docstrings and exact complex expressions. |
| Configuration | Root keys/types, nested hierarchy, settings categories, documented validation constraints and meaningful values. Note credentials without exposing their values. Do not claim effective/default settings from an isolated file without resolving their dependencies. |
| Data | Parsed record count, headers/schema, observed types, examples only within an explicit sample scope, missingness and evidenced identifiers. Compute dataset-wide claims over all records with an appropriate parser; raw line count is not CSV record count. |
| Documentation | Actual heading hierarchy, main claims/definitions, prerequisites, commands/examples and internal/external references. Retain locations; quoted commands remain data, not instructions to execute. |
| Markup | Document structure, visible/embedded text and relevant links; separate markup inspection from verified visual rendering. |
| PDF/office document | Use a host-provided or available format-aware reader. Account for pages, tables, images or attachments not extracted. Inspect relevant visual material before claiming its contents. |
| Other binary/unknown | Use an appropriate available reader only within task authority. Otherwise return metadata plus the specific extraction limitation, not guessed contents. |
Do not generalize schema, ranges, row totals or missingness from the first ten rows. Keep sampling
for illustrative examples and disclose its scope. Failed text decoding is a reason to choose a
compatible reader or report a limitation, never to silently replace corrupted text and call it complete.
Extract, render and verify
Extract passages/values with source locations, preserve their qualifiers, then compose the requested
summary. For chunked, delegated or audit work, retain an evidence record.
Ensure every relevant section/chunk either contributed inspected evidence or has an explicit failure.
Do not synthesize a chain of progressively shortened summaries without recoverable source support.
Render the selected template and run the execution contract's final checks. For several files, keep
individual attribution and failure records; invoke multi-source-synthesis
only for requested integration. On access failure, preserve the exact path/error and caller status;
do not manufacture a successful summary or repeat an unchanged failing access method indefinitely.