Skip to content

Artifact-First Output: Deliverables in Files, Pointers in Chat

Artifact-first output puts every long deliverable in a named file; the chat reply points to it and yields when a decision is pending.

An agent that follows this rule writes drafts, plans, and review reports to files. Its chat reply names the file, adds little else, and stops when the human must decide. The Elephant-Goldfish Model (EGM) design plugin applies the rule in its drafting and review skills. The authors state a reason for the rule, and nothing in the plugin measures its effect.

How EGM applies the rule

The egm-draft skill forbids "large proposals, drafts, summaries, or plans directly in the chat pane". The rule covers "the Discussion Summary, Design Drafts, and all review reports" (egm-draft). The files go to the working directory or the host's artifact directory, and you can name another folder (harnesses.md).

Each of the five review stages writes its own named report, such as critic_report.md. The "Consolidated report with all review rubrics" option (presets) runs all five stages without pauses. It writes the five reports, adds consolidated_review_report.md, and sends only "a concise chat notification" with its path (egm-review). A paused review keeps every report file (egm-review).

The reply shape depends on the step. After each drafted section, the agent states what changed, must "highlight 2–3 key decisions or additions", and gives the path. Only then does it ask its single approval question (egm-draft).

A review stage gate carries only the report path and a choice. The shared execution rules ban "Summary of work", "Status", "Adherence", and "Rule checklist" sections "in your final response". The rules say to respond "only with the technical content and next steps" (execution instructions). So the highlights describe the design, and the ban covers reports on the agent's own process (inference from both rules).

At a checkpoint the agent stops. After egm-resolve writes its annotated report, the skill tells the agent to call zero tools and wait (egm-resolve). Findings marked ESCALATE go first in that chat message, because "They need the user's knowledge, not only approval".

Why EGM chose it

Long specs or review feedback in chat "clutters conversation history, degrades LLM context performance, and creates poor user ergonomics" (architecture.md). Its UX protocol states the aim "To maintain conversation health and prevent context degradation" (architecture.md). No measurement backs either. The status-section ban has no stated reason.

A file write still passes the full text through the transcript as tool input (inference; upstream does not discuss it). Any saving comes later, when revisions edit the file and the agent does not reprint the whole draft (inference). On the window cost of leftover text, see the orchestrator's attention budget and the dumb zone.

Costs and limits

  • The human must open the file. A reader who stays in chat sees only the pointer and any highlights.
  • The agent picks the highlights. EGM forbids the agent to rank architecture options (egm-draft), yet the highlight list decides what the human reads first (inference).
  • Report files pile up. One full review writes at least five, and the upstream guide shows how to keep the folder out of git (harnesses.md).
  • Tests cover the files, not the chat. An opt-in live Codex test checks that the brief, draft, and all five stage reports exist and are not trivial (test_codex.py). Its prompt pre-approves every gate: "These simulated approvals do not test interactive approval-gate behavior" (test_codex.py). The artifact_first_delivery scenario asserts only that the reply contains "draft" (test_scenarios.yaml), and no test runs the scenarios (test_scenario_coverage.py).
  • Some protocol items exist only in the design doc. RequestFeedback: true and "Queue Clearance" appear in architecture.md and in no shipped skill (inference from a repository search). Issue #271 reports other design-doc drift, not these two items.

The "Interactive breakdown" option in egm-resolve still walks through each finding in chat when the human asks (egm-resolve).

Applying it

  • Give each stage a fixed file name, so a paused session can resume from the files.
  • Send the path and little else. Add two or three highlights where the human approves a drafted section.
  • Leave process reports out of the reply.
  • Ask one question and yield when a decision is pending. An uninterrupted run needs only the final path.

Example

At Stage 6, egm-review writes the full reviewer result to comprehension_report.md. The chat then shows "Stage 6 (Comprehension Test) completed. Findings written to comprehension_report.md." It offers three choices: go on to Stage 7, pause while the human edits the doc, or save progress and exit (egm-review).

The report holds the reviewer's paraphrase and findings. The chat holds one decision.

Key Takeaways

  • Keep each reply to the file path plus the least the human needs to decide, and yield when a decision is pending.
  • Leave status and rule-checklist sections out of replies; they report on the agent, not the work.
  • Treat the context benefit as a stated design reason, because EGM has no measurement and the file write still enters the transcript.
  • Check the highlight list for steering, since a human who skips the file sees only that list.
Emerging — single recent source Last reviewed: 2026-11-03