feat(agent): preamble before multi-step tasks for a readable chat

[Vasanthdev2004]

Problem

Zero jumps silently into tool calls — no upfront explanation of what it's about to do, so the chat reads like opaque machine output. A reference agent on the same task preambles ("I'll build this with a warm editorial direction… let me write the three files"), which makes the work easy to follow.

Root cause

internal/agent/system_prompt.md told the model: "Use tools to act, not to narrate. Do not announce each call; just do the work and explain the outcome." That correctly stops per-call spam, but it also suppressed the useful upfront approach statement. (The TUI already commits streamed pre-tool prose as an assistant row, so the render path was ready — the model just produced none.)

Fix

One-file prompt change: lead a multi-step task with a 1-2 sentence plain-language preamble, while keeping the per-call anti-spam:

Lead a multi-step task with a one- or two-sentence plain-language preamble on your approach, so the user can follow what you're about to do. After that, use tools to act, not to narrate: don't announce each individual call; just do the work and explain outcomes as you go.

Notes

• Scoped to multi-step tasks, so trivial Q&A doesn't grow a preamble.
• The "don't announce each individual call" clause keeps weaker models from over-narrating every call.
• Prompt-only; build + ./internal/agent/... tests green. Behavior is a manual/eval check (not deterministically unit-testable); easiest of the chat-clarity series to tune or revert.

Part 2 of 3 in the chat-clarity series (with #316). The third — write/edit diff preview — is a separate PR.

Summary by CodeRabbit

• Documentation
  • Updated guidance for the AI assistant to provide a brief plain-language preamble before starting multi-step tasks.
  • Improved how progress and outcomes are communicated during longer interactions.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 2dcd67f0-f60b-477d-a6ee-a39b3bd8b977

📥 Commits

Reviewing files that changed from the base of the PR and between 46c44a8 and a4a7ccd.

📒 Files selected for processing (1)

• internal/agent/system_prompt.md

---

Walkthrough

The system prompt’s tool-use guidance now asks for a brief plain-language preamble before multi-step work, then directs the agent to use tools without narrating each call and to explain outcomes as it proceeds.

Changes

Tool-use prompt update

Layer / File(s)	Summary
Tool-use instruction wording internal/agent/system_prompt.md	The prompt text replaces the prior tool-use sentence with guidance for a short preamble, direct tool use, and outcome narration during multi-step work.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~2 minutes

Possibly related PRs

• Gitlawb/openclaude#1656: Also changes the system-prompt tool-use guidance, with a different requirement around when tools should be invoked.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the prompt-only change to add a preamble for multi-step tasks and improve chat readability.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Zero automated PR review

Verdict: No blockers found

Blockers

• None found.

Validation

• [pass] Diff hygiene: git diff --check
• [pass] Tests: go test ./...
• [pass] Build: go run ./cmd/zero-release build
• [pass] Smoke build: go run ./cmd/zero-release smoke

Scope

Head: a4a7ccdaadca
Changed files (1): internal/agent/system_prompt.md

This deterministic review checks validation status and basic diff hygiene. A human reviewer still owns product judgment and design quality.