Spec Writing

Output Formats

1. New Specification (Writing)

When asked to write or draft a specification, use the Specification Template as a guide. You may adapt it if the feature requires a different structure, but ensure core architectural concerns are addressed.

Key Sections to Include:

• TLDR & Overview: Summary and context.
• Problem Statement: What are we solving?
• Proposed Solution: High-level approach.
• Phasing: Breakdown of delivery.
• Implementation Plan: Detailed steps.

2. Architectural Review (Reviewing)

When asked to review or audit a specification, produce the report using this structure:

# Architectural Review: {Spec Title}

## Summary
{1-3 sentences: what the spec proposes and overall architectural health}

## Findings

### Critical
{Violations of core laws: plural naming, cross-module ORM, tenant isolation leaks}

### High
{Missing Phase strategy, lack of undo logic, incorrect package placement}

### Medium
{Missing failure scenarios, inconsistent terminology, spec-bloat}

### Low
{Stylistic suggestions, diagram improvements, nits}

## Checklist

Refer to [Spec Review Checklist](references/spec-checklist.md).

Review Heuristics (The "Martin Fowler" Lens)

1. Command Graph vs. Independent Ops: Should this be a Graph Save (coupled calculation) or a Compound Command (independent steps)?
2. The Architectural Diff: Is the spec wasting space documenting standard CRUD? Cut the noise, focus on the unique.
3. Singularity Law: Does the spec use pos.carts (FAIL) or pos.cart (PASS)?
4. Undo Contract: How is the state reversed? Is the "Undo" logic as detailed as the "Execute"?
5. Module Isolation: Are we using Event Bus for side effects or cheating with direct imports?

Quick Rule Reference

• Singular naming for everything (entities, commands, events, feature IDs).
• FK IDs only for cross-module links.
• Organization ID is mandatory for all scoped entities.
• Undoability is the default for state changes.
• Zod validation for all API inputs.

Reference Materials

• Spec Review Checklist
• Final Compliance Review
• Specification Template
• Root AGENTS.md