feat(audit): SSoT warning + incremental suggestions prompt

Script:
- needs_ssot_refactor flag: warns if CLAUDE.md >100 lines with 0 @refs
- Red warning in human output suggesting SSoT pattern

Prompt:
- Focus on incremental improvements, not generic advice
- Stricter health score (penalize missing SSoT)
- Domain-specific quick wins only
- Improve existing CLAUDE.md instead of full rewrite
- Don't suggest duplicates of existing agents/commands

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

CHANGELOG.md

@@ -6,6 +6,25 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ## [Unreleased]
 
+## [2.9.9] - 2026-01-12
+
+### Enhanced
+- **audit-scan.sh** - SSoT refactor warning
+  - New `needs_ssot_refactor` flag: true if CLAUDE.md >100 lines with 0 @references
+  - Human output shows red warning suggesting SSoT pattern (split into @docs/)
+  - JSON output includes `needs_ssot_refactor` in quality section
+
+- **README.md** - Improved Full Audit prompt for incremental suggestions
+  - Added IMPORTANT instruction to focus on incremental improvements, not generic advice
+  - Health score now penalizes large CLAUDE.md without @refs
+  - Quick wins must be domain-specific, not generic
+  - If CLAUDE.md exists: suggest 3-5 improvements instead of full template
+  - Agents/commands suggestions must not duplicate existing ones
+
+### Stats
+- 2 files modified
+- Audit now provides targeted, incremental recommendations
+
 ## [2.9.8] - 2026-01-12
 
 ### Enhanced

README.md

@@ -127,22 +127,24 @@ $CLAUDE_MD
 Local .claude/CLAUDE.md:
 $LOCAL_CLAUDE_MD
 
-Based on ALL this context (tech stack, business domain, existing instructions), provide:
+IMPORTANT: Focus on INCREMENTAL improvements to existing setup. Don't suggest creating things that already exist. If CLAUDE.md exists, suggest specific improvements to it rather than a full rewrite.
+
+Based on ALL this context, provide:
 1. Stack Recap: runtime, framework, test runner, bundler, database, key integrations detected
-2. Health Score (0-100) with priority breakdown
-3. Findings table: Priority|Element|Status|Action
-4. Top 3 quick wins (<5 min) tailored to THIS project's domain
-5. CLAUDE.md template (~100 lines) that incorporates existing instructions + improvements
-6. Suggested agents/commands/hooks specific to THIS project's business context
-7. Ideas to leverage Claude Code for this specific domain and integrations"
+2. Health Score (0-100) - be strict: penalize missing SSoT pattern if >100 lines without @refs
+3. Findings table: Priority|Element|Status|Action (only gaps, not what exists)
+4. Top 3 quick wins (<5 min) - MUST be specific to THIS project's domain (not generic advice)
+5. If CLAUDE.md exists: list 3-5 specific improvements (not a full template). If missing: provide ~100 line template
+6. Suggested agents/commands/hooks that DON'T duplicate existing ones - check extensions count first
+7. Ideas to leverage Claude Code for this specific domain and detected integrations"
 ```
 
 **What you get**:
 - **Stack recap**: Runtime, framework, test runner, bundler, database, and key integrations auto-detected
-- Health score with prioritized findings
-- Stack-specific CLAUDE.md template (~100 lines) that builds on your existing instructions
+- Strict health score (penalizes large CLAUDE.md without @refs)
+- **Incremental improvements**: Specific fixes for YOUR setup, not generic advice
 - Domain-aware suggestions (e.g., EdTech → session planning agents, E-commerce → inventory commands)
-- Integration-aware ideas (e.g., Stripe → payment testing commands, Sentry → error monitoring hooks)
+- Non-duplicate suggestions: Only recommends agents/commands you don't already have
 
 **Want maximum depth?** Use [claude-setup-audit-prompt.md](./claude-setup-audit-prompt.md) with `claude --ultrathink`
 
@@ -385,7 +387,7 @@ If this guide saved you time, helped you master Claude Code, or inspired your wo
 
 ---
 
-*Version 2.9.8 | January 2026 | Crafted with Claude*
+*Version 2.9.9 | January 2026 | Crafted with Claude*
 
 <!-- SEO Keywords -->
 <!-- claude code, claude code tutorial, anthropic cli, ai coding assistant, claude code mcp,

claude-code-reference.yaml

@@ -3,7 +3,7 @@
 # Source: english-ultimate-claude-code-guide.md
 # Purpose: Condensed index for LLMs to quickly answer user questions about Claude Code
 
-version: "2.9.8"
+version: "2.9.9"
 updated: "2026-01"
 
 # ════════════════════════════════════════════════════════════════

english-ultimate-claude-code-guide.md

@@ -10,7 +10,7 @@
 
 **Last updated**: January 2026
 
-**Version**: 2.9.8
+**Version**: 2.9.9
 
 ---
 
@@ -9009,4 +9009,4 @@ Thumbs.db
 
 **Contributions**: Issues and PRs welcome.
 
-**Last updated**: January 2026 | **Version**: 2.9.8
+**Last updated**: January 2026 | **Version**: 2.9.9

examples/scripts/audit-scan.sh

@@ -341,8 +341,13 @@ fi
 
 # Single Source of Truth pattern
 HAS_SSOT="false"
+NEEDS_SSOT_REFACTOR="false"
 if [[ -f "./CLAUDE.md" ]]; then
   grep -qE "^@|/docs/|/conventions/" "./CLAUDE.md" 2>/dev/null && HAS_SSOT="true"
+  # Warning: large CLAUDE.md without @references should use SSoT pattern
+  if [[ $CLAUDE_MD_LINES -gt 100 && $CLAUDE_MD_REFS -eq 0 ]]; then
+    NEEDS_SSOT_REFACTOR="true"
+  fi
 fi
 
 # === OUTPUT ===
@@ -381,6 +386,7 @@ if [[ "$OUTPUT_MODE" == "json" ]]; then
   "quality": {
     "has_security_hooks": $HAS_SECURITY_HOOKS,
     "has_ssot_references": $HAS_SSOT,
+    "needs_ssot_refactor": $NEEDS_SSOT_REFACTOR,
     "claude_md_lines": $CLAUDE_MD_LINES,
     "claude_md_refs": $CLAUDE_MD_REFS
   },
@@ -432,7 +438,9 @@ else
 
   if [[ "$PROJECT_CLAUDE_MD" == "true" ]]; then
     echo -e "  ${BLUE}ℹ️${NC}  CLAUDE.md: $CLAUDE_MD_LINES lines, $CLAUDE_MD_REFS @references"
-    if [[ $CLAUDE_MD_LINES -gt 200 ]]; then
+    if [[ "$NEEDS_SSOT_REFACTOR" == "true" ]]; then
+      echo -e "    ${RED}⚠️${NC}  Large file without @refs → Consider SSoT pattern (split into @docs/)"
+    elif [[ $CLAUDE_MD_LINES -gt 200 ]]; then
       echo -e "    ${YELLOW}⚠️${NC}  Consider shortening (>200 lines)"
     fi
   fi