Spec Writing

Output Formats

1. New Specification

Use the Specification Template. Adapt if needed, but ensure core concerns are addressed.

Required sections: TLDR, Problem Statement, Proposed Solution, Data Models, API Contracts, Risks, Changelog.

2. Architectural Review

# Architectural Review: {SPEC-0XX: Title}

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

## Findings

### Critical
{Cross-module ORM, tenant isolation leaks, missing auth guards}

### High
{Missing undo logic, incorrect module placement, missing phase strategy}

### Medium
{Missing failure scenarios, inconsistent terminology}

### Low
{Style suggestions, nits}

Review Heuristics

1. Command Graph vs. Independent Ops: Graph Save (coupled calculation) or Compound Command (independent steps)?
2. Architectural Diff: Cut standard CRUD noise. Focus on what's unique.
3. Singularity Law: Singular naming for entities, commands, events, feature IDs.
4. Undo Contract: Is the "Undo" logic as detailed as the "Execute"?
5. Module Isolation: Using Event Bus for side effects or cheating with direct imports?

Quick Rule Reference

• Singular naming for entities, commands, events, feature IDs.
• FK IDs only for cross-module links — no ORM relationships.
• organization_id is mandatory for all tenant-scoped entities.
• Undoability is the default for state changes.
• Zod validation for all API inputs.

Reference Materials

• Spec Template
• Spec Checklist
• AGENTS.md