From f4c3891bb77f74caff8e2f594ef09714e70245ee Mon Sep 17 00:00:00 2001
From: Avi Fenesh <aviarchi1994@gmail.com>
Date: Sun, 15 Mar 2026 18:50:05 +0200
Subject: [PATCH 1/2] feat: ask user to generate repo-intel in sync-docs skill

Prompt user when repo-intel.json is missing instead of silently
skipping doc-drift detection.
---
 skills/sync-docs/SKILL.md | 39 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/skills/sync-docs/SKILL.md b/skills/sync-docs/SKILL.md
index 3bb99d4..e61e83c 100644
--- a/skills/sync-docs/SKILL.md
+++ b/skills/sync-docs/SKILL.md
@@ -21,6 +21,45 @@ const includeUndocumented = args.includes('--include-undocumented');
 
 ## 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)

From d3ae357b43d1f53dc76cd55667f2945cd6a0f26b Mon Sep 17 00:00:00 2001
From: Avi Fenesh <aviarchi1994@gmail.com>
Date: Sun, 15 Mar 2026 19:21:37 +0200
Subject: [PATCH 2/2] feat: pre-fetch repo-intel doc-drift in sync-docs command

Queries doc-drift before spawning sync-docs-agent, passes stale
doc paths directly in the agent prompt.
---
 commands/sync-docs.md | 36 +++++++++++++++++++++++++++++++-----
 1 file changed, 31 insertions(+), 5 deletions(-)

diff --git a/commands/sync-docs.md b/commands/sync-docs.md
index 6ecf0db..4d0d90f 100644
--- a/commands/sync-docs.md
+++ b/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'}