optimize-docs

# Optimize Documentation Analyze documentation for optimization opportunities, including splitting long documents, reducing verbosity, and identifying obsolete or redundant content. ## Input Scope: $ARGUMENTS (optional - flexible scope for analysis) **Scope interpretation:** - No argument = analyze all documentation - Specific topic (e.g., "auth", "user authentication") = find and analyze related docs - File path = analyze specific document - Directory name = analyze all docs in that directory ## Context **You must load the following skills and read the following files before proceeding.** ### Skills - `katachi:framework-core` - Workflow principles and project structure ### Documentation indexes (read to discover documents) - `docs/feature-specs/README.md` - Feature capability index - `docs/feature-designs/README.md` - Feature design index - `docs/architecture/README.md` - Architecture decisions (ADRs) - `docs/design/README.md` - Design patterns (DES) ### Template references (for structure compliance checks) - `${CLAUDE_PLUGIN_ROOT}/skills/working-on-delta/references/feature-spec.md` - `${CLAUDE_PLUGIN_ROOT}/skills/working-on-delta/references/feature-design.md` - `${CLAUDE_PLUGIN_ROOT}/skills/framework-core/references/ADR-template.md` - `${CLAUDE_PLUGIN_ROOT}/skills/framework-core/references/DES-template.md` ## Pre-Check Verify framework is initialized: - If `docs/planning/` doesn't exist, explain this command requires an initialized katachi framework - If minimal documentation exists, note the analysis may be limited ## Process ### 1. Discover Documents Within Scope **If no scope provided:** - Scan all directories: feature-specs/, feature-designs/, architecture/, design/ - Collect all .md files **If topic scope provided** (e.g., "auth"): - Scan all documentation directories - Find files where: - File name contains topic keywords (auth, authentication, login, etc.) - Title/headings mention the topic - Content discusses the topic - Present discovered files for confirmation **If file path provided:** - Analyze that specific document **If directory provided:** - Analyze all .md files in that directory Group discovered documents for parallel processing. ### 2. Dispatch Doc-Optimizer Agents (Silent) Always dispatch doc-optimizer agents to analyze discovered documents: - If multiple documents, dispatch multiple agents in parallel (single message with multiple Task calls) - If single document, dispatch one agent - Each agent receives a subset of documents and the relevant template references For each agent, provide: ``` Analyze these documents for optimization opportunities. ## Documents to Analyze [list of file paths with brief descriptions] ## Document Type [feature-specs / feature-designs / architecture / design] ## Template Reference [relevant template content for structure compliance] ## Analysis Focus Provide actionable guidance on: 1. Document Length: Files that should split (>400 lines features, >150 decisions) 2. Verbosity: Repetitive phrasing, over-explanation, redundancy 3. Obsolescence: Orphaned docs, superseded content, obsolete documents 4. Structure: Missing required sections, incorrect format For each issue found, provide: - Specific file and location (line numbers when relevant) - Clear explanation of the problem - Actionable recommendation for improvement ``` ### 3. Aggregate Results (Silent) Wait for all agent responses and synthesize findings into a single report organized by action type: - Candidates for Splitting - Verbosity Reduction Opportunities - Candidates for Removal - Orphaned Documents - Structure Issues ### 4. Present Optimization Report Show the aggregated report with clear categorization: ``` ## Document Optimization Report ### Candidates for Splitting - docs/feature-specs/auth.md (523 lines) - Contains 3 distinct authentication methods that should be separate - Suggested: auth/login.md, auth/oauth.md, auth/mfa.md - Each method has independent user stories, flows, and acceptance criteria ### Verbosity Reduction Opportunities - docs/feature-designs/api.md (312 lines → est. 180 lines) - Lines 45-60, 89-104, 145-160, 201-216: "API first" explanation repeated 4 times - Consider extracting to DES-XXX or consolidating into single reference section ### Candidates for Removal - docs/feature-designs/old-workflow.md - Not referenced in feature-designs/README.md - Content describes deprecated workflow ### Orphaned Documents - docs/architecture/old-db-choice.md (superseded by ADR-003) - Marked as superseded, no active references in other docs ### Structure Issues - docs/feature-specs/projects.md missing User Flows section - This is a UI capability - should include breadboards or add exclusion note ``` ### 5. Discuss Next Steps After presenting the report, ask: ``` "Which optimization would you like to address? 1. Split long documents 2. Reduce verbosity / consolidate content 3. Remove obsolete documents 4. Fix orphaned documents 5. Fix structure issues 6. All of the above Or provide specific items to address." ``` ### 6. Execute Optimizations **For splits:** - Show proposed split structure with new file names - Get explicit confirmation - Create new files with appropriate content - Update index README files if needed - Delete or replace original file **For verbosity reduction:** - Show before/after preview for the specific change - Get confirmation - Apply the change **For removals:** - Always require explicit confirmation before deleting - Show file path and reason for deletion - After confirmation, delete the file **For orphaned documents:** - Offer choices: add to index, delete, or leave as-is - If adding to index, show proposed index addition - Get confirmation before applying **For structure fixes:** - Show what needs to be added/changed - Get confirmation - Apply the fix Apply changes incrementally with user approval for each action or category. Track all changes made: - Modified file paths - New file paths (from splits) - Deleted file paths ### 7. Validate All Optimizations After all optimizations are complete, dispatch the optimization-validator agent to verify no data was lost: ``` Validate the following document optimizations preserve all relevant information. ## Modified Files [list of modified file paths] ## New Files (from splits) [list of new file paths and their source files] ## Deleted Files [list of deleted file paths] Use git to retrieve original versions and compare with current state. Apply corrections automatically if content was lost. Ask only if uncertain how to fix. ``` **If validation returns NEEDS_WORK:** - Agent applies corrections automatically (restores missing content) - Agent asks user only when uncertain about how to fix - Proceed to summary after corrections are applied ### 8. Post-Optimization Summary After completing optimizations: ``` "Optimization complete! Changes made: - [summary of splits, deletions, consolidations, fixes] Next steps: - Index files may need updating if structure changed - Consider running /katachi:analyze to verify no gaps introduced - Related deltas may need documentation updates" ``` ## Integration with Other Commands This command integrates with: - `/katachi:analyze` - Complementary: analyze finds gaps, optimize finds improvement opportunities - `/katachi:decision` - For extracting discovered patterns into DES documents - `/katachi:spec-delta` / `/katachi:design-delta` - For updating delta working documents ## Workflow This is an optimization command: - Discover documents within scope - Dispatch agents in parallel for analysis - Aggregate and present findings - Guide user through applying optimizations with confirmation - Apply changes incrementally - Validate no data was lost (auto-correct if needed)