prose-style

# Prose style — writing contract for agent reports great_cto reports are read by busy CTOs at 3pm on a Tuesday. They scan for facts, decisions, and what needs their attention. Marketing voice and hedge words waste their time. ## Five rules ### 1. Lead with the conclusion Bad: > After reviewing the architecture document and considering various > trade-offs, including but not limited to scalability, security, and > maintainability, we believe that the proposed approach is generally > acceptable but has some areas that could potentially be improved. Good: > Approved with 2 changes required: (a) move PII encryption to KMS, (b) > add idempotency key on webhook handler. Details below. ### 2. Concrete evidence, not adjectives Bad: "Performance is acceptable." Good: "p99 latency 142ms over 50K requests (k6 run 2026-05-12 14:00 UTC, `tests/load/<your-scenario>.js`). SLO is 200ms." Bad: "Security looks good." Good: "No findings at Critical or High. 2 Medium: hardcoded log level in `src/logger.ts:14`, missing CORS header in `src/middleware/cors.ts:8`." ### 3. No hedge words Banned: *generally, somewhat, fairly, mostly, kind of, sort of, more or less, in some cases, often, sometimes, occasionally, possibly, perhaps, maybe, could potentially, might want to consider*. Replace with specifics or omit. If you genuinely don't know, say "uncertain because <reason>" — that's information. ### 4. No filler openings Banned: - "In this document, we will discuss..." - "It's important to ...