repository-writing-style

Files (6)

• SKILL.md
• documentation.md · references/
• github-issues.md · references/
• pull-request-descriptions.md · references/
• release-notes.md · references/
• review-notes.md · references/

SKILL.md (first lines)

# Repository writing style

Write contributor-facing text in a clear, natural, technically informed voice.

The result should sound like a thoughtful project maintainer: direct without being abrupt, confident without overstating the case, and detailed only where the detail helps the reader.

## Format-specific guidance

Read only the references relevant to the current task:

- For proposals, feature requests, bug reports, and other GitHub issues, read [references/github-issues.md](references/github-issues.md).
- For pull request summaries, implementation explanations, testing notes, and reviewer guidance written by the PR author, read [references/pull-request-descriptions.md](references/pull-request-descriptions.md).
- For inline review feedback and overall PR review comments, read [references/review-notes.md](references/review-notes.md).
- For contributor guides, procedural documentation, architecture notes, and reference material, read [references/documentation.md](references/documentation.md).
- For changelogs, release notes, and version announcements, read [references/release-notes.md](references/release-notes.md).

When a task spans multiple formats, read each relevant reference. Do not read unrelated references.

## Start from the reader's needs

Before writing, determine:

- Who will read the text
- What they need to understand
- What they need to decide or do
- Which technical details affect that decision
- Which facts and conventions already exist in the repository

Give readers enough context to understand the subject without requiring them to reconstruct it from code or prior conversations.

Do not include background that has no effect on their understanding or next action.

## Voice

Use a calm, direct, collaborative voice.

Write as someone who:

- Understands the project
- Respects the reader's time
- Explains the reason behind important decisions
- Distinguishes facts from opinions and proposals
- Acknowledges trade-offs without becoming defensive
- Assumes contributors are acting in good faith
- Prefers useful constraints over vague instructions

Use plain English and concrete statements.

Prefer:

> Large diffs are harder to review with confidence.

Avoid:

> Oversized changes introduce significant cognitive overhead into the review lifecycle.

Prefer:

> This check gives contributors and coding agents an early boundary before a change reaches review.

Avoid:

> This mechanism facilitates the proactive governance of AI-assisted development workflows.

## Keep the writing natural

Use short and medium-length sentences. Longer sentences are fine when they express one connected thought clearly.

Vary sentence structure enough that the prose does not feel mechanical. Use contractions when they fit the context.

Prefer familiar words:

- “use” instead of “utilize”
- “help” instead of “facilitate”
- “before” instead of “prior to”
- “because” instead of “due to the fact that”
- “to” instead of “in order to”
- “about” instead of “with regard to”

Avoid stock phrases and generic transitions such as:

- “It is important to note that”
- “Furthermore”
- “Moreover”
- “In today's landscape”
- “This comprehensive approach”
- “By leveraging”
- “This ensures that”
- “At the end of the day”
- “There are several key benefits”
- “It is worth mentioning”

Do not use exaggerated adjectives to make an ordinary change sound important. Words such as “robust,” “seamless,” “powerful,” “comprehensive,” and “revolutionary” should appear only when they convey something specific and defensible.

Avoid canned contrasts such as:

> This is not just about X; it is about Y.

State the actual point directly.

Never use em dashes (—). Use a period, comma, colon, semicolon, or parentheses instead, whichever fits the sentence.

## Be accurate and specific

Ground explanations in the repository.

Use concrete references when they help:

- Files and directories
- Commands
- Configuration keys
- Branches and workflows
- Issues and pull requests
- Observed failures
- Real examples
- Measured limits

Explain why a reference matters. Do not add technical detail merely to make the text appear authoritative.

From Database-Tycoon/tycoon-cli, MIT.

More from Database-Tycoon/tycoon-cli