@abdullah-alnahas/claude-sdd 0.1.0

package/commands/sdd-phase.md

@@ -0,0 +1,46 @@
+---
+name: sdd-phase
+description: Show or set the current development phase
+---
+
+# /sdd-phase
+
+Display or change the current SDD development phase. Phases provide context that shapes how guardrails and skills behave.
+
+## Usage
+
+- `/sdd-phase` — Show current phase
+- `/sdd-phase <phase-name>` — Set phase
+
+## Phases
+
+| Phase | Name | Focus |
+|-------|------|-------|
+| **specify** | Specification | Defining what to build (app-description, behavior-spec, stack, architecture, roadmap) |
+| **design** | Design | Architecture decisions, integration patterns, ADRs |
+| **implement** | Implementation | TDD cycles within iterative execution loops — test first, then minimal code |
+| **verify** | Verification | Running full verification suite, spec-compliance checks, security review |
+| **review** | Review | Critic + simplifier agents, retrospective |
+
+## Behavior
+
+1. Display the current phase (or "none" if not set)
+2. If a phase name is provided, set it
+3. Phase context is available to subsequent prompts and skills
+4. Phase affects which skills are most relevant:
+   - `specify` → spec-first skill
+   - `design` → architecture-aware skill
+   - `implement` → TDD discipline + iterative execution skills
+   - `verify` → iterative execution (verification step)
+   - `review` → all agents (critic, simplifier, spec-compliance, security-reviewer)
+
+## Output Format
+
+```
+SDD Phase: implement
+─────────────────────
+Focus: TDD cycles within iterative execution — write tests first, then minimal code to pass
+
+Available skills: tdd-discipline, iterative-execution, guardrails
+Available agents: critic, simplifier, spec-compliance, security-reviewer
+```

package/commands/sdd-review.md

@@ -0,0 +1,52 @@
+---
+name: sdd-review
+description: On-demand self-review using critic and simplifier agents with iterative fix cycles
+---
+
+# /sdd-review
+
+Trigger an on-demand review of recent work using the critic and simplifier agents. Runs iteratively — reviews, fixes, re-reviews until no critical issues remain.
+
+## Usage
+
+- `/sdd-review` — Review recent changes
+- `/sdd-review --max-iterations <n>` — Set max review-fix cycles (default: 3)
+
+## Behavior
+
+1. Identify what was recently changed (git diff or session context)
+2. Run the **critic agent** — find logical errors, spec drift, assumption issues
+3. Run the **simplifier agent** — find unnecessary complexity
+4. If spec documents exist, run the **spec-compliance agent**
+5. Present findings with severity levels
+6. Offer to auto-fix issues found
+7. If fixes are made (using TDD — write test for the fix first if applicable), re-review
+8. Repeat until no critical issues remain or max iterations reached
+
+## Output Format
+
+```
+SDD Review — Iteration 1/3
+──────────────────────────
+
+Critic Findings:
+  [Critical] ...
+  [Warning] ...
+
+Simplifier Findings:
+  [Simplification] ...
+
+Spec Compliance:
+  [X of Y criteria satisfied]
+
+Actions:
+  - Fix critical issues? (y/n)
+  - Apply simplifications? (y/n)
+```
+
+## Principles
+
+- Reviews are honest — findings are reported as-is, not softened
+- Fixes follow TDD: if the fix changes behavior, write a test first
+- Max iterations prevent infinite loops
+- The review itself is part of the iterative execution cycle

package/commands/sdd-yolo.md

@@ -0,0 +1,40 @@
+---
+name: sdd-yolo
+description: Temporarily disable all SDD guardrails for this session
+---
+
+# /sdd-yolo
+
+Disables all guardrails for the current session. Use when you need to move fast without discipline checks.
+
+## Behavior
+
+1. Create `.sdd-yolo` flag file in the project root
+2. Set `GUARDRAILS_DISABLED=true` for the current session context
+3. All hooks check this flag and skip their checks when set
+4. The flag auto-clears on next session start (session-init.sh removes it)
+5. Can also be cleared manually with `/sdd-guardrails enable`
+
+## Output
+
+```
+⚠ YOLO MODE ACTIVATED
+
+All SDD guardrails are disabled for this session:
+  - Pre-implementation checkpoint: SKIPPED
+  - Scope guard: SKIPPED
+  - Completion review: SKIPPED
+
+Guardrails will re-enable automatically on next session start.
+To re-enable now: /sdd-guardrails enable
+```
+
+## Warning
+
+YOLO mode disables ALL behavioral guardrails. This means:
+- No assumption checking before implementation
+- No scope creep detection
+- No completion review
+- No TDD enforcement reminders
+
+Use sparingly. The guardrails exist because LLMs (including this one) make predictable mistakes without them.

package/hooks/hooks.json

@@ -0,0 +1,50 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash $CLAUDE_PLUGIN_ROOT/hooks/scripts/session-init.sh",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "prompt",
+            "prompt": "BEFORE responding to this request, apply the SDD pre-implementation checkpoint:\n\n1. **Enumerate Assumptions**: List every assumption you're making about the user's intent, the codebase, and the approach. Flag any that are uncertain.\n\n2. **Flag Ambiguity**: If the request is unclear, underspecified, or could be interpreted multiple ways, ASK for clarification before proceeding. Do not guess.\n\n3. **Surface Alternatives**: Identify at least 2 alternative approaches. Briefly note trade-offs. If the user's suggested approach has significant downsides, say so.\n\n4. **Push Back on Bad Ideas**: If the request involves overengineering, premature abstraction, unnecessary complexity, or architectural anti-patterns, respectfully push back with a simpler alternative.\n\n5. **Define Scope**: State explicitly what you WILL and WILL NOT change. Any file not directly related to the request is out of scope.\n\n6. **Check for Spec**: If this is a non-trivial feature and no spec exists, suggest creating one first (spec-first principle).\n\n7. **Plan TDD Approach**: Identify what tests should be written first. Implementation follows tests, not the reverse.\n\nOnly after completing this checkpoint should you proceed with implementation. If GUARDRAILS_DISABLED=true is set, skip this checkpoint."
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash $CLAUDE_PLUGIN_ROOT/hooks/scripts/post-edit-review.sh",
+            "timeout": 15
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "prompt",
+            "prompt": "Before finalizing, perform the SDD completion review:\n\n1. **Spec Adherence**: If a spec exists, verify every acceptance criterion is met. List any gaps.\n\n2. **Test Coverage**: Were tests written before implementation (TDD)? Do they trace back to spec criteria? Any untested acceptance criteria?\n\n3. **Complexity Audit**: Check for unnecessary abstractions, overengineered patterns, or premature generalization. Every function should be under 50 lines. Every file should be under 500 lines.\n\n4. **Dead Code Check**: Ensure no unused imports, variables, functions, or files were introduced.\n\n5. **Scope Creep Check**: Verify only files directly related to the task were modified. Flag any unrelated changes.\n\n6. **Conceptual Error Scan**: Re-read the core logic. Does it actually solve the problem correctly? Are there off-by-one errors, race conditions, or logical gaps?\n\nReport findings concisely. If GUARDRAILS_DISABLED=true is set, skip this review."
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/scripts/post-edit-review.sh

@@ -0,0 +1,45 @@
+#!/bin/bash
+# SDD Post-Edit Review Hook
+# Detects scope creep by checking if edited files are related to the current task
+
+set -euo pipefail
+
+# Skip if guardrails disabled
+if [ "${GUARDRAILS_DISABLED:-false}" = "true" ]; then
+  exit 0
+fi
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+
+# Read tool input from stdin (JSON with file_path)
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | grep -oP '"file_path"\s*:\s*"([^"]*)"' | head -1 | sed 's/.*"\([^"]*\)"/\1/' 2>/dev/null || echo "")
+
+if [ -z "$FILE_PATH" ]; then
+  # Try alternate JSON key names
+  FILE_PATH=$(echo "$INPUT" | grep -oP '"filePath"\s*:\s*"([^"]*)"' | head -1 | sed 's/.*"\([^"]*\)"/\1/' 2>/dev/null || echo "")
+fi
+
+if [ -z "$FILE_PATH" ]; then
+  exit 0
+fi
+
+# Check if inside project directory
+case "$FILE_PATH" in
+  "$PROJECT_DIR"*) ;; # Inside project, OK
+  /*)
+    echo "SDD SCOPE WARNING: Edit to file outside project directory: $FILE_PATH" >&2
+    exit 2
+    ;;
+esac
+
+# Check git status for unrelated modifications
+if command -v git &>/dev/null && [ -d "$PROJECT_DIR/.git" ]; then
+  MODIFIED_COUNT=$(cd "$PROJECT_DIR" && git diff --name-only 2>/dev/null | wc -l)
+  if [ "$MODIFIED_COUNT" -gt 10 ]; then
+    echo "SDD SCOPE WARNING: $MODIFIED_COUNT files modified — possible scope creep. Review changes with 'git diff --stat'" >&2
+    exit 2
+  fi
+fi
+
+exit 0

package/hooks/scripts/session-init.sh

@@ -0,0 +1,44 @@
+#!/bin/bash
+# SDD Session Initialization Hook
+# Loads .sdd.yaml config, sets environment variables, checks yolo flag
+
+set -euo pipefail
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+ENV_FILE="${CLAUDE_ENV_FILE:-}"
+CONFIG_FILE="$PROJECT_DIR/.sdd.yaml"
+YOLO_FLAG="$PROJECT_DIR/.sdd-yolo"
+
+# Check for yolo mode
+if [ -f "$YOLO_FLAG" ]; then
+  echo "SDD: YOLO mode active — all guardrails disabled" >&2
+  # Remove yolo flag (auto-clears on session start)
+  rm -f "$YOLO_FLAG"
+  if [ -n "$ENV_FILE" ]; then
+    echo "GUARDRAILS_DISABLED=true" >> "$ENV_FILE"
+    echo "SDD_YOLO_CLEARED=true" >> "$ENV_FILE"
+  fi
+  exit 0
+fi
+
+# Set defaults
+if [ -n "$ENV_FILE" ]; then
+  echo "GUARDRAILS_DISABLED=false" >> "$ENV_FILE"
+  echo "SDD_ACTIVE=true" >> "$ENV_FILE"
+fi
+
+# Check for config file
+if [ -f "$CONFIG_FILE" ]; then
+  echo "SDD: Config loaded from $CONFIG_FILE" >&2
+  if [ -n "$ENV_FILE" ]; then
+    echo "SDD_CONFIG_FOUND=true" >> "$ENV_FILE"
+  fi
+else
+  echo "SDD: No .sdd.yaml found — using defaults" >&2
+  if [ -n "$ENV_FILE" ]; then
+    echo "SDD_CONFIG_FOUND=false" >> "$ENV_FILE"
+  fi
+fi
+
+echo "SDD: Session initialized — guardrails active" >&2
+exit 0

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@abdullah-alnahas/claude-sdd",
+  "version": "0.1.0",
+  "description": "Spec-Driven Development discipline system for Claude Code — behavioral guardrails, spec-first development, architecture awareness, TDD enforcement, iterative execution loops",
+  "keywords": [
+    "claude-code-plugin",
+    "sdd",
+    "spec-driven-development",
+    "tdd",
+    "guardrails",
+    "architecture",
+    "iterative-execution"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/abdullah-alnahas/claude-sdd.git"
+  },
+  "author": "abdullah-alnahas"
+}

package/scripts/verify-commands.sh

@@ -0,0 +1,59 @@
+#!/bin/bash
+# SDD Self-Test: Verify commands structure
+set -euo pipefail
+
+PLUGIN_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+PASS=0
+FAIL=0
+
+check() {
+  local desc="$1"
+  shift
+  if "$@" >/dev/null 2>&1; then
+    echo "  ✓ $desc"
+    PASS=$((PASS + 1))
+  else
+    echo "  ✗ $desc"
+    FAIL=$((FAIL + 1))
+  fi
+}
+
+echo "SDD Command Verification"
+echo "────────────────────────"
+
+COMMANDS=("sdd-guardrails" "sdd-yolo" "sdd-phase" "sdd-review" "sdd-adopt" "sdd-execute" "sdd-autopilot")
+
+for cmd in "${COMMANDS[@]}"; do
+  echo ""
+  echo "Command: /$cmd"
+  CMD_FILE="$PLUGIN_DIR/commands/$cmd.md"
+
+  check "File exists" test -f "$CMD_FILE"
+  check "Has frontmatter" grep -q "^---" "$CMD_FILE"
+  check "Has name field" grep -q "^name:" "$CMD_FILE"
+  check "Has description field" grep -q "^description:" "$CMD_FILE"
+  check "Is non-empty (>100 chars)" test "$(wc -c < "$CMD_FILE")" -gt 100
+done
+
+# Check for duplicate command names
+echo ""
+echo "Uniqueness:"
+NAMES=$(grep -h "^name:" "$PLUGIN_DIR/commands/"*.md | sort)
+UNIQUE_NAMES=$(echo "$NAMES" | sort -u)
+check "All command names are unique" test "$(echo "$NAMES" | wc -l)" -eq "$(echo "$UNIQUE_NAMES" | wc -l)"
+
+# Check agents referenced by commands exist
+echo ""
+echo "Agent references:"
+AGENTS=("critic" "simplifier" "spec-compliance" "security-reviewer")
+for agent in "${AGENTS[@]}"; do
+  check "Agent: $agent.md exists" test -f "$PLUGIN_DIR/agents/$agent.md"
+done
+
+echo ""
+echo "────────────────────────"
+echo "Results: $PASS passed, $FAIL failed"
+
+if [ "$FAIL" -gt 0 ]; then
+  exit 1
+fi

package/scripts/verify-hooks.sh

@@ -0,0 +1,74 @@
+#!/bin/bash
+# SDD Self-Test: Verify hooks configuration and scripts
+set -euo pipefail
+
+PLUGIN_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+PASS=0
+FAIL=0
+
+check() {
+  local desc="$1"
+  shift
+  if "$@" >/dev/null 2>&1; then
+    echo "  ✓ $desc"
+    PASS=$((PASS + 1))
+  else
+    echo "  ✗ $desc"
+    FAIL=$((FAIL + 1))
+  fi
+}
+
+echo "SDD Hook Verification"
+echo "─────────────────────"
+
+# Check hooks.json exists and is valid JSON
+echo ""
+echo "hooks.json:"
+check "File exists" test -f "$PLUGIN_DIR/hooks/hooks.json"
+check "Valid JSON" python3 -c "import json; json.load(open('$PLUGIN_DIR/hooks/hooks.json'))"
+check "Has hooks wrapper" python3 -c "
+import json
+d = json.load(open('$PLUGIN_DIR/hooks/hooks.json'))
+assert 'hooks' in d, 'Missing hooks key'
+"
+check "Has SessionStart hook" python3 -c "
+import json
+d = json.load(open('$PLUGIN_DIR/hooks/hooks.json'))
+assert 'SessionStart' in d['hooks']
+"
+check "Has UserPromptSubmit hook" python3 -c "
+import json
+d = json.load(open('$PLUGIN_DIR/hooks/hooks.json'))
+assert 'UserPromptSubmit' in d['hooks']
+"
+check "Has PostToolUse hook" python3 -c "
+import json
+d = json.load(open('$PLUGIN_DIR/hooks/hooks.json'))
+assert 'PostToolUse' in d['hooks']
+"
+check "Has Stop hook" python3 -c "
+import json
+d = json.load(open('$PLUGIN_DIR/hooks/hooks.json'))
+assert 'Stop' in d['hooks']
+"
+
+# Check scripts exist and are executable
+echo ""
+echo "Hook scripts:"
+check "session-init.sh exists" test -f "$PLUGIN_DIR/hooks/scripts/session-init.sh"
+check "post-edit-review.sh exists" test -f "$PLUGIN_DIR/hooks/scripts/post-edit-review.sh"
+check "session-init.sh is executable or bash-runnable" bash -n "$PLUGIN_DIR/hooks/scripts/session-init.sh"
+check "post-edit-review.sh is executable or bash-runnable" bash -n "$PLUGIN_DIR/hooks/scripts/post-edit-review.sh"
+
+# Test session-init.sh runs without error
+echo ""
+echo "Script execution:"
+check "session-init.sh runs without error" bash "$PLUGIN_DIR/hooks/scripts/session-init.sh"
+
+echo ""
+echo "─────────────────────"
+echo "Results: $PASS passed, $FAIL failed"
+
+if [ "$FAIL" -gt 0 ]; then
+  exit 1
+fi

package/scripts/verify-skills.sh

@@ -0,0 +1,72 @@
+#!/bin/bash
+# SDD Self-Test: Verify skills structure and content
+set -euo pipefail
+
+PLUGIN_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+PASS=0
+FAIL=0
+
+check() {
+  local desc="$1"
+  shift
+  if "$@" >/dev/null 2>&1; then
+    echo "  ✓ $desc"
+    PASS=$((PASS + 1))
+  else
+    echo "  ✗ $desc"
+    FAIL=$((FAIL + 1))
+  fi
+}
+
+echo "SDD Skill Verification"
+echo "──────────────────────"
+
+SKILLS=("guardrails" "spec-first" "architecture-aware" "tdd-discipline" "iterative-execution")
+
+for skill in "${SKILLS[@]}"; do
+  echo ""
+  echo "Skill: $skill"
+  SKILL_DIR="$PLUGIN_DIR/skills/$skill"
+
+  check "Directory exists" test -d "$SKILL_DIR"
+  check "SKILL.md exists" test -f "$SKILL_DIR/SKILL.md"
+  check "SKILL.md has frontmatter" grep -q "^---" "$SKILL_DIR/SKILL.md"
+  check "SKILL.md has name field" grep -q "^name:" "$SKILL_DIR/SKILL.md"
+  check "SKILL.md has description field" grep -q "^description:" "$SKILL_DIR/SKILL.md"
+
+  # Check SKILL.md body is under 3000 words
+  if [ -f "$SKILL_DIR/SKILL.md" ]; then
+    WORD_COUNT=$(wc -w < "$SKILL_DIR/SKILL.md")
+    check "SKILL.md under 3000 words ($WORD_COUNT)" test "$WORD_COUNT" -lt 3000
+  fi
+
+  # Check references exist
+  if [ -d "$SKILL_DIR/references" ]; then
+    REF_COUNT=$(find "$SKILL_DIR/references" -name "*.md" -type f | wc -l)
+    check "Has reference files ($REF_COUNT found)" test "$REF_COUNT" -gt 0
+
+    # Check no empty reference files
+    while IFS= read -r ref; do
+      SIZE=$(wc -c < "$ref")
+      check "$(basename "$ref") is non-empty" test "$SIZE" -gt 10
+    done < <(find "$SKILL_DIR/references" -name "*.md" -type f)
+  fi
+done
+
+# Check templates
+echo ""
+echo "Templates:"
+TEMPLATE_DIR="$PLUGIN_DIR/skills/spec-first/references/templates"
+check "Templates directory exists" test -d "$TEMPLATE_DIR"
+TEMPLATES=("app-description.md" "architecture.md" "stack.md" "roadmap.md" "behavior-spec.md" "test-plan.md" "retrospective.md")
+for tmpl in "${TEMPLATES[@]}"; do
+  check "Template: $tmpl exists" test -f "$TEMPLATE_DIR/$tmpl"
+done
+
+echo ""
+echo "──────────────────────"
+echo "Results: $PASS passed, $FAIL failed"
+
+if [ "$FAIL" -gt 0 ]; then
+  exit 1
+fi

package/skills/architecture-aware/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: Architecture Awareness
+description: >
+  Provides architecture consciousness during development — integration patterns, anti-patterns, and ADR guidance.
+  Use when designing systems, discussing architecture, integration, patterns, structure, or organization.
+version: 1.0.0
+---
+
+# Architecture Awareness
+
+You maintain architectural consciousness throughout development. Every code change exists within an architectural context — respect it.
+
+## Core Principles
+
+### Fit the Existing Architecture
+Before proposing any pattern, understand what's already there. Don't introduce a new pattern when the codebase already has an established one that works.
+
+### Justify Pattern Choices
+Every pattern has trade-offs. State the specific benefit for THIS codebase, not abstract "best practice" arguments.
+
+### Record Significant Decisions
+If a decision is hard to reverse or affects multiple components, it deserves an ADR (Architecture Decision Record).
+
+## When to Engage
+
+- User asks "how should I structure this?"
+- Adding a new component to an existing system
+- Introducing a new technology or pattern
+- Changing how components communicate
+- Anything that touches 3+ modules/services
+
+## What to Check
+
+1. **Existing patterns**: What patterns does the codebase already use?
+2. **Integration points**: How will new code connect to existing code?
+3. **Coupling**: Are we creating tight coupling between components?
+4. **Consistency**: Does this follow or violate established conventions?
+
+## References
+
+See: `references/integration-patterns.md`
+See: `references/anti-patterns.md`
+See: `references/adr-guide.md`

package/skills/architecture-aware/references/adr-guide.md

@@ -0,0 +1,53 @@
+# Architecture Decision Records (ADRs)
+
+## When to Write an ADR
+
+Write an ADR when:
+- The decision is hard to reverse
+- Multiple valid alternatives exist
+- The decision affects multiple components
+- Future developers will wonder "why did they do it this way?"
+
+Don't write an ADR for:
+- Obvious choices (using the project's existing language)
+- Easily reversible decisions
+- Style preferences
+
+## Format
+
+```markdown
+# ADR-[NUMBER]: [Title]
+
+**Date**: [Date]
+**Status**: [Proposed | Accepted | Deprecated | Superseded by ADR-X]
+
+## Context
+[What situation or problem prompted this decision?]
+
+## Decision
+[What did we decide to do?]
+
+## Alternatives Considered
+[What other options were evaluated? Why were they rejected?]
+
+## Consequences
+[What are the positive and negative results of this decision?]
+```
+
+## Storage
+
+Store ADRs in `docs/adr/` or `specs/adr/`:
+```
+docs/adr/
+├── 0001-use-postgresql.md
+├── 0002-event-driven-notifications.md
+└── 0003-monorepo-structure.md
+```
+
+## Tips
+
+- Keep ADRs short (1 page max)
+- Focus on the WHY, not the HOW
+- Include rejected alternatives — they're as valuable as the choice
+- Link to relevant specs or behavior documents
+- ADRs are immutable — supersede, don't edit

package/skills/architecture-aware/references/anti-patterns.md

@@ -0,0 +1,41 @@
+# Architectural Anti-Patterns
+
+## 1. Direct DB Coupling Across Boundaries
+**Problem**: Service A queries Service B's database directly.
+**Why it's bad**: Changes to B's schema break A. No encapsulation.
+**Fix**: B exposes an API. A calls the API.
+
+## 2. Mega Object / Mega Module
+**Problem**: One module/class does everything.
+**Why it's bad**: Impossible to understand, test, or modify safely.
+**Fix**: Extract cohesive responsibilities into focused modules.
+
+## 3. Distributed Monolith
+**Problem**: Microservices that must be deployed together and share everything.
+**Why it's bad**: All the complexity of distributed systems with none of the benefits.
+**Fix**: Either make them truly independent or merge them back into a monolith.
+
+## 4. Synchronous Chains
+**Problem**: A calls B calls C calls D synchronously. Any failure breaks the chain.
+**Why it's bad**: Latency multiplies. Availability decreases multiplicatively.
+**Fix**: Use async processing. Break the chain with events or queues.
+
+## 5. Missing Correlation IDs
+**Problem**: Requests flow through multiple services with no way to trace them.
+**Why it's bad**: Debugging production issues becomes nearly impossible.
+**Fix**: Generate a correlation ID at the entry point, pass it through all calls.
+
+## 6. Premature Microservices
+**Problem**: Splitting into services before understanding domain boundaries.
+**Why it's bad**: Wrong boundaries are expensive to fix. Data consistency becomes hard.
+**Fix**: Start monolithic. Split when you have clear, proven boundaries.
+
+## 7. Shared Mutable State
+**Problem**: Multiple components read/write the same data without coordination.
+**Why it's bad**: Race conditions. Inconsistent state. Hard to reproduce bugs.
+**Fix**: Single owner per piece of state. Others request changes through the owner.
+
+## 8. Copy-Paste Integration
+**Problem**: Duplicating code across services instead of sharing or abstracting.
+**Why it's bad**: Bug fixes need to be applied N times. Drift is inevitable.
+**Fix**: Shared library for truly shared logic. Accept some duplication for loose coupling.