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 note that..."
- "First and foremost..."
- "At the end of the day..."
- "It goes without saying..."
If a sentence can be deleted without losing information, delete it.
5. Verdict line on the last line
Every terminal report ends with one of:
VERDICT: APPROVED — <one-line summary>
VERDICT: DONE — <one-line summary>
VERDICT: BLOCKED reason="<specific blocker>"
VERDICT: FAIL reason="<specific failure>"
This is parsed by the board's readVerdicts() function. Format is
machine-readable — no flourishes.
Templates
Reviewer report
# REVIEW-<feature> — <reviewer name>
Reviewed: <commit-sha or file paths>
Standard: <regulation / framework you applied>
## Findings
- [Critical|High|Med|Low] <one-sentence finding>
- location: <path:line>
- rationale: <why this matters in this domain>
- remediation: <specific fix>
## Verdict
VERDICT: APPROVED|BLOCKED reason="<short>"
Architecture / ADR
# ARCH-<feature> | ADR-<NNN>
Date: <ISO>
Status: proposed | accepted | superseded
## Context
2-4 sentences. What problem, what constraint.
## Decision
Imperative single sentence: "Use X for Y."
## Consequences
- Positive: <bullets>
- Negative: <bullets>
- Reversible? yes/no — if no, document migration cost
## Alternatives considered
<bullets with one-line dismissal reason each>
Anti-patterns to grep for
Before writing the verdict line, search your draft for:
\b(generally|somewhat|fairly|mostly|kind of|sort of|possibly|perhaps|maybe)\b
If a hit is in a non-quoted sentence, rewrite it to be concrete or delete it.
Why this matters
The board's readVerdicts() parses every report. Marketing voice breaks
the parser. Hedge-word reports waste the reader's time. Specifics let the
CTO trust the agent's judgment.