Technical writing

Technical Writing — Write & Review

Twelve rules govern all technical writing produced or reviewed under this skill. The rules form a constitution: when any other style guidance conflicts with them, these rules win.

Scope

The rules govern written artifacts:

• Documentation: READMEs, architecture decision records (ADRs), runbooks, API references, design docs
• Code comments and docstrings
• Commit messages, pull request (PR) titles, and PR descriptions
• Obsidian vault notes

The rules do not govern conversational replies. Dialogue with the user keeps its natural register; Rule 1 applies to artifacts, never to conversation. Verbatim quotes and third-party text stay untouched.

Modes

Mode	Activation	Output
Write	Default when authoring any in-scope artifact	Content compliant with all 12 rules
Review	Requests containing "review", "audit", "check", or a target file	Rule-by-rule compliance report; fixes only on request

Write mode procedure

1. Identify the artifact type and audience. State the audience at the top when not obvious from context (Rule 11).
2. Draft the content applying Rules 1–12.
3. Self-check the draft against the Review report format. Fix every violation before delivering.
4. If the avoid-ai-writing skill is installed, run it as a final pass. Its edits must not delete prerequisites, edge cases, or scope boundaries (Rule 12 precedence).

Review mode procedure

1. Read the target document completely.
2. Check each of the 12 rules in order. Record every violation with a line reference and quoted evidence.
3. Check the patterns in references/ai-patterns.md. Record matches as additional rows labeled "AI pattern".
4. Emit the compliance report (see the Review report format section).
5. Fix only when the user requests fixes. After fixing, re-run the review once to confirm the report is clean.
6. If the avoid-ai-writing skill is installed, run it as a final pass.

The 12 rules

Rule 1 — Objective & impersonal

Write in third person. Remove personal pronouns from all technical content.

• ✓ "The function calculates the delta between snapshots."
• ✗ "We calculate the delta..." / "I will skip..." / "My logic is..."

Rule 2 — Explain the why, not just the what

Comments and documentation must convey intent, not mechanics.

• ✓ # Role hierarchy prevents admins from being downgraded during sync
• ✗ # Check if role is admin

Rule 3 — Declarative style

State facts directly. No conversational lead-ins.

• ✓ "The service processes messages in FIFO order."
• ✗ "Here, we are going to process messages..." / "Note that..."

Rule 4 — No agentic meta-commentary

No AI authorship traces, agent notes, or AI disclaimers in documents.

• ✓ # Retry logic handles transient network failures
• ✗ # Agent Note: I fixed this bug / # TODO: As an AI, I suggest...

Rule 5 — Technical precision

Use exact versions, concrete values, and definitive language. Never hedge.

• ✓ "The runtime requires Python 3.12 or later."
• ✗ "The newer version probably needs a recent Python." / "might", "could", "possibly", "I think"

Rule 6 — Actionable & imperative

Instructions must be direct and sequentially structured.

• ✓ "Configure the connection string in local.settings.json."
• ✗ "You should maybe look into configuring the connection string."
• Number sequential steps (1, 2, 3).
• Bullet parallel options.
• Never mix sequential instructions into unordered bullet lists.

Rule 7 — Acronyms & terminology consistency

Spell out acronyms on first use. Use one term per concept throughout a document.

• ✓ "Row-Level Security (RLS)" on first use, then "RLS" consistently.
• ✗ Alternating between "data warehouse", "DWH", and "warehouse" in the same document.

Rule 8 — Formatting discipline

Use backticks, tables, and structured formatting to maximize clarity.

• Backtick all code, commands, and file paths: main.py, pip install.
• Use tables for comparisons; never write comparison prose when a table is clearer.

Rule 9 — No filler or emotional language

Start directly with relevant content. No pleasantries, apologies, or assumptions.

• ✗ "Great question!", "Let me explain...", "Here's an interesting thing..."
• ✗ "Unfortunately...", "Sorry, but...", "Obviously...", "Clearly..."

Rule 10 — Cross-referencing

Link to specific notes and sections. No vague references.

• ✓ "See [[RLS Architecture]] for implementation details."
• ✓ "As defined in the Prerequisites section of [[ADR-001]]."
• ✗ "There is some related info somewhere in the vault." / "As mentioned earlier" / "See above"

Rule 11 — Audience awareness

Match technical depth to the document's intended audience. State the intended audience at the top when not obvious from context.

• No unexplained jargon in stakeholder-facing documents.
• No over-simplification in engineering reference documentation.

Rule 12 — Completeness over brevity

Include prerequisites, assumptions, edge cases, and explicit scope boundaries.

• State what a feature does NOT do when it addresses a common misconception.
• Never omit context assuming the reader already knows.
• Never leave scope or boundaries ambiguous.

Context adaptations

• Links (Rule 10): use [[wikilinks]] inside Obsidian vault notes; use standard Markdown links inside repositories.
• Audience (Rule 11): stakeholder-facing documents state the audience in the first line under the title.
• Precedence: the 12 rules override any tone filter, including avoid-ai-writing. Completeness (Rule 12) beats anti-padding: a de-slop pass must never remove prerequisites, edge cases, or scope statements.

Review report format

Emit one table, then a verdict line:

#	Rule	Verdict	Evidence	Fix
1	Objective & impersonal	FAIL	line 12: "We calculate the delta"	"The function calculates the delta"
5	Technical precision	PASS	—	—
AI	Hedge stack	FAIL	line 30: "might potentially break"	"breaks when X"

Verdict line: COMPLIANT or <N> violations across <M> rules.