Spec Authoring

Purpose

Produce detailed, engineering-grade specifications similar in depth and structure to a full platform spec. The output must be explicit, testable, and implementation-ready without needing back-and-forth clarification.

Core Principles

• State intent clearly and early.

• Define scope and non-scope to avoid ambiguity.

• Make every requirement verifiable.

• Prefer concrete examples over vague descriptions.

• Use consistent naming and types across the document.

• Include failure modes and edge cases.

• Avoid assumptions; write them down.

• Define canonical data models in a single spec and reference them elsewhere to prevent duplication.

Required Structure

See the SPEC_TEMPLATE.md for a template with detailed section descriptions and writing guidelines.

Follow this structure exactly, but customize content to the project.

Writing Rules

• Use precise, plain english language.

• Prefer tables for enums, options, or matrices.

• Include code blocks with correct syntax highlighting.

• Keep naming consistent across entities, APIs, and SDKs.

• If a behavior depends on policy, state it explicitly.

• If a data model is shared across domains, treat one spec as the source of truth and reference it rather than re-defining it.

Output Quality Checklist

Before finalizing, confirm:

• Scope is explicit and non-goals are listed.

• All core entities and relationships are defined.

• Every endpoint has auth and payloads.

• All critical workflows are described step-by-step.

• Security and permissions are not implicit.

• At least one example is given for each major section.

Related docs

When the new spec is complete, update specs/README.md to include it in the list of available specs.