feat: pre-fetch doc-drift in sync-docs command

commands/sync-docs.md

@@ -54,7 +54,33 @@ const scope = scopeArg ? scopeArg.split('=')[1] : 'recent';
 const pathArg = args.find(a => !a.startsWith('--') && a !== 'report' && a !== 'apply');
 ```
 
-### Step 2: Spawn sync-docs-agent
+### Step 2: Pre-fetch repo-intel doc-drift data
+
+```javascript
+let repoIntelContext = '';
+try {
+  const { binary } = require('@agentsys/lib');
+  const fs = require('fs');
+  const path = require('path');
+  const cwd = process.cwd();
+  const stateDir = ['.claude', '.opencode', '.codex'].find(d => fs.existsSync(path.join(cwd, d))) || '.claude';
+  const mapFile = path.join(cwd, stateDir, 'repo-intel.json');
+
+  if (fs.existsSync(mapFile)) {
+    const docDrift = JSON.parse(binary.runAnalyzer(['repo-intel', 'query', 'doc-drift', '--top', '20', '--map-file', mapFile, cwd]));
+    if (docDrift.length > 0) {
+      const stale = docDrift.filter(d => d.codeCoupling === 0).map(d => d.path);
+      repoIntelContext = '\n\nRepo-intel doc-drift data (use this, do not re-scan):';
+      if (stale.length > 0) {
+        repoIntelContext += '\nDocs with ZERO code coupling (likely stale, check these first): ' + stale.join(', ');
+      }
+      repoIntelContext += '\nFull doc-drift data: ' + JSON.stringify(docDrift);
+    }
+  }
+} catch (e) { /* unavailable */ }
+```
+
+### Step 3: Spawn sync-docs-agent
 
 ```javascript
 const agentOutput = await Task({
@@ -65,11 +91,11 @@ Mode: ${mode}
 Scope: ${scope}
 ${pathArg ? `Path: ${pathArg}` : ''}
 
-Execute the sync-docs skill and return structured results.`
+Execute the sync-docs skill and return structured results.${repoIntelContext}`
 });
 ```
 
-### Step 3: Process Results
+### Step 4: Process Results
 
 Parse the structured JSON from between `=== SYNC_DOCS_RESULT ===` markers:
 
@@ -87,7 +113,7 @@ const result = parseSyncDocsResult(agentOutput);
 // result now contains: { mode, scope, validation, discovery, issues, fixes, changelog, summary }
 ```
 
-### Step 4: Apply Fixes (if apply mode)
+### Step 5: Apply Fixes (if apply mode)
 
 If mode is `apply` and fixes array is non-empty:
 
@@ -104,7 +130,7 @@ Use the Edit tool to apply each fix. Commit message: "docs: sync documentation w
 }
 ```
 
-### Step 5: Present Results
+### Step 6: Present Results
 
 ```markdown
 ## Documentation Sync ${mode === 'apply' ? 'Applied' : 'Report'}

skills/sync-docs/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: sync-docs
 description: "Sync documentation with code. Use when user asks to update docs, check docs, fix stale documentation, update changelog, or after code changes."
 version: 5.1.0
 argument-hint: "[report|apply] [--scope=all|recent|before-pr] [--include-undocumented]"
 allowed-tools: Bash(git:*), Read, Grep, Glob
 ---
 
@@ -21,6 +21,45 @@
 
 ## Quick Start - Agent Instructions
 
+### Pre-check: Ensure Repo-Intel
+
+Before starting analysis, check if the repo-intel map exists:
+
+```javascript
+const fs = require('fs');
+const path = require('path');
+
+const cwd = process.cwd();
+const stateDir = ['.claude', '.opencode', '.codex']
+  .find(d => fs.existsSync(path.join(cwd, d))) || '.claude';
+const mapFile = path.join(cwd, stateDir, 'repo-intel.json');
+
+if (!fs.existsSync(mapFile)) {
+  const response = await AskUserQuestion({
+    questions: [{
+      question: 'Generate repo-intel?',
+      description: 'No repo-intel map found. Generating one enables doc-drift detection (identifies stale docs by code coupling). Takes ~5 seconds.',
+      options: [
+        { label: 'Yes, generate it', value: 'yes' },
+        { label: 'Skip', value: 'no' }
+      ]
+    }]
+  });
+
+  if (response === 'yes' || response?.['Generate repo-intel?'] === 'yes') {
+    try {
+      const { binary } = require('@agentsys/lib');
+      const output = binary.runAnalyzer(['repo-intel', 'init', cwd]);
+      const stateDirPath = path.join(cwd, stateDir);
+      if (!fs.existsSync(stateDirPath)) fs.mkdirSync(stateDirPath, { recursive: true });
+      fs.writeFileSync(mapFile, output);
+    } catch (e) {
+      // Binary not available - proceed without
+    }
+  }
+}
+```
+
 **Step 1**: Get changed files (use Bash):
 ```bash
 # Recent changes (default scope)