Skip to content

Add a functional-prose convention for comms drafting (distinct from voice + style calibration) #203

Description

@aaronsb

Summary

Suggest adding a "functional prose" convention to the comms/EA ways. It is a quality
axis distinct from the two the ways already cover:

  • meta/trust/voice/voice.md covers whose voice (ghostwriting / attributed / collaborative).
  • ea/email/drafting/drafting.md covers matching the user's observed style, plus a list of phrase-level AI tells to avoid.

Neither covers the prose-quality floor: write functional, plain prose where punctuation
and structure serve the signal rather than decorate it.

The principle

  • Normal capitalization. Sentence case, capital "I". Not an affected all-lowercase style.
  • Functional prose, not polished prose. Clear and direct over stylish.
  • Avoid em dashes and other ornamental punctuation. They form a side-channel that blurs
    the point rather than sharpening it. Periods, commas, colons, and parentheses do the work.
  • Structure matches content ("human markdown"). If it needs a list, use a list. If it is
    code, use a code block. If it is a quote, quote it. If it is just explaining, plain prose.
  • The point is not effort. It is no harder or easier to write either way. The point is
    signal clarity: strip anything that dilutes meaning.

A useful framing from the conversation that prompted this: a Scandinavian, Linus-style
approach to development communication. Not polished business prose, and not affected
all-lowercase either. Just functional.

Why it is its own axis

  • It is orthogonal to voice. It applies whether ghostwriting or writing attributed as Claude.
  • The current email anti-patterns catch phrase-level tells ("circling back", "happy to")
    but not punctuation-level noise. Em dashes and ornamental connectors are a common AI
    tell that survives the present list.
  • There is a real tension worth resolving. drafting.md says match the user's voice, but
    a functional-prose floor is a quality bar that can apply even when a user's own style is
    looser. Worth deciding whether this is a universal floor or a per-user calibration.

Where it could live (maintainer's call)

  • A new child way under writing/ or meta/trust/voice/, e.g. functional-prose,
    refired on comms/drafting prompts.
  • Or a shared "prose quality" section folded into ea/email/drafting and ea/comms.
  • Or extend the email anti-patterns list with the punctuation-noise items and link a
    fuller way for the reasoning.

Provenance

Surfaced from real use. While drafting a multi-message Slack briefing through a user's
account, the first pass used em dashes throughout and an affected all-lowercase "i". The
correction generalized into the principle above, which felt general enough to belong in
the ways rather than in one project's memory.

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:waysWays CLI, matching, steering layerenhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions