mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-10 02:24:35 +08:00
feat: add document analysis template for technical documents and papers
Add new CLI mode for systematic technical document analysis with: - CLI command: /cli:mode:document-analysis for Gemini/Qwen/Codex - Comprehensive analysis template with 6-phase protocol - Support for README, API docs, research papers, specifications, tutorials - Evidence-based analysis with pre-planning and self-critique requirements - Precise language constraints and structured output format Template features: - Pre-analysis planning phase for approach definition - Multi-phase analysis: assessment, extraction, critical analysis, synthesis - Self-critique requirement before final output - Mandatory section references and evidence citations - Output length control proportional to document size
This commit is contained in:
Claude
126
.claude/commands/cli/mode/document-analysis.md
Normal file
126
.claude/commands/cli/mode/document-analysis.md
Normal file
@@ -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 <gemini|qwen|codex>` - Tool selection (default: gemini)
|
||||||
|
- `--enhance` - Enhance analysis target with `/enhance-prompt`
|
||||||
|
- `--cd "path"` - Target directory for document search
|
||||||
|
- `<document-path-or-topic>` (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
|
||||||
@@ -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
|
||||||
Reference in New Issue
Block a user