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..dac53a51 --- /dev/null +++ b/.claude/workflows/cli-templates/prompts/analysis/02-analyze-technical-document.txt @@ -0,0 +1,33 @@ +Analyze technical documents, research papers, and specifications systematically. + +## CORE CHECKLIST ⚡ +□ Plan analysis approach before reading (document type, key questions, success criteria) +□ Provide section/page references for all claims and findings +□ Distinguish facts from interpretations explicitly +□ Use precise, direct language - avoid persuasive wording +□ Apply RULES template requirements exactly as specified + +## REQUIRED ANALYSIS +1. Document assessment: type, structure, audience, quality indicators +2. Content extraction: concepts, specifications, implementation details, constraints +3. Critical evaluation: strengths, gaps, ambiguities, clarity issues +4. Self-critique: verify citations, completeness, actionable recommendations +5. Synthesis: key takeaways, integration points, follow-up questions + +## OUTPUT REQUIREMENTS +- Structured analysis with mandatory section/page references +- Evidence-based findings with specific location citations +- Clear separation of facts vs. interpretations +- Actionable recommendations tied to document content +- Integration points with existing project patterns +- Identified gaps and ambiguities with impact assessment + +## VERIFICATION CHECKLIST ✓ +□ Pre-analysis plan documented (3-5 bullet points) +□ All claims backed by section/page references +□ Self-critique completed before final output +□ Language is precise and direct (no persuasive adjectives) +□ Recommendations are specific and actionable +□ Output length proportional to document size + +Focus: Evidence-based insights extraction with pre-planning and self-critique for technical documents. diff --git a/.claude/workflows/intelligent-tools-strategy.md b/.claude/workflows/intelligent-tools-strategy.md index 14b65d9e..6c200e6f 100644 --- a/.claude/workflows/intelligent-tools-strategy.md +++ b/.claude/workflows/intelligent-tools-strategy.md @@ -65,6 +65,7 @@ codex -C [dir] --full-auto exec "[prompt]" [--skip-git-repo-check -s danger-full | Architecture Planning | Gemini → Qwen | analysis | `planning/01-plan-architecture-design.txt` | | Code Pattern Analysis | Gemini → Qwen | analysis | `analysis/02-analyze-code-patterns.txt` | | Architecture Review | Gemini → Qwen | analysis | `analysis/02-review-architecture.txt` | +| Document Analysis | Gemini → Qwen | analysis | `analysis/02-analyze-technical-document.txt` | | Feature Implementation | Codex | auto | `development/02-implement-feature.txt` | | Component Development | Codex | auto | `development/02-implement-component-ui.txt` | | Test Generation | Codex | write | `development/02-generate-tests.txt` | @@ -519,13 +520,14 @@ When no specific template matches your task requirements, use one of these unive **Available Templates**: ``` prompts/ -├── universal/ # ← NEW: Universal fallback templates +├── universal/ # ← Universal fallback templates │ ├── 00-universal-rigorous-style.txt # Precision & standards-driven │ └── 00-universal-creative-style.txt # Innovation & exploration-focused ├── analysis/ │ ├── 01-trace-code-execution.txt │ ├── 01-diagnose-bug-root-cause.txt │ ├── 02-analyze-code-patterns.txt +│ ├── 02-analyze-technical-document.txt │ ├── 02-review-architecture.txt │ ├── 02-review-code-quality.txt │ ├── 03-analyze-performance.txt @@ -556,6 +558,7 @@ prompts/ | Execution Tracing | Gemini (Qwen fallback) | `analysis/01-trace-code-execution.txt` | | Bug Diagnosis | Gemini (Qwen fallback) | `analysis/01-diagnose-bug-root-cause.txt` | | Code Pattern Analysis | Gemini (Qwen fallback) | `analysis/02-analyze-code-patterns.txt` | +| Document Analysis | Gemini (Qwen fallback) | `analysis/02-analyze-technical-document.txt` | | Architecture Review | Gemini (Qwen fallback) | `analysis/02-review-architecture.txt` | | Code Review | Gemini (Qwen fallback) | `analysis/02-review-code-quality.txt` | | Performance Analysis | Gemini (Qwen fallback) | `analysis/03-analyze-performance.txt` |