prose-style

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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

```markdown
# 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

```markdown
# 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

From avelikiy/great_cto, MIT.

More from avelikiy/great_cto