GSD FRAMEWORK: EXTERNALIZED SPEC SYSTEM

PROBLEM SOLVED
Context rot - after 10+ conversation turns, Claude forgets decisions made in turn 2. Solution: Keep specs external (JSON, markdown), not in chat.

SPEC STRUCTURE (4-week project)

PHASE 1: FOUNDATION (Week 1)
spec.md:
• Project name + goal (1 sentence)
• Tech stack (Node 20, Next.js 14, Postgres)
• Database schema (tables, relationships)
• Core entities (User, Project, Task)
• API endpoint list (10 endpoints)
• Architecture diagram (simple ASCII)
→ Owner: Tech lead
→ Update frequency: Weekly Mondays

PHASE 2: FEATURE BREAKDOWN (Week 2)
features.json:
[{
  "id": "auth-login",
  "status": "in-progress",
  "owned_by": "devA",
  "acceptance_criteria": [
    "Email+password login works",
    "Sessions persist >30 days",
    "404 on invalid email (security)"
  ],
  "decisions": "Use Lucia, not Supabase auth",
  "blockers": "none"
}]
→ One JSON object per feature
→ Updates: Before each coding turn, check spec for current status

PHASE 3: DECISIONS LOG (Weeks 1-4)
decisions.md:
→ 2026-07-31: "Using Postgres UUID over sequential IDs" (why: easier sharding later)
→ 2026-08-01: "Rejected GraphQL - REST only" (why: team familiarity, deployment speed)
→ 2026-08-05: "Migrate from SQLite to Postgres" (schedule: before week 3)
→ Each decision: date + rationale + impact

CODING WORKFLOW
At turn start: "Read spec.md, features.json. Feature 'auth-login' in progress."
At turn end: "Update features.json: auth-login → testing. New decision logged."
→ Conversation resets after turn 20 without losing context
→ New collaborator onboards in 30 min (read specs, not 100-turn chat)

TOOLS REQUIRED: GitHub repo (commit specs on each update), or shared Google Doc, or Claude artifact (public link in README).