diff --git a/.claude/commands/cli/mode/document-analysis.md b/.claude/commands/cli/mode/document-analysis.md new file mode 100644 index 00000000..3cd92132 --- /dev/null +++ b/.claude/commands/cli/mode/document-analysis.md @@ -0,0 +1,126 @@ +--- +name: document-analysis +description: Read-only technical document/paper analysis using Gemini/Qwen/Codex with systematic comprehension template for insights extraction +argument-hint: "[--tool codex|gemini|qwen] [--enhance] [--cd path] document path or topic" +allowed-tools: SlashCommand(*), Bash(*), Task(*), Read(*) +--- + +# CLI Mode: Document Analysis (/cli:mode:document-analysis) + +## Purpose + +Systematic analysis of technical documents, research papers, API documentation, and technical specifications. + +**Tool Selection**: +- **gemini** (default) - Best for document comprehension and structure analysis +- **qwen** - Fallback when Gemini unavailable +- **codex** - Alternative for complex technical documents + +**Key Feature**: `--cd` flag for directory-scoped document discovery + +## Parameters + +- `--tool ` - Tool selection (default: gemini) +- `--enhance` - Enhance analysis target with `/enhance-prompt` +- `--cd "path"` - Target directory for document search +- `` (Required) - File path or topic description + +## Tool Usage + +**Gemini** (Primary): +```bash +/cli:mode:document-analysis "README.md" +/cli:mode:document-analysis --tool gemini "analyze API documentation" +``` + +**Qwen** (Fallback): +```bash +/cli:mode:document-analysis --tool qwen "docs/architecture.md" +``` + +**Codex** (Alternative): +```bash +/cli:mode:document-analysis --tool codex "research paper in docs/" +``` + +## Execution Flow + +Uses **cli-execution-agent** for automated document analysis: + +```javascript +Task( + subagent_type="cli-execution-agent", + description="Systematic document comprehension and insights extraction", + prompt=` + Task: ${document_path_or_topic} + Mode: document-analysis + Tool: ${tool_flag || 'gemini'} + Directory: ${cd_path || '.'} + Enhance: ${enhance_flag} + Template: ~/.claude/workflows/cli-templates/prompts/analysis/02-analyze-technical-document.txt + + Execute systematic document analysis: + + 1. Document Discovery: + - Locate target document(s) via path or topic keywords + - Identify document type (README, API docs, research paper, spec, tutorial) + - Detect document format (Markdown, PDF, plain text, reStructuredText) + - Discover related documents (references, appendices, examples) + - Use MCP/ripgrep for comprehensive file discovery + + 2. Pre-Analysis Planning (Required): + - Determine document structure (sections, hierarchy, flow) + - Identify key components (abstract, methodology, implementation details) + - Map dependencies and cross-references + - Assess document scope and complexity + - Plan analysis approach based on document type + + 3. CLI Command Construction: + - Tool: ${tool_flag || 'gemini'} (qwen fallback, codex for complex docs) + - Directory: cd ${cd_path || '.'} && + - Context: @{document_paths} + @CLAUDE.md + related files + - Mode: analysis (read-only) + - Template: analysis/02-analyze-technical-document.txt + + 4. Analysis Execution: + - Apply 6-field template structure (PURPOSE, TASK, MODE, CONTEXT, EXPECTED, RULES) + - Execute multi-phase analysis protocol with pre-planning + - Perform self-critique before final output + - Generate structured report with evidence-based insights + + 5. Output Generation: + - Comprehensive document analysis report + - Structured insights with section references + - Critical assessment with evidence + - Actionable recommendations + - Save to .workflow/active/WFS-[id]/.chat/doc-analysis-[timestamp].md (or .scratchpad/) + ` +) +``` + +## Core Rules + +- **Read-only**: Analyzes documents, does NOT modify files +- **Evidence-based**: All claims must reference specific sections/pages +- **Pre-planning**: Requires analysis approach planning before execution +- **Precise language**: Direct, accurate wording - no persuasive embellishment +- **Output**: `.workflow/active/WFS-[id]/.chat/doc-analysis-[timestamp].md` (or `.scratchpad/` if no session) + +## Document Types Supported + +| Type | Focus Areas | Key Outputs | +|------|-------------|-------------| +| README | Purpose, setup, usage | Integration steps, quick-start guide | +| API Documentation | Endpoints, parameters, responses | API usage patterns, integration points | +| Research Paper | Methodology, findings, validity | Applicable techniques, implementation feasibility | +| Specification | Requirements, standards, constraints | Compliance checklist, implementation requirements | +| Tutorial | Learning path, examples, exercises | Key concepts, practical applications | +| Architecture Docs | System design, components, patterns | Design decisions, integration points, trade-offs | + +## Best Practices + +1. **Scope Definition**: Clearly define what aspects to analyze before starting +2. **Layered Reading**: Structure/Overview → Details → Critical Analysis → Synthesis +3. **Evidence Trail**: Track section references for all extracted information +4. **Gap Identification**: Note missing information or unclear sections explicitly +5. **Actionable Output**: Focus on insights that inform decisions or actions diff --git a/.claude/workflows/cli-templates/prompts/analysis/02-analyze-technical-document.txt b/.claude/workflows/cli-templates/prompts/analysis/02-analyze-technical-document.txt new file mode 100644 index 00000000..6aebb0a0 --- /dev/null +++ b/.claude/workflows/cli-templates/prompts/analysis/02-analyze-technical-document.txt @@ -0,0 +1,279 @@ +PURPOSE: Extract key insights, concepts, and actionable information from technical documents and research papers +TASK: Systematically analyze technical document to identify core concepts, specifications, and integration points +MODE: analysis +CONTEXT: {document_files} {related_documentation} +EXPECTED: Structured analysis report with evidence-based insights, critical assessment, and actionable recommendations +RULES: | + ## Role Definition + + You are a technical document analyst. Your task is to extract, assess, and synthesize information from technical documents with precision and clarity. + + ## Behavioral Constraints + + - Use precise, direct language - eliminate persuasive or embellished wording + - Cite specific sections/pages/line numbers for all claims + - Distinguish explicitly between facts and interpretations + - Highlight assumptions and uncertainties without hedging excessively + - Focus on actionable insights over general observations + + ## Analysis Protocol + + ### Phase 1: Pre-Analysis Planning (Required First Step) + + Before analyzing content, plan your approach: + + 1. Document Classification: + - Identify document type (README, API docs, research paper, specification, tutorial, architecture) + - Determine primary purpose and target audience + - Assess document scope and expected depth + + 2. Analysis Strategy: + - Define key questions this analysis should answer + - Identify critical sections requiring deep focus + - Plan reading order (linear vs. selective) + - Anticipate potential gaps or ambiguities + + 3. Success Criteria: + - What insights must be extracted? + - What level of detail is appropriate? + - What integration points with existing project? + + **Output**: Brief analysis plan (3-5 bullet points) before proceeding + + ### Phase 2: Initial Assessment + + - Document structure and organization quality + - Completeness indicators (table of contents, index, references) + - Target audience and prerequisite knowledge + - Version/date information and currency + - Overall quality assessment (clarity, coherence, technical accuracy) + + ### Phase 3: Content Extraction + + Extract with section/page references: + + 1. **Core Concepts and Definitions** + - Fundamental concepts introduced + - Technical terminology and definitions + - Conceptual models or frameworks + + 2. **Technical Specifications** + - APIs, interfaces, protocols + - Data structures and schemas + - Algorithms or methodologies + - Configuration parameters + - Performance characteristics + + 3. **Implementation Details** + - Step-by-step procedures + - Code examples and patterns + - Integration requirements + - Dependencies and prerequisites + - Environment setup + + 4. **Constraints and Limitations** + - Scope boundaries + - Known issues or caveats + - Platform or version restrictions + - Performance limitations + + ### Phase 4: Critical Analysis + + Evaluate document quality: + + 1. **Strengths**: + - Clear explanations with specific examples + - Comprehensive coverage with evidence + - Well-structured with good flow + + 2. **Gaps and Ambiguities**: + - Missing information (specify what) + - Unclear sections (identify location) + - Contradictions or inconsistencies + - Outdated or deprecated content + + 3. **Clarity Assessment**: + - Jargon usage appropriateness + - Example quality and relevance + - Diagram/visualization effectiveness + - Accessibility for target audience + + ### Phase 5: Self-Critique (Required Before Final Output) + + Before providing final analysis, critique your work: + + 1. Verification: + - Have I cited sources for all claims? + - Are my interpretations clearly distinguished from facts? + - Have I avoided persuasive language? + - Are recommendations specific and actionable? + + 2. Completeness: + - Did I address all analysis objectives? + - Are there obvious gaps in my analysis? + - Have I considered alternative interpretations? + + 3. Quality: + - Is the output concise without losing critical detail? + - Are findings prioritized appropriately? + - Will this enable actionable decisions? + + **Output**: Brief self-assessment (2-3 sentences) + refinements before final submission + + ### Phase 6: Synthesis and Output + + Generate structured output: + + ## Output Format (Mandatory Structure) + + ```markdown + # Document Analysis: [Document Title] + + ## Analysis Plan + + [Brief 3-5 bullet plan developed in Phase 1] + + ## Document Overview + + - **Type**: [README|API Docs|Research Paper|Specification|Tutorial|Architecture] + - **Purpose**: [Primary goal in 1 sentence] + - **Scope**: [Coverage boundaries] + - **Audience**: [Target readers and prerequisite knowledge] + - **Currency**: [Version/date, assessment of recency] + - **Quality**: [High|Medium|Low] - [Specific rationale with examples] + + ## Core Findings + + ### Concepts and Definitions + + 1. **[Concept Name]** (Section X.Y, Page Z) + - Definition: [Precise definition from document] + - Significance: [Why this matters] + - Context: [How it relates to other concepts] + + 2. **[Concept Name]** (Section X.Y) + - [Follow same structure] + + ### Technical Specifications + + - **[Specification Area]** (Section X.Y) + - Detail: [Precise specification with parameters] + - Requirements: [What's needed to implement] + - Constraints: [Limitations or restrictions] + + ### Implementation Guidance + + 1. **[Implementation Aspect]** (Section X.Y) + - Procedure: [Step-by-step or key approach] + - Dependencies: [Required components] + - Example: [Reference to code example if available] + + ## Critical Assessment + + ### Strengths + + - **[Strength Category]**: [Specific example with location] + - Evidence: [Quote or reference] + - Impact: [Why this is valuable] + + ### Gaps and Ambiguities + + - **[Gap Description]** (Expected in Section X, missing) + - Impact: [What's unclear or unavailable] + - Consequence: [How this affects usage/implementation] + + - **[Ambiguity Description]** (Section X.Y, Line Z) + - Issue: [What's unclear] + - Alternative Interpretations: [Possible meanings] + + ### Clarity and Accessibility + + - **Positive**: [What's well-explained] + - **Needs Improvement**: [What's confusing with suggestions] + + ## Synthesis + + ### Key Takeaways (Prioritized) + + 1. **[Primary Insight]** + - Implication: [What this means for implementation/usage] + - Evidence: [Supporting sections/data] + + 2. **[Secondary Insight]** + - [Follow same structure] + + 3. **[Tertiary Insight]** + - [Follow same structure] + + ### Actionable Recommendations + + 1. **[Specific Action]** + - Context: [When/why to do this] + - Approach: [How to execute] + - Reference: [Document section supporting this] + + 2. **[Specific Action]** + - [Follow same structure] + + ### Integration with Existing Project + + - **Alignment**: [How document findings match existing patterns] + - Example: [Specific code pattern + document section] + + - **Conflicts**: [Where findings contradict current implementation] + - Recommendation: [How to resolve] + + - **Opportunities**: [New capabilities or improvements enabled] + + ### Unanswered Questions + + 1. **[Question requiring clarification]** + - Why it matters: [Impact of ambiguity] + - Where to investigate: [Suggested resources] + + 2. **[Question for further research]** + - [Follow same structure] + + ## Cross-References + + - **Related Documents**: [List with paths and relevance] + - **External References**: [Key citations with URLs/identifiers] + - **Code Examples**: [Locations in codebase if applicable] + - **Dependencies**: [Other docs to read for full context] + + ## Self-Critique + + [2-3 sentences assessing analysis completeness, potential blind spots, and confidence level] + ``` + + ## Output Constraints + + - **Length Control**: + - Overview: 100-200 words + - Each finding: 50-100 words + - Total: Proportional to document size (1-page doc → 500 words; 20-page doc → 2000 words) + + - **Precision Requirements**: + - Every claim → section/page reference + - Every recommendation → supporting evidence + - Every assessment → specific examples + - Avoid: "seems", "appears", "might" (use "is unclear", "document states", "evidence suggests") + + - **Prohibited Language**: + - No persuasive adjectives ("amazing", "excellent", "poor") + - No unsupported generalizations ("always", "never", "obviously") + - No hedging without reason ("perhaps", "maybe", "possibly") + - Use: "Section 3.2 indicates...", "The document specifies...", "No evidence provided for..." + + ## Quality Checklist (Verify Before Output) + + - [ ] Analysis plan documented + - [ ] All sections have location references + - [ ] Facts separated from interpretations + - [ ] Language is precise and direct + - [ ] Recommendations are actionable and specific + - [ ] Gaps and ambiguities explicitly noted + - [ ] Integration with project considered + - [ ] Self-critique completed + - [ ] Output length appropriate for document size + - [ ] No persuasive or embellished language