write-project-docs

name	write-project-docs
description	Write or refine durable engineering documentation such as API contracts, architecture docs, handoff docs, design notes, and reviewer-facing project documentation. Use when polishing project docs, documenting phase boundaries, or preventing conversation-specific/user-instruction wording from leaking into final artifacts.

Write Project Docs

Core Standard

Write the artifact as project documentation, not as a response to the user. The final document should stand alone for future readers and should not mention the conversation, the user's instructions, or the act of writing the document.

Target expert maintainers. Assume they understand the product direction and adjacent system design, but they have not held all implementation details in working memory. Technical detail is welcome when it helps them review, debug, or take over the system during an incident.

Content To Cover

For project architecture docs, API contracts, and handoff docs, include the parts that help a reviewer reason about correctness:

• System purpose and the main safety or consistency rule.
• End-to-end flow through the main runtime path.
• Phase boundaries and the state crossing each boundary.
• Responsibilities: which module makes each decision, transformation, and failure behavior.
• Persisted state and why each field exists.
• Failure modes and the expected recovery behavior.
• Complexity isolation: where subtle logic belongs and where it should not spread.
• Invariants that future changes must preserve.
• Operational entry points for diagnosing stuck or degraded behavior.

Prefer concrete state names, method names, enum values, table names, and file paths from the code. If a concept is abstract, explain it with a small concrete example.

Structure

Present the runtime flow before diagnostic entry points. A good default order is:

1. Purpose and primary runtime rule.
2. End-to-end flow.
3. Phase boundaries.
4. Operational entry points.
5. Component responsibilities.
6. Persisted state, failure behavior, and invariants.

Use a Mermaid flowchart when the flow has branches, retries, queued follow-ups, or state transitions. Keep supporting prose short so the diagram carries the flow.

Language Rules

Use direct system statements:

• Prefer "The scheduler records last_started_at" over "This section explains how the scheduler records...".
• Prefer "Import jobs start with these records" over "Use these records when debugging...".

Keep rationale out of the artifact unless it is architectural rationale that a maintainer needs. Put conversational explanation in the assistant response, not in the documentation file.

Keep local technical decisions out of durable project docs unless they define a cross-boundary contract. Avoid expanding durable project docs with:

• Runtime constants or env var inventories.
• README-style configuration details.
• Runbook chores that do not explain system shape.
• Implementation-local method sequencing that is already clear from code.
• Future cleanup reminders or TODO-like retention notes.

Preserve concrete names only when they anchor an architectural contract, persisted state, failure behavior, or emergency diagnosis path.

When two concepts share similar implementation names, choose distinct reader-facing terms in durable docs. For example, distinguish a worker lock from an API idempotency token instead of calling both "locks." Keep persisted field names visible only where they anchor state or diagnosis.

Avoid meta and instruction-leak phrases in the final artifact:

• "This document is for..."
• "This document explains..."
• "The goal of this review..."
• "As discussed..."
• "Per your request..."
• "You should..."
• "Reviewers should..."
• "Future maintainers should..."

Avoid stock contrast patterns unless they add real information:

• "not X but Y"
• "rather than"
• "intentionally"
• "instead of"

Avoid wording that sounds abstract but does not add precision.

Prefer concrete system nouns and verbs:

• "The billing service publishes payment events."
• "The importer validates each row before writing customer records."
• "The export file contains invoice records for one account."

Avoid vague phrasing:

• "carrier for desired state"
• "surface for synchronization"
• "wrapper around truth"
• "vehicle for data movement"

Also avoid project-doc cliches:

• "the core invariant"
• "own", "owns", "ownership"
• "answer separate questions"
• overusing "keeps", "lets", or "stays" when a concrete verb would name the action

Prefer direct alternatives such as "runtime split", "safety rule", "handles", "provides", "applies", "defines", "records", "component responsibilities", or "cover different layers".

Avoid sections that package advice as reader instructions:

• "Refactor Warning Signs"
• "Design Review Alarms"
• "What Reviewers Should Watch For"

Convert useful content from those sections into project documentation facts: phase boundaries, responsibility rules, failure modes, or invariants.

Review Workflow

Before editing, read the current doc and the code names it references. Align the document vocabulary with the implementation vocabulary.

When drafting, start from the project facts:

1. What runs?
2. What state is persisted?
3. What state crosses process or phase boundaries?
4. Which module makes each decision?
5. What can fail?
6. What rule prevents data loss, duplicate work, or stale cleanup?

After editing, run a leak scan for meta wording and stale names. Useful search terms:

rg -n "This document|document is|reviewer|reader|future maintainer|you|your|instructions|as discussed|per your request|goal of this review|rather than|intentionally|not .* but|core invariant|\\bowns?\\b|ownership|answer separate questions" <doc>

Do not treat every match as wrong. Inspect each match and remove wording that makes the artifact sound like it is answering the current user conversation.