docNerd is a system that monitors pull requests (PRs) in a source repository and creates corresponding documentation PRs in a target documentation repository when invoked via comment. A user comments on a source PR (e.g., @docNerd, doc for core/v7.1) to request documentation; docNerd uses Claude to generate or update docs, then opens a PR on the specified branch in the docs repo and replies with the link.

• Automation: Reduce manual effort of keeping docs in sync with code changes
• Traceability: Link documentation updates to the source PRs that triggered them
• Control: Give the user full control over documentation style, structure, and rules
• Reliability: Produce consistent, high-quality documentation that follows configurable conventions

• Detecting comment triggers on source PRs (e.g., @docNerd, doc for <branch>)
• Validating that the requested docs branch exists in the target repository
• Analyzing PR content (files changed, commit messages, descriptions) to determine documentation impact
• Generating and editing documentation using Claude (LLM), guided by user-defined rules
• Creating new docs and modifying existing docs to reflect source changes
• Opening PRs in a target MkDocs + Mike documentation repository on the correct version branch
• Replying to the source PR with status updates and the docs PR link
• Configurable documentation rules and conventions

• Multi-repo source → single docs repo (could be added later)
• Real-time collaboration or live doc preview
• Approval workflows or gating logic beyond basic PR creation

A user invokes docNerd by commenting on a source PR with a mention and branch specification:

@docNerd, doc for core/v7.1

The format is: @docNerd, doc for <branch>, where <branch> is the target branch in the docs repository (e.g., a Mike version branch like core/v7.1).

• docNerd must check that the requested branch exists in the target docs repository before proceeding
• If the branch does not exist, docNerd replies immediately with "I couldn't find that branch" and does not create a docs PR

• PR analysis and doc generation should complete within a reasonable time (e.g., < 5 minutes for typical PRs, accounting for LLM latency)
• Comment detection and API usage should not overwhelm source/target/LLM rate limits

• Credentials (tokens, keys, LLM connection strings) must not be hardcoded; use env vars or secure secret management
• LLM API keys must be stored securely and never exposed in logs or PR content
• System must support least-privilege access (e.g., read source, write target)

• System should handle API failures gracefully (retries, backoff)
• System should log actions for debugging and audit
• LLM failures should result in a clear comment reply to the user (e.g., "I ran into an error generating docs")

• Documentation rules should be easy to edit without code changes
• Architecture should allow swapping LLM provider if needed (e.g., different Claude endpoint)

The user must have full control over how documentation is written. The system provides a rules engine; the user defines the rules.

1. Style Rules

   • Voice (e.g., second person, imperative)
   • Tone (e.g., concise, formal, friendly)
   • Sentence length, paragraph structure
   • Use of passive vs active voice

2. Structural Rules

   • Required sections (e.g., Overview, Prerequisites, Steps, Examples)
   • Heading hierarchy (H1 → H2 → H3)
   • Ordering of content blocks

3. Formatting Rules

   • Markdown conventions (bold, code blocks, lists)
   • Code block language tags
   • Link format and style

4. Terminology Rules

   • Preferred terms and banned terms
   • Acronym handling (spell out first use, etc.)
   • Product/feature naming consistency

5. Content Rules

   • What to include for different change types (API, config, UI, etc.)
   • Example formats
   • Deprecation/breaking change documentation requirements

• Proposed: YAML or JSON config files in the project
• Alternative: Dedicated rules directory (e.g., rules/) with modular rule files
• Rules should be human-readable and diff-friendly

• Rules are passed to Claude (e.g., in system prompt or context) to guide generation
• Optional: validation step to check generated docs against rules before PR creation
• Optional: lint/check command for manual rule validation

┌─────────────────┐     ┌──────────────────────────────────────────┐     ┌─────────────────┐
│  Source Repo    │     │  docNerd                                  │     │  Target Docs    │
│  (PR + comment  │────▶│  - Comment Watcher (detect @docNerd)       │────▶│  Repo           │
│   @docNerd)     │     │  - Branch Validator (check docs repo)      │     │  (MkDocs+Mike)  │
│                 │◀────│  - Analyzer (PR diff, metadata)            │     │  (Doc PRs on    │
│  (reply: link)  │     │  - Claude (LLM doc generation/editing)    │     │   version       │
└─────────────────┘     │  - Rules Engine (user rules → prompt)     │     │   branches)     │
                        │  - PR Creator (branch from target, open PR)│     └─────────────────┘
                        └──────────────────────────────────────────┘

1. Comment Watcher: Detects @docNerd, doc for <branch> comments on source PRs
2. Branch Validator: Verifies the requested branch exists in the docs repo
3. Analyzer: Parses PR content, determines docs relevance, extracts topics
4. Claude (LLM): Generates new docs and edits existing docs, guided by rules
5. Rules Engine: Loads user rules, injects them into Claude prompts
6. PR Creator: Creates branch from target version branch, opens PR, replies with link

• Source repository URL and auth
• Target repository URL and auth (MkDocs + Mike docs repo)
• LLM (Claude) connection strings / API keys (e.g., Anthropic API key, or custom endpoint URL + key)
• Path to documentation rules

• Comment trigger phrase (default: @docNerd, doc for)
• Branch naming convention for docNerd's working branches (e.g., docnerd/<source-pr-number>-<branch>)
• Mapping: source repo paths → target doc paths
• Claude model variant (e.g., claude-3-5-sonnet)

1. Comment detection: Webhook on issue/PR comments, or polling for new comments?
2. Duplicate handling: If user comments @docNerd, doc for core/v7.1 twice, should docNerd update the existing docs PR or create a new one?
3. Conflict handling: If target branch has changed since docNerd branched, how to handle merge conflicts?
4. Review workflow: Should docs PRs be draft by default, or ready for review?
5. MkDocs structure: Does docNerd need to understand mkdocs.yml / nav structure to place new pages correctly?

• Detects @docNerd, doc for <branch> comments on source PRs
• Validates requested branch exists in docs repo; replies "I couldn't find that branch" when not found
• Replies "yes, working on it" when request is accepted
• Uses Claude to generate and edit docs according to user-defined rules
• Opens a docs PR on the correct version branch (e.g., core/v7.1)
• Replies "Here is the link to the Doc changes" with the PR link when complete
• User can provide LLM connection strings via configuration
• No duplicate docs PRs for the same source PR + branch combo

# rules/style.yaml (example)
voice: second_person  # "You can configure..."
tone: concise
sentence_max_words: 25
use_active_voice: true

# rules/structure.yaml (example)
required_sections:
  - overview
  - prerequisites
  - steps
  - examples
heading_style: sentence_case

# rules/terminology.yaml (example)
preferred_terms:
  "config" -> "configuration"
  "API" -> "API"  # (no change, but explicit)
banned_terms:
  - "simply"
  - "just"

Document version: 1.1
Last updated: March 19, 2025