spec-writing

name	spec-writing
description	Guide for creating high-quality specifications for sandbox. Use when starting a new SPEC or reviewing specs against architectural standards.

Spec Writing & Review

Design and review specifications (SPECs) against Open Mercato architecture and quality rules.

Workflow

1. Load Context: Read AGENTS.md for module conventions and .ai/specs/ for existing specs.
2. Initialize: Create {date}-{title}.md in .ai/specs/.
3. Start Minimal: Write a Skeleton Spec (TLDR + 2-3 key sections). Do NOT write the full spec in one pass.
   • Scan for critical unknowns — decisions that block data model, scope, or architecture.
   • If unknowns exist, add a numbered Open Questions block (Q1, Q2, …) after the TLDR.
   • STOP after presenting the skeleton. Do not proceed until the user answers all questions.
4. Iterate: Apply answers, remove Open Questions block. Repeat if new unknowns surface.
5. Research: Challenge requirements against open-source market leaders.
6. Design: Create architecture, data models, API contracts.
7. Implementation Breakdown: Break into Phases (stories) and Steps (testable tasks).
8. Review: Apply the Spec Checklist.
9. Output: Finalize the specification file.

Output Formats

1. New Specification