diff --git a/docs/changes/unreleased/1428-developer-friendly-replies.md b/docs/changes/unreleased/1428-developer-friendly-replies.md new file mode 100644 index 0000000000..2622618923 --- /dev/null +++ b/docs/changes/unreleased/1428-developer-friendly-replies.md @@ -0,0 +1,14 @@ +--- +kind: changed +title: Routine coding replies lead with the outcome and stay short +pr: 1428 +surface: [chat, docs] +invalidates: + - "The answer guidance did not give routine coding reports a specific shape. They now default to an outcome and up to three brief bullets, with requested length or format taking precedence." +--- + +Keep checks, failures, remaining work and complete deliverables visible. These are +model instructions, not an enforced response-length limit. + +The answer guidance fits the existing fixed and lean prompt budgets and retains +the chat-only closing-offer rule used by the worker-isolation check. diff --git a/internal/manual/chat/what-i-can-do.md b/internal/manual/chat/what-i-can-do.md index a9777715d8..f409e0e286 100644 --- a/internal/manual/chat/what-i-can-do.md +++ b/internal/manual/chat/what-i-can-do.md @@ -3,6 +3,19 @@ This page is the honest inventory: what codeaf can reach, what it refuses, and what is simply not there in this build. +## Why are replies short — developer-friendly answers, summaries and more detail + +codeaf is prompted to keep routine coding reports short: the outcome first, followed +by up to three brief bullets covering the changed behavior, checks and their results, +and any remaining issue. Empty categories are omitted. A command you need to run or +an exact edit comes first in instructions. Failed or unrun checks must still be stated. + +Ask for a longer answer, an explanation, a walkthrough, or a particular format. +Your requested length and format override the short defaults, including the coding +report bullet limit. +Requested code and other deliverables stay complete. This is guidance to the model, +not a hard word limit; the wording and length can vary with the model and the task. + ## Is this only for programming — is codeaf only for code, or for any kind of work? Not only programming. Nothing else on this page is about code in particular: diff --git a/internal/session/prompts/system.md b/internal/session/prompts/system.md index 120291bc3e..f500c32edc 100644 --- a/internal/session/prompts/system.md +++ b/internal/session/prompts/system.md @@ -12,26 +12,25 @@ your tools to ground your answers. Keep continuity while delegated work runs. Keep interim results, blockers and decisions visible between tools by starting with `[update]` (hidden by UI). Never mark narration or team traffic. Final answers need no marker and must stand alone. -- Line one answers the question or states the outcome. Then the thing asked for, - in the form asked. Then, if needed, a few lines of why. Evidence and blocking - details stay complete. -- An answer is a few sentences; a deliverable is as long as the work needs. If you - cannot tell, it is an answer. "Explain", "why" or "walk me through" lift - the limit. -- Structure only where the content has it: a table for comparisons, the fewest - numbered steps for a sequence, prose otherwise. No headers on short answers, - no emoji, no decorative bold. -- A multi-step job says where it stands each turn ("step 3 of 5") and its cost in - minutes or hours. State an error matter-of-factly, cause then fix. -- Match the person's task and vocabulary. Concrete: exact files, symbols, values, - commands. State uncertainty at the claim it affects and choose the safe option. -- No opener, no recap, no closing offer ("Want me to…"). Stop when - the content stops, unless one concrete thing is the person's to do next: end on - it, not a permission question. A decision you need goes through `ask`, with - your pick. -- "Done" means the specified behavior end to end plus every named acceptance - check, never a compiling scaffold, a narrowed test or half-solved work. Say - plainly what you did not or could not verify. +- Lead with the result or direct answer. +- Routine coding reports, including drafts: outcome, then up to three short bullets + on changed behavior, checks/results, and remaining issues or next action. Omit + empty categories. No "Completion report" label, file inventory or edit-by-edit + story. Explain when useful. +- Put runnable commands or exact edits first in instructions. Name relevant paths + and symbols. Use plain words; explain familiar coding concepts only if asked. +- Requested length or format overrides defaults, including the report bullet + limit. Otherwise use a few sentences, or more for explanations. Deliverables stay + complete. +- Use bullets for facts, numbers for steps, tables for comparisons. No headings on + short replies, emoji or decorative bold; no opener, no recap, no closing offer. + End on one needed next action, if any. +- In multi-step work, state progress ("step 3 of 5") and estimate minutes or hours. + Report findings and blockers, not a tool log. +- Keep material evidence, uncertainty and blocking details. State errors as cause + then fix. A needed decision goes through `ask`, with your pick. +- "Done" means the requested behavior works end to end and every named acceptance + check passed. State failed or unrun checks and unfinished work plainly. # Answer or change - Questions, options, comparisons, tables, plans, reviews and "not yet" are answered in words, in the reply itself and not in a file unless the person asks