feat: Enhance /docinit to preserve existing doc conventions

[fore5fire]

Summary

Enhance the /docinit command to better handle repositories that already have documentation:

• Detect and analyze existing documentation patterns (naming, structure, tone, sections)
• Prompt user for organization preferences after exploration via AskUserQuestion
• Generate new docs that follow existing conventions
• Handle conflicts with existing topics (skip/merge/rename)

Motivation

Previously, /docinit would generate documentation without considering existing docs in the repository. This led to inconsistent formatting and structure. The new version:

1. Analyzes existing docs to understand conventions
2. Asks the user how they want new docs organized
3. Generates docs that seamlessly integrate with the existing documentation

Test plan

• Run /docinit in a repo with existing docs
• Verify existing conventions are detected correctly
• Test user prompt for organization preferences
• Verify generated docs follow detected conventions
• Test with repos that have no existing docs (fallback to defaults)

Changes

claude-docsync-plugin/plugins/docsync/commands/docinit.md:

• Step 1: Detect existing documentation files
• Step 2: Spawn Explore subagent to analyze conventions
• Step 7: Ask user for organization preferences
• Step 8: Use detected conventions in doc generation

🤖 Generated with Claude Code

[claude]

Code Review - CLAUDE.md Compliance Issue

Architecture Deviation from Documented Pattern

The PR enhances /docinit functionality but changes the documented architecture in a way that requires CLAUDE.md to be updated.

Issue: The implementation adds new phases to the DocInit workflow that deviate from the documented architecture.

CLAUDE.md states (lines 125-132):

DocInit uses a two-phase exploration + parallel documentation architecture:

1. Architecture Discovery: Explore subagent identifies structural topics (patterns, modules, infrastructure)
2. Feature Discovery: Explore subagent identifies concrete features (capabilities, APIs, outcomes)
3. Topic Deduplication: Merges and removes duplicates between both exploration passes
4. Parallel Documentation: Spawns general-purpose subagents to create individual .md files per topic

What the PR implements:

The new workflow adds two additional phases:

1. Existing docs analysis (Step 2) - Analyzes existing documentation conventions before exploration
2. User confirmation (Step 7) - Uses AskUserQuestion to confirm organization preferences after exploration

This changes the architecture from "two-phase exploration + parallel documentation" to effectively a four-phase architecture:

1. Existing documentation analysis (new)
2. Architecture discovery (existing)
3. Feature discovery (existing)
4. User confirmation (new)
5. Parallel documentation (existing)

Impact: CLAUDE.md violation - the documented architecture no longer matches the implementation.

Recommendation: Update CLAUDE.md's DocInit architecture section (lines 125-132) to reflect the new workflow:

### DocInit Plugin

DocInit uses a **multi-phase exploration and user-guided documentation** architecture:

1. **Existing Docs Analysis**: Explore subagent analyzes existing documentation to detect conventions (naming, structure, tone, sections)
2. **Architecture Discovery**: Explore subagent identifies structural topics (patterns, modules, infrastructure)
3. **Feature Discovery**: Explore subagent identifies concrete features (capabilities, APIs, outcomes)
4. **Topic Deduplication**: Merges and removes duplicates between both exploration passes
5. **User Confirmation**: Prompts user via AskUserQuestion to confirm organization and formatting preferences
6. **Parallel Documentation**: Spawns `general-purpose` subagents to create individual `.md` files per topic following detected conventions

Also update the "Tools Used" section to include AskUserQuestion:

- **Tools Used**: Glob (file discovery), Read (file content), Task (subagent spawning), Bash (git commands), AskUserQuestion (user preferences)

---

Note: The enhancement itself is excellent and adds valuable functionality. This is purely a documentation synchronization issue - the CLAUDE.md file needs to be updated to match the new implementation.

[claude]

DocSync Validation Report

Overall Status: APPROVE

• Documentation files analyzed: 1
• Changed files analyzed: 1
• Issues found: 0

---

Summary

All changes in CLAUDE.md comply with the architecture documented in docs/architecture.md. The additions include the new /docsync:pr-review command and additional_permissions feature, both of which align with the documented architecture's design principles of parallel processing, git integration, and the plugin format.

---

Details by Document

architecture.md: PASS

No violations found. The changes accurately reflect the architectural workflow and components for the PR Review Mode feature.

Recommendations:

• Consider updating docs/architecture.md to include the PR Review Mode as a distinct component alongside the Console Mode, as this represents a significant architectural enhancement
• The DocInit plugin architecture is documented in CLAUDE.md but not in docs/architecture.md - consider adding this to maintain architectural documentation completeness

---

Review Policy

• APPROVE: All changes comply with documentation
• REQUEST_CHANGES: One or more violations found - please address before merging
• COMMENT: Minor issues or suggestions provided

This review was generated by the DocSync plugin for Claude Code.