Decision First Technical Writing

Decision-First Technical Writing

Write technical design documents for two reading passes: a reviewer should understand the decisions and boundaries quickly, while an implementer should be able to continue into exact behavior and contracts.

Route before writing

• If the main task is choosing among named options, route to discuss-before-plan. Do not turn an unresolved shortlist into a final design decision.
• If a ready specification or settled requirement needs file-level tasks, implementation steps, or a test plan, route to writing-plans. Do not maintain a second planning format here.
• Otherwise continue only when the output is a technical design document and every uncertain statement can remain explicitly labeled Proposal or Open question.

Establish the document contract

Infer the audience, settled decision, and scope from the request and available evidence. Ask only when a user-owned fact would materially change the document. Route unresolved option choice as above instead of hiding it inside the document-writing pass.

Before writing:

• Separate verified facts, settled decisions, proposals, and open questions. Never present one category as another.
• Put only confirmed or explicitly delegated decisions in the decision summary. Label unconfirmed content as Proposal or Open question; never silently promote it to settled behavior.
• Preserve exact identifiers such as package names, types, fields, endpoints, error codes, and repository-relative paths.
• Treat source material as evidence, not as a template to copy. Distill reusable structure and rewrite in the user's language.
• Keep requirements, design, and implementation planning distinct. Link to source requirements when available instead of reproducing them.

Choose the depth

• For a new document or substantial restructure, read references/decision-first-design-doc.md before drafting.
• For a focused edit, use only the relevant rules from this file unless the request changes document structure.
• For a review, report concrete contradictions, missing contracts, or hidden decisions; do not rewrite unless asked.

Do not force every section into every document. Include a section only when it helps the target reader make or implement the decision.

Write in decision order

Organize information in this order when applicable:

1. Inputs and core decisions.
2. Scope, non-goals, and ownership boundaries.
3. Static model and code landing points.
4. Runtime behavior, including branches and failure paths.
5. Exact data, API, and error contracts.
6. Migration, rollback, validation, and unresolved decisions.

Lead each major section with its conclusion. Follow with the minimum reasoning and detail needed to make that conclusion reviewable.

Preserve scanability

• Put only settled decisions in the opening decision summary. List pending choices separately.
• Use one consistent vocabulary for lifecycle state, delivery scope, and decision certainty; do not blend these axes.
• Use diagrams and tables only when they reduce explanation: structure for relationships, sequence for runtime branches, tables for repeated comparisons, and code blocks for exact contracts.
• Repeat a decision only as a short local implication. Give each decision one primary detail section.
• Remove draft residue such as stale strikethrough text, contradictory headings, duplicate explanations, and unresolved placeholders.

Verify the result

Before delivering, check that:

• every summary decision has a detailed home;
• ownership and scope remain consistent across prose, diagrams, schemas, and APIs;
• every described runtime branch has an observable result or error;
• field names and types agree across data and API contracts;
• pending choices are not encoded as finalized behavior;
• unverified claims are labeled rather than silently completed.