Docs monitor changes

.github/workflows/claude-code-review.yml

@@ -17,14 +17,14 @@ jobs:
     #   github.event.pull_request.user.login == 'external-contributor' ||
     #   github.event.pull_request.user.login == 'new-developer' ||
     #   github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR'
-    
+
     runs-on: ubuntu-latest
     permissions:
       contents: read
       pull-requests: read
       issues: read
       id-token: write
-    
+
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
@@ -46,12 +46,12 @@ jobs:
             - Performance considerations
             - Security concerns
             - Test coverage
-            
+
             Use the repository's CLAUDE.md for guidance on style and conventions. Be constructive and helpful in your feedback.
 
             Use `gh pr comment` with your Bash tool to leave your review as a comment on the PR.
-          
+
           # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
-          # or https://docs.claude.com/en/docs/claude-code/sdk#command-line for available options
+          # or https://docs.claude.com/en/docs/claude-code/cli-reference for available options
           claude_args: '--allowed-tools "Bash(gh issue view:*),Bash(gh search:*),Bash(gh issue list:*),Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh pr list:*)"'
 

.github/workflows/claude.yml

@@ -35,7 +35,7 @@ jobs:
         uses: anthropics/claude-code-action@v1
         with:
           claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
-          
+
           # This is an optional setting that allows Claude to read CI results on PRs
           additional_permissions: |
             actions: read
@@ -45,6 +45,6 @@ jobs:
 
           # Optional: Add claude_args to customize behavior and configuration
           # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
-          # or https://docs.claude.com/en/docs/claude-code/sdk#command-line for available options
-          # claude_args: '--model claude-opus-4-1-20250805 --allowed-tools Bash(gh pr:*)'
+          # or https://docs.claude.com/en/docs/claude-code/cli-reference for available options
+          # claude_args: '--allowed-tools Bash(gh pr:*)'
 

.github/workflows/smart-docs-monitor.yml

@@ -2,13 +2,13 @@ name: Smart Docs Monitor
 
 on:
   schedule:
-    - cron: '0 */6 * * *'  # Run every 6 hours
+    - cron: '0 0 * * *'  # Run every 24 hours at midnight UTC
   workflow_dispatch:
     inputs:
       hours_back:
         description: 'Hours to look back for merged PRs'
         required: false
-        default: '6'
+        default: '24'
 
 permissions:
   contents: read
@@ -36,7 +36,7 @@ jobs:
               .split('\n')
               .filter(line => line.trim() && !line.startsWith('#'));
 
-            const hoursBack = parseInt('${{ github.event.inputs.hours_back || '6' }}');
+            const hoursBack = parseInt('${{ github.event.inputs.hours_back || '24' }}');
             const since = new Date(Date.now() - hoursBack * 60 * 60 * 1000).toISOString();
 
             let batchSummary = '# Merged PRs to Review\n\n';
@@ -92,94 +92,102 @@ jobs:
         with:
           claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
           prompt: |
-            Review the merged PRs listed in `pr-batch.md` and determine which ones require documentation updates.
+            Review the merged PRs listed in `pr-batch.md` and determine which ones require documentation updates, new documentation, or removal/deprecation of existing docs.
 
             **Your Process:**
 
-            1. **Read pr-batch.md** to see all merged PRs
-
-            2. **For each PR:**
-               - Analyze the description and changes
-               - Determine if it affects user-facing features, APIs, or workflows
-
-            3. **Review our documentation:**
-               - Check /concepts directory for all conceptual documentation
-               - Check /guides-and-tutorials directory for tutorials and how-to guides
-               - Check /reference directory for API and reference documentation
-               - Read README.md
-               - Look for setup/configuration guides
-
-            4. **Output JSON for issues to create:**
-
-               For each PR needing documentation updates, create a JSON object with this structure:
+            1. **Read pr-batch.md and CLAUDE.md**
+               - Follow CLAUDE.md's Review Process and "What Requires Documentation" guidelines
+               - See all merged PRs in pr-batch.md
+
+            2. **For each PR - Fetch and analyze the full diff:**
+               - Use the Diff URL from pr-batch.md to fetch the complete PR diff (use curl or gh api)
+               - Do NOT rely only on PR titles or summaries - read the actual code changes
+               - Extract user-facing changes: new/changed/removed public APIs, endpoints, CLIs, flags, config keys, setup instructions, breaking changes, renames
+
+            3. **Classify documentation impact** (may be multiple categories per PR):
+               a) **UPDATE** existing docs (content exists but is now incorrect/outdated)
+               b) **CREATE** new documentation (feature/API is not documented anywhere)
+               c) **REMOVE or DEPRECATE** documentation (feature/API was removed or deprecated)
+
+            4. **Thoroughly search our existing documentation:**
+               - Use Grep tool to search /concepts, /guides-and-tutorials, /reference, README.md for ALL relevant terms from the diff:
+                 * Function/method names (e.g., "map-insert", "map_insert")
+                 * API endpoints (e.g., "/v2/accounts", "accounts endpoint")
+                 * CLI commands and flags (e.g., "stacks-node", "--config")
+                 * Configuration keys (e.g., "peer_host", "miner.seed")
+                 * Type/class names
+               - Try both case-sensitive and case-insensitive searches
+               - Try word variations (snake_case, kebab-case, camelCase)
+
+               **Search results determine the impact:**
+               - **If NOT found:** Propose new doc with specific path + outline/content
+               - **If found:** Identify exact files/sections that are incorrect and need updating
+               - **If PR removes/deprecates something:** List ALL references across docs and propose removal/deprecation action
+
+            5. **Look for detection keywords in the diff:**
+               - "deprecate", "remove", "delete", "drop" → Check for docs to remove/deprecate
+               - "add", "new", "introduce", "implement" → Check if docs exist; if not, flag as CREATE
+               - "breaking", "rename", "change" → Check existing docs need UPDATE
+               - "BREAKING CHANGE" in commit messages → High priority
+
+            6. **Output JSON for issues to create:**
+
+               For each PR needing documentation changes, create a JSON object with this structure:
 
                {
                  "title": "[Docs Update] [repo-name] PR #123: Brief description",
-                 "body": "## Source PR\n- Repository: [repo-name]\n- PR: #123 - [PR title]\n- URL: [PR URL]\n- Merged: [date]\n\n## What Changed\n[Clear summary of the functional changes]\n\n## Documentation Impact\n\n### Files Needing Updates\n- [ ] `/path/to/file1.md` - [What needs to change]\n- [ ] `/path/to/file2.md` - [What needs to change]\n\n## Recommended Changes\n\n### In `/path/to/file1.md`\n[Specific text to add/change with examples]\n\n## Priority\n[High/Medium/Low] - [Why]\n\n---\n*Auto-generated by docs sync monitor*",
-                 "labels": ["documentation", "auto-generated", "sync-needed", "[repo-name]", "priority-[level]"]
+                 "body": "## Source PR\n- Repository: [repo-name]\n- PR: #123 - [PR title]\n- URL: [PR URL]\n- Merged: [date]\n\n## What Changed\n[Clear user-impact summary based on the DIFF, not just the PR description]\n\n## Documentation Impact\n\n### Updates to Existing Docs\n- [ ] `/path/to/file.md` (Section: X) - [Precise change needed; e.g., update signature, add new flag, fix example]\n\n### New Docs to Create\n- [ ] `/proposed/path/new-doc.md` - Title: [Proposed H1 title]\n  **Suggested content:**\n  ```markdown\n  [Outline or initial content with examples, signatures, usage]\n  ```\n\n### Docs to Remove or Deprecate\n- [ ] `/path/to/obsolete.md` - Action: [Remove/Deprecate]\n  **Replacement:** [Link to new doc if applicable]\n  **Rationale:** [Why; cite specific diff changes]\n\n## Recommended Changes\n\n### In `/path/to/file.md`\n\n**Section: [Section name]**\n\n[Specific text to add/change with concrete examples]\n\n## Priority\n[High/Medium/Low] - [Reason]\n\n---\n*Auto-generated by docs sync monitor*",
+                 "labels": ["documentation", "auto-generated", "sync-needed", "[repo-name]", "priority-[level]", "[docs-update|docs-new|docs-remove]"]
                }
 
                **Save the output as a JSON array to a file called `issues-to-create.json`**
 
                Example:
                [
                  {
-                   "title": "[Docs Update] stacks-core PR #456: Add new Clarity function",
+                   "title": "[Docs Update] stacks-core PR #456: Add new Clarity function map-insert",
                    "body": "## Source PR\n...",
-                   "labels": ["documentation", "auto-generated", "sync-needed", "stacks-core", "priority-high"]
+                   "labels": ["documentation", "auto-generated", "sync-needed", "stacks-core", "priority-high", "docs-new"]
                  }
                ]
 
-            5. **Optimization:**
-               - Skip PRs with only internal refactoring, tests, or CI changes
-               - Group multiple PRs affecting the same doc section into one issue if appropriate
-               - Prioritize user-facing changes (API, features, setup)
-               - Be specific - don't create vague "update docs" issues
+            7. **Optimization and Quality:**
+               - Skip PRs with only internal refactoring, tests, or CI changes (follow CLAUDE.md skip list)
+               - Group multiple PRs affecting the same doc section into one issue when it makes sense
+               - Prioritize user-facing changes (APIs, features, setup, breaking changes)
+               - Be specific with file paths and sections - don't create vague "update docs" issues
+               - When uncertain about removal, prefer "deprecate with redirect" over hard delete
+               - Include concrete examples, signatures, and suggested content in recommendations
 
             **Important:**
-            - Only include PRs that genuinely need documentation updates
-            - Save the JSON array to `issues-to-create.json`
-            - If no issues are needed, save an empty array: []
+            - Only include PRs that genuinely need documentation updates/additions/removals
+            - Create GitHub issues DIRECTLY using the `gh issue create` command
+            - Do NOT create a JSON file - create issues immediately as you identify them
+            - Always fetch and read the actual PR diff - summaries are insufficient
+
+            **Creating Issues:**
+            For each PR that needs documentation, create an issue using:
+            ```bash
+            gh issue create \
+              --repo stacks-network/docs \
+              --title "[Docs Update] [repo-name] PR #123: Brief description" \
+              --body "$(cat <<'EOF'
+            ## Source PR
+            - Repository: [repo-name]
+            - PR: #123 - [PR title]
+            ...
+            EOF
+            )" \
+              --label "documentation,auto-generated,sync-needed,[repo-name],priority-[level],[docs-update|docs-new|docs-remove]"
+            ```
+
+            **Important:** Create issues in the stacks-network/docs repository.
+
+            After creating each issue, mark it as completed in your todo list before moving to the next one.
           claude_args: |
             --max-turns 40
             --model claude-sonnet-4-20250514
+            --allowed-tools "Bash(curl:*),Bash(gh:*),Grep,Read,Write,glob"
 
-      - name: Create issues from Claude analysis
-        if: steps.batch.outputs.pr_count > 0
-        uses: actions/github-script@v7
-        with:
-          github-token: ${{ secrets.GITHUB_TOKEN }}
-          script: |
-            const fs = require('fs');
-
-            if (!fs.existsSync('issues-to-create.json')) {
-              console.log('No issues file found - Claude may not have found any PRs needing docs updates');
-              return;
-            }
-
-            const content = fs.readFileSync('issues-to-create.json', 'utf8');
-            console.log('Issues file content:', content);
-
-            const issues = JSON.parse(content);
-
-            if (!Array.isArray(issues) || issues.length === 0) {
-              console.log('No issues to create');
-              return;
-            }
-
-            console.log(`Creating ${issues.length} issue(s)...`);
 
-            for (const issue of issues) {
-              try {
-                const result = await github.rest.issues.create({
-                  owner: context.repo.owner,
-                  repo: context.repo.repo,
-                  title: issue.title,
-                  body: issue.body,
-                  labels: issue.labels || []
-                });
-                console.log(`✓ Created issue #${result.data.number}: ${issue.title}`);
-              } catch (error) {
-                console.error(`✗ Failed to create issue "${issue.title}":`, error.message);
-              }
-            }

CLAUDE.md

@@ -90,6 +90,74 @@ This repository monitors merged PRs across all Stacks Network and Hiro Systems p
 - Performance optimizations that don't change APIs
 - Internal code comments or documentation in code
 
+### Detection Scenarios
+
+When analyzing PRs, classify documentation impact into three categories:
+
+#### 1. UPDATE Existing Docs
+**When:** Code changes make existing documentation incorrect or outdated.
+
+**Detection signals:**
+- Modified function signatures in public APIs
+- Changed CLI flag behavior or defaults
+- Updated configuration schema
+- Renamed types, methods, or modules
+- Changed setup/installation steps
+- Breaking changes that alter existing functionality
+
+**Example:**
+```
+PR changes `map-set` to require a third parameter `ttl`
+→ Search docs for "map-set" 
+→ Found in /concepts/clarity/language-functions.md
+→ Issue: UPDATE the signature and examples to include ttl parameter
+```
+
+#### 2. CREATE New Docs
+**When:** New functionality has zero documentation coverage.
+
+**Detection signals:**
+- New public functions, methods, or classes
+- New API endpoints
+- New CLI commands or subcommands
+- New configuration options
+- New features or capabilities
+- Keywords in diff: "add", "new", "introduce", "implement"
+
+**Example:**
+```
+PR adds new Clarity function `map-insert`
+→ Search docs for "map-insert", "map_insert"
+→ NOT FOUND in any documentation
+→ Issue: CREATE new section in /concepts/clarity/language-functions.md with signature, usage, examples
+```
+
+#### 3. REMOVE or DEPRECATE Docs
+**When:** Features are removed or deprecated but docs still reference them.
+
+**Detection signals:**
+- Removed functions, endpoints, or commands
+- Deprecated APIs with warnings
+- Deleted configuration options
+- Keywords in diff: "remove", "delete", "deprecate", "drop"
+- BREAKING CHANGE notices about removals
+
+**Example:**
+```
+PR removes legacy endpoint `/v1/accounts` (deprecated in favor of `/v2/accounts`)
+→ Search docs for "v1/accounts", "/v1/accounts"
+→ Found in /guides-and-tutorials/api-quickstart.md and /reference/api-endpoints.md
+→ Issue: REMOVE or DEPRECATE these references, add redirect note to v2 endpoint
+```
+
+**Search Strategy:**
+For each scenario, thoroughly search using multiple term variations:
+- Exact names (e.g., "map-insert")
+- Case variations (case-sensitive and case-insensitive)
+- Format variations (snake_case, kebab-case, camelCase)
+- Partial matches (e.g., "map" functions)
+- Related terms and synonyms
+
 ### Priority Levels
 
 **High Priority** (Document immediately):