spec-writing-rules

name	spec-writing-rules
description	Enforces clear, unambiguous, testable, FULL-STACK specification writing rules for Phase II web applications (Frontend + Backend + Auth + Database). Apply before any code is written. Use when this capability is needed.
metadata	{"author":"afaqulislam"}

Full-Stack Specification Writing Rules (Phase II)

Purpose

This skill enforces a strict spec-before-code discipline for full-stack web applications.
No frontend, backend, database, or authentication code may be written until a complete, approved specification exists.

This specification acts as a binding contract between:

• Frontend (Next.js)
• Backend (FastAPI)
• Authentication (JWT / Better Auth)
• Database (SQLModel + PostgreSQL)

---

Core Principles

1. Specification-First Mandate

• NEVER write frontend or backend code before the specification is approved
• All APIs, UI flows, auth behavior, and data models must be defined first
• Specs must support multi-user, authenticated systems
• The specification is the single source of truth

---

Mandatory Specification Structure (Phase II)

Every Phase-2 spec MUST contain all sections below.

---

A. Overview

• Purpose: What problem does this system solve?
• Scope: What is included and explicitly excluded?
• Target Users: Authenticated users, roles (if any)
• System Architecture:
  • Frontend (Next.js App Router)
  • Backend (FastAPI)
  • Auth (JWT via Better Auth)
  • Database (Neon PostgreSQL)

---

B. Functional Requirements

1. Frontend Requirements

• Pages and routes (e.g. /login, /tasks)
• UI states (loading, empty, error)
• Auth flows (signup, signin, logout)
• API interaction behavior
• Client-side validation rules

2. Backend / API Requirements

For every endpoint, define:

• HTTP method + path
• Required headers (Authorization: Bearer JWT)
• Request body schema
• Response schema
• Success status codes
• Error status codes (401, 403, 404, 422, 500)

3. Authentication Requirements

• JWT issuance behavior
• Token expiry rules
• Unauthorized request handling
• User isolation rules (data ownership enforcement)

4. Data Requirements

• Entities and fields
• Field types and constraints
• Ownership rules (user_id)
• Indexing expectations

---

C. Non-Functional Requirements

• Security (JWT validation, user isolation)
• Performance expectations
• API consistency rules
• Error message clarity
• Environment variable usage (no hardcoded secrets)

---

D. Constraints

Technical Constraints

• Next.js App Router only
• FastAPI + SQLModel only
• PostgreSQL via Neon
• JWT authentication mandatory

Architectural Constraints

• Frontend NEVER directly accesses DB
• Backend NEVER trusts user_id from URL without JWT validation
• Stateless backend auth

---

E. Acceptance Criteria (CRITICAL)

Every feature must include:

• ✅ Happy-path scenario
• ❌ Unauthorized access scenario
• ❌ Cross-user access attempt
• ❌ Invalid payload scenario
• Edge cases (empty data, duplicates, limits)

Acceptance criteria must be directly testable by:

• API tests
• Manual UI testing
• Agent-based test-runner

---

Specification Lifecycle

Phase 1: Discovery

• Identify frontend + backend + auth needs
• Resolve ambiguity before writing spec

Phase 2: Drafting

• Write all mandatory sections
• Define contracts clearly between layers

Phase 3: Review

• User approval required
• No “TBD” allowed

Phase 4: Lock

• Mark spec as APPROVED
• Only then code generation may begin

---

Anti-Patterns (STRICTLY FORBIDDEN)

❌ Writing UI without API spec
❌ Writing API without auth rules
❌ Assuming frontend behavior
❌ Mixing implementation code in specs
❌ Skipping error cases
❌ Using vague language (“should”, “maybe”)

---

Quality Gate Checklist

Before approval, verify:

• Frontend + Backend + Auth covered
• Every API secured
• User data isolation defined
• JWT behavior specified
• Acceptance criteria are testable
• User explicitly approved spec

---

Usage

Invoke this skill when:

1. Starting any Phase-2 feature
2. Writing API, auth, or UI specifications
3. Before generating backend or frontend code
4. Preparing specs for agentic implementation

---

Success Criteria

A specification is complete when:

1. Backend and frontend can be built independently
2. No clarification is needed during coding
3. Auth and security behavior is explicit
4. Test-runner can validate it objectively
5. User has approved it

---

Converted and distributed by TomeVault — claim your Tome and manage your conversions.