feat(commands): add /diagnose interactive troubleshooting assistant v3.0.4

- New diagnose.md command with bilingual support (FR/EN) - 12 problem categories: permissions, MCP, config, performance, installation - Auto-fetches latest guide from GitHub for up-to-date troubleshooting - Integrates with audit-scan.sh --json for environment scanning - Structured output: diagnostic → solution → template → reference Updated: README, examples/README, CHANGELOG, cheatsheet, guide (section 10.4) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-13 08:41:54 +01:00 · 2026-01-13 08:41:54 +01:00 · 0e04c51a5d
commit 0e04c51a5d
parent 5830990e9b
6 changed files with 297 additions and 5 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@ -6,6 +6,87 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).

 ## [Unreleased]

+## [3.0.4] - 2026-01-13
+
+### Added
+- **examples/commands/diagnose.md** - Interactive troubleshooting assistant (NEW)
+  - Bilingual support (FR/EN) with automatic language detection
+  - 12 problem categories: permissions, MCP servers, config, performance, installation, agents/skills
+  - Auto-fetches latest guide from GitHub for up-to-date troubleshooting data
+  - Integrates with `audit-scan.sh --json` for environment scanning
+  - Structured diagnostic output: root cause → solution → template → reference
+  - Common patterns documented: repeated permission prompts, MCP not found, context saturation
+  - Usage: Copy to `~/.claude/commands/` then invoke with `/diagnose`
+
+### Changed
+- **README.md** - Added `/diagnose` to commands table and navigation
+- **examples/README.md** - Added `/diagnose` to commands index
+- **cheatsheet-en.md** - Version bump to 3.0.4
+
+### Stats
+- 1 new file created (diagnose.md, ~210 lines)
+- 3 files modified (README.md, examples/README.md, cheatsheet-en.md)
+- Focus on self-service troubleshooting for common Claude Code issues
+
+## [3.0.3] - 2026-01-13
+
+### Enhanced
+- **audit-scan.sh v2.0** - Major improvements based on community feedback (2 test projects)
+  - **P0.1: MCP Detection globale** - Now detects both project-specific AND global MCPs from `~/.claude.json`
+    - Previously only checked `projects[path].mcpServers`, now also checks top-level `mcpServers`
+    - Shows separate counts: project MCPs vs global MCPs with their sources
+  - **P0.2: MCP documented vs configured** - New feature detecting MCPs mentioned in CLAUDE.md but not actually configured
+    - Scans CLAUDE.md files for known MCPs (serena, context7, sequential, playwright, morphllm, magic, filesystem)
+    - Warns when MCP is documented but missing from config: "Documented but NOT configured: serena"
+    - Helps catch configuration drift
+  - **P1.1: +35 integrations detected** - Expanded from ~25 to ~60 packages
+    - Chat/Communication: TalkJS, Knock, Stream
+    - Maps: MapLibre, Mapbox, Google Maps
+    - File Upload: Bytescale, UploadThing, Cloudinary
+    - Admin: Forest Admin, Refine
+    - Validation: Zod, Yup, Valibot
+    - UI Libraries: Chakra UI, Material UI, DaisyUI, Mantine
+    - Database providers: Neon, PlanetScale, Vercel Postgres, Upstash, Turso
+    - Analytics: Vercel Analytics, Mixpanel, Hotjar, Amplitude
+    - Feature flags: Vercel Flags, LaunchDarkly
+    - Forms: React Hook Form, Formik
+    - Auth: Kinde
+    - Payments: LemonSqueezy
+    - AI: Vercel AI SDK
+    - CMS: Payload CMS
+    - State: Jotai
+  - **P1.2: Test framework warning** - Now explicitly warns when no test framework detected
+    - Checks package.json deps, config files (jest.config.*, vitest.config.*), and test file patterns
+    - Shows ❌ "No test framework detected" in quality patterns
+  - **P1.3: MCP Recommendations** - Context-aware suggestions based on detected stack
+    - context7 recommended for modern frameworks (Next.js, React, Vue, etc.)
+    - sequential-thinking for complex architectures (with DB or NestJS/Next.js)
+    - playwright for projects without E2E testing
+    - serena for TypeScript projects
+  - **P2.1: SSoT detection élargie** - Now searches for @refs in codebase even without CLAUDE.md
+    - If >5 files contain `@*.md` references, considers SSoT pattern adopted
+  - **P2.2: shadcn/ui detection** - Special case handling (not in package.json)
+    - Detects presence of `components/ui/` or `src/components/ui/` folders
+  - **JSON output enhanced** with new fields:
+    - `quality.has_test_framework` (boolean)
+    - `mcp.project_servers`, `mcp.global_servers` (separated)
+    - `mcp.documented`, `mcp.missing` (doc vs config gap)
+    - `mcp.recommendations` (stack-based suggestions)
+  - **Human output enhanced**:
+    - New "🔌 MCP SERVERS" section with project/global breakdown
+    - Warning for documented but unconfigured MCPs
+    - Recommendations displayed with 💡 icon
+
+### Fixed
+- **audit-scan.sh** - `ALL_DEPS` unbound variable error when running outside Node.js projects
+  - Initialized `ALL_DEPS=""` before conditional blocks
+
+### Stats
+- 1 file modified (audit-scan.sh, ~200 lines added/modified)
+- Integration detection improved from ~25 to ~60 packages
+- MCP detection now covers all configuration locations
+- Based on feedback from Native Spaces (venue booking) and Méthode Aristote (EdTech) projects
+
 ## [3.0.2] - 2026-01-12

 ### Added
--- a/README.md
+++ b/README.md
@ -68,6 +68,7 @@ claude
 | Want personalized recommendations | [Deep Audit](#-deep-audit-personalized-recommendations) | 30 sec |
 | Want to test your knowledge | [Knowledge Quiz](#-knowledge-quiz) | 10 min |
 | Want a guided tour | [Personalized Onboarding](./personalized-onboarding-prompt.md) | ~15 min |
+| Having issues with Claude Code | [/diagnose command](./examples/commands/diagnose.md) | ~2 min |

 ### ⚡ Audit Your Setup

@ -326,6 +327,7 @@ Copy-paste templates from [`examples/`](./examples/) for immediate use:
 | [/release-notes](./examples/commands/release-notes.md) | Generate release notes (3 formats) | CHANGELOG + PR body + Slack |
 | [/sonarqube](./examples/commands/sonarqube.md) | Analyze quality issues | Executive summary, action plans |
 | [/commit](./examples/commands/commit.md) | Conventional commits | Follows team conventions |
+| [/diagnose](./examples/commands/diagnose.md) | Interactive troubleshooting | Bilingual FR/EN, auto-scans environment |

 ### Security & Automation Hooks

@ -476,7 +478,7 @@ If this guide saved you time, helped you master Claude Code, or inspired your wo

 ---

-*Version 3.0.2 | January 2026 | Crafted with Claude*
+*Version 3.0.4 | January 2026 | Crafted with Claude*

 <!-- SEO Keywords -->
 <!-- claude code, claude code tutorial, anthropic cli, ai coding assistant, claude code mcp,
--- a/cheatsheet-en.md
+++ b/cheatsheet-en.md
@ -6,7 +6,7 @@

 **Written with**: Claude (Anthropic)

-**Version**: 3.0.2 | **Last Updated**: January 2026
+**Version**: 3.0.4 | **Last Updated**: January 2026

 ---

@ -378,4 +378,4 @@ where.exe claude; claude doctor; claude mcp list

 **Author**: Florian BRUNIAUX | [@Méthode Aristote](https://methode-aristote.fr) | Written with Claude

-*Last updated: January 2026 | Version 3.0.2*
+*Last updated: January 2026 | Version 3.0.4*
--- a/english-ultimate-claude-code-guide.md
+++ b/english-ultimate-claude-code-guide.md
@ -10,7 +10,7 @@

 **Last updated**: January 2026

-**Version**: 3.0.2
+**Version**: 3.0.4

 ---

@ -7930,6 +7930,8 @@ claude --add-dir ../shared-lib ../utils ../config

 ## 10.4 Troubleshooting

+> **Interactive Troubleshooting**: Use the `/diagnose` command for guided, interactive problem-solving. It auto-scans your environment and provides targeted solutions. See [examples/commands/diagnose.md](./examples/commands/diagnose.md).
+
 ### Quick Diagnostic Guide

 Use this symptom-based guide for rapid issue identification and resolution:
@ -9048,4 +9050,4 @@ Thumbs.db

 **Contributions**: Issues and PRs welcome.

-**Last updated**: January 2026 | **Version**: 3.0.2
+**Last updated**: January 2026 | **Version**: 3.0.4
--- a/examples/README.md
+++ b/examples/README.md
@ -63,6 +63,7 @@ Ready-to-use templates for Claude Code configuration.
 | [sonarqube.md](./commands/sonarqube.md) | `/sonarqube` | Analyze SonarCloud quality issues for PRs |
 | [generate-tests.md](./commands/generate-tests.md) | `/generate-tests` | Test generation |
 | [git-worktree.md](./commands/git-worktree.md) | `/git-worktree` | Isolated git worktree setup |
+| [diagnose.md](./commands/diagnose.md) | `/diagnose` | Interactive troubleshooting assistant (FR/EN) |

 ### Hooks
 | File | Event | Purpose |
--- a/examples/commands/diagnose.md
+++ b/examples/commands/diagnose.md
@ -0,0 +1,206 @@
+# Claude Code Diagnostic Assistant
+
+Interactive troubleshooting assistant for Claude Code issues. Supports FR/EN.
+
+## Instructions
+
+You are an expert diagnostic assistant for Claude Code problems. Your role is to identify issues and provide targeted solutions.
+
+### Step 1: Language Detection
+
+Detect the user's language from their input. If ambiguous, ask:
+> "FR or EN? / Français ou English?"
+
+Respond in the detected language throughout the session.
+
+### Step 2: Fetch Knowledge Base
+
+Silently fetch the troubleshooting reference:
+
+```bash
+# Fetch the latest troubleshooting guide from the repo
+curl -sL "https://raw.githubusercontent.com/flobby41/claude-code-ultimate-guide/main/english-ultimate-claude-code-guide.md" | head -n 3000
+```
+
+Use Section 10.4 (Troubleshooting) as your primary reference.
+
+### Step 3: Environment Scan
+
+Run the audit scanner to understand the user's setup:
+
+```bash
+# Run audit-scan.sh in JSON mode for structured data
+curl -sL "https://raw.githubusercontent.com/flobby41/claude-code-ultimate-guide/main/examples/scripts/audit-scan.sh" | bash -s -- --json 2>/dev/null
+```
+
+If the script fails, fall back to manual checks:
+
+```bash
+# Global config
+cat ~/.claude/settings.json 2>/dev/null || echo "No global settings"
+
+# Project config
+cat .claude/settings.json 2>/dev/null || echo "No project settings"
+
+# CLAUDE.md files
+ls -la CLAUDE.md .claude/CLAUDE.md ~/.claude/CLAUDE.md 2>/dev/null
+
+# MCP config
+cat ~/.claude/mcp.json 2>/dev/null || echo "No MCP config"
+```
+
+### Step 4: Present Categories
+
+If the user hasn't described a specific problem, present these categories:
+
+---
+
+**Permissions**
+1. Repeated permission prompts despite settings.json / Demandes répétées malgré settings.json
+2. Actions blocked by hooks / Actions bloquées par hooks
+
+**MCP Servers**
+3. Server not found / connection failed / Serveur non trouvé
+4. MCP tool not recognized / Outil MCP non reconnu
+
+**Configuration**
+5. settings.json ignored / settings.json ignoré
+6. CLAUDE.md not read / CLAUDE.md non lu
+7. Hooks not triggering / Hooks ne se déclenchent pas
+
+**Performance**
+8. Context saturated (>75%) / Contexte saturé
+9. Slow responses / Réponses lentes
+
+**Installation**
+10. Installation/update errors / Erreurs installation
+
+**Other**
+11. Agents/Skills issues / Problèmes agents/skills
+12. Other → describe freely / Autre → décrivez
+
+---
+
+### Step 5: Correlate & Diagnose
+
+Cross-reference:
+- User's symptom/category choice
+- Environment scan results
+- Knowledge base patterns
+
+Ask targeted follow-up questions if the cause is ambiguous. Examples:
+- "What exact error message do you see?"
+- "When did this start happening?"
+- "Did you recently update Claude Code or change configuration?"
+
+### Step 6: Prescription
+
+Format your response as:
+
+---
+
+### Diagnostic
+
+[Root cause identified based on scan + symptom correlation]
+
+### Solution
+
+1. [Step 1 - most critical action]
+2. [Step 2]
+3. [Step 3 if needed]
+
+### Template (if applicable)
+
+Link to relevant template:
+- Config: `https://github.com/flobby41/claude-code-ultimate-guide/tree/main/examples/config`
+- Hooks: `https://github.com/flobby41/claude-code-ultimate-guide/tree/main/examples/hooks`
+
+### Reference
+
+Section X.Y of the guide: [Brief description]
+`https://github.com/flobby41/claude-code-ultimate-guide`
+
+---
+
+## Common Patterns
+
+### Pattern: Repeated Permission Prompts
+
+**Symptoms**: Claude keeps asking for permission despite settings.json configuration
+
+**Likely causes**:
+1. Pattern mismatch (e.g., `npm *` but using `pnpm`)
+2. Wrong file location (global vs project)
+3. Malformed JSON syntax
+
+**Quick diagnostic**:
+```bash
+# Check what's actually in settings
+cat ~/.claude/settings.json | jq '.permissions.allow'
+```
+
+### Pattern: MCP Server Not Found
+
+**Symptoms**: "Tool not found" or "Server not responding"
+
+**Likely causes**:
+1. Server not installed globally
+2. Wrong path in mcp.json
+3. Missing environment variables
+
+**Quick diagnostic**:
+```bash
+# Check MCP config
+cat ~/.claude/mcp.json | jq '.mcpServers'
+
+# Check if server binary exists
+which mcp-server-sequential
+```
+
+### Pattern: Context Saturation
+
+**Symptoms**: Claude loses context, forgets earlier discussion
+
+**Likely causes**:
+1. Large files read into context
+2. Long conversation without summary
+3. Too many parallel operations
+
+**Quick diagnostic**: Check context usage in Claude Code status bar
+
+## Examples
+
+### Example 1: Permission Pattern Mismatch
+
+**User**: "Claude keeps asking me to approve `pnpm install`"
+
+**Scan reveals**:
+```json
+{
+  "permissions": {
+    "allow": ["Bash(npm *)"]
+  }
+}
+```
+
+**Diagnosis**: Pattern `npm *` doesn't match `pnpm` commands.
+
+**Solution**:
+1. Edit `~/.claude/settings.json`
+2. Add `"Bash(pnpm *)"` to allow array
+3. Restart Claude Code session
+
+### Example 2: Hooks Not Triggering
+
+**User**: "My pre-commit hook doesn't run"
+
+**Scan reveals**: No hooks directory or wrong event name
+
+**Diagnosis**: Hook file naming or location issue.
+
+**Solution**:
+1. Verify hook is in `.claude/hooks/` or `~/.claude/hooks/`
+2. Check filename matches event: `PreToolUse.sh`, `PostToolUse.sh`
+3. Ensure hook is executable: `chmod +x hook.sh`
+
+$ARGUMENTS