THE GITHTML FIELD GUIDE
Ask an AI coding agent for a single-file HTML report you can read anywhere
Tell the agent exactly what the report is for, which files and revision it may read, and the output contract: one .html file, inline CSS, no external scripts or fonts, a viewport tag, and claims linked to file paths. Then check the result yourself before committing it. The format requirements make it portable; the evidence requirements make it trustworthy.
Why specify the format
Coding agents will happily produce HTML, but left alone they often reach for a CDN framework, a web font, a chart library, or a layout tuned for a wide monitor. Those choices look fine in the agent's preview and fail when the file is opened offline, in a reader with scripts disabled, or on a phone. Asking up front costs one paragraph and saves a round of fixes.
Equally important is scope. A report that says the service retries three times is only useful if the reader can see where that came from. Ask for paths and line references next to claims so a reviewer can verify them.
A reusable prompt
Adapt the bracketed parts and keep the output rules. The read-only instruction matters for analysis tasks: you want a description of the current code, not a report mixed with unrequested edits.
Write a report explaining [how request authentication works in services/api]
for [a new on-call engineer]. Read only; do not modify source files.
Output contract:
- One file: docs/reports/[auth-flow].html, complete document with <!doctype html>.
- <meta name="viewport" content="width=device-width, initial-scale=1">.
- All CSS in a single <style> element. System font stack. No external
scripts, stylesheets, fonts, or images.
- Diagrams as inline SVG or ordered lists, each with a text explanation.
- Wide tables and code inside containers with overflow-x: auto.
- Start with: title, one-paragraph summary, revision (git commit), date.
- After each factual claim, cite the file path and line range.
- Mark anything inferred rather than read as "Inferred:".
- End with open questions and what you did not inspect.Acceptance checks before committing
Treat the output as a draft from a fast colleague. The format checks take a minute; the evidence checks take longer and are where the value is.
- Search the file for http and src= to confirm there are no external dependencies.
- Open it with JavaScript disabled and the network off; every section should still read.
- Narrow the browser to phone width and check tables, code, and diagrams for overflow.
- Spot-check at least three cited file paths and line ranges against the stated commit.
- Read every Inferred: line and either verify it or keep it labeled.
- Confirm the report contains no secrets, tokens, or customer data copied from logs.
Commit and read it
Commit the report in a predictable folder such as docs/reports with a descriptive filename. In gitHtml it then appears alongside the repository's other HTML documents and renders on iPhone or iPad with scripts and remote resources off by default, which is exactly the environment the output contract was designed for. When the code changes, regenerate the report from the new commit instead of editing old claims by hand.
Sources and further reading
AI-assisted writing with source-linked guidance and illustrative examples. Read our editorial approach or report a correction.