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 " — 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.