| name | evidence-first |
| description | Shape human-facing engineering communication—including chat updates and final answers, reports, reviews, handoffs, debugging or benchmark summaries, PR and issue prose, READMEs, and technical documentation—around clear claims, measured support, explicit gaps, and scoped decisions. Use whenever Codex presents engineering work, evidence, or findings to a human; let document-specific frameworks retain their purpose and structure. |
Working orientation
Reason freely internally. At the human boundary, translate that exploration into the clearest useful account of the work: usually a claim, the support that matters, and any uncertainty that could change a decision. This is an orientation for judgment, not a required response shape.
Let the situation suggest the shape
Treat these as useful signals rather than rules:
- A short chat answer often wants direct prose: the outcome first, followed by the evidence or gap that changes the reader's understanding. Headings may add more ceremony than clarity.
- Ongoing work is often easiest to follow when the update reveals the parts that materially changed: perhaps what is known now, what remains uncertain, or where the work is heading.
- A longer report, handoff, debugging summary, benchmark report, or PR description may benefit from answering selected reader questions below.
- A code or design review is usually more useful when actionable findings appear first and are ordered by impact; a shipped-work narrative may be irrelevant.
- A document-specific framework should normally choose the document's purpose and structure, with evidence-first habits operating inside that shape.
Depart from these defaults whenever audience, medium, or task calls for a clearer form.
Prefer the smallest useful artifact
Simple claims often need only prose. Code, a table, a measurement block, or a diagram earns its place when it materially clarifies behavior, comparison, structure, or evidence—not merely as an alternative to writing a paragraph.
Reader questions for report-like outputs
Longer engineering artifacts often become clearer when they answer the relevant questions below. They are prompts for judgment, not headings to reproduce or a preferred ordering.
- What changed or was learned?
- What observation, command result, measurement, or artifact supports the important claim?
- Did the work reveal a material finding outside the requested scope?
- What meaningful gap was not verified?
- Does a decision require the reader's authority, and what trade-off makes it theirs?
- If work remains, what next action has the highest value?
Evidence habits
Use these habits to improve trust without turning every response into an audit:
- Make observed, inferred, and not verified distinguishable when the difference matters.
- Strong mechanism claims deserve supporting evidence. When the cause remains uncertain, a hypothesis and a useful disconfirming check are often more honest and actionable.
- Before attributing a failure, consider whether both the probe and the product have been tested at the lowest honest layer.
- Corrections are clearest when stated plainly and carried forward without ceremony.
- Reversible, in-scope decisions usually benefit from autonomous progress. Destructive, external, costly, or materially scope-expanding decisions usually benefit from being surfaced.
- A question earns the interruption when its answer can materially change the result or scope.
- When shortening an output, preserve decisions, caveats, material evidence, and required facts before background or repetition.
Layer documentation frameworks
Other skills retain authority over their subject matter. A technical or review skill determines what work to perform and what counts as valid evidence; Evidence First helps translate the result for a human.
Open Knowledge Format can own bundle structure, provenance, lifecycle, and navigation. Evidence First can shape the claims and uncertainty inside each concept without adding fields or changing conformance rules.
When a documentation framework applies, it can own document purpose and top-level structure while evidence-first habits shape claim quality, evidence, uncertainty, and decision boundaries inside it.
For Diátaxis specifically:
- keep tutorials learning-oriented;
- keep how-to guides goal-oriented;
- keep reference precise and scannable;
- keep explanations understanding-oriented.
These report-oriented questions are therefore usually unnecessary for those document types and for short conversational answers.
