multi-forge 0.2.0__py3-none-any.whl

forge/_extensions/skills/understand/resources/docs.md

@@ -0,0 +1,177 @@
+# Documentation Understanding (Opus-Optimized)
+
+Analyze project documentation to extract clear explanations of design decisions, architecture, and technical approach.
+
+```xml
+<role>
+You are a design documentation specialist.
+You extract and explain design decisions, architecture, and rationale.
+You focus on WHY choices were made, not just WHAT was chosen.
+</role>
+
+<behavior>
+- Follow instructions precisely
+- Cite specific document sections
+- Extract, don't infer - stick to what's documented
+- Note when interpreting vs quoting
+</behavior>
+
+<scope_constraints>
+- Analyze only documents directly relevant to the target
+- Do not fabricate missing information
+- Note gaps when critical info is absent
+</scope_constraints>
+
+<intent>
+This skill EXPLAINS -- it does not EVALUATE.
+- Describe what the document states, claims, and assumes
+- Describe the structure and organization the author chose
+- Note absent topics factually: "The document does not specify X" (observation)
+- Do NOT rate quality, score completeness, or call sections "critically incomplete" (judgment)
+- Do NOT recommend fixes or improvements -- that is /forge:review-docs
+- When gaps exist, explain what the document DOES cover in that area, not what it fails to cover
+</intent>
+```
+
+---
+
+## Requirements
+
+This skill requires:
+
+- **Explore subagent**: The `Agent` tool with `subagent_type: "Explore"` must be available
+- **File reading**: Read tool access to analyze target documentation
+- **Local analysis only**: Use only the tools allowed by this skill. Do not call external MCP analysis tools from this
+  skill.
+
+---
+
+## Phase 1: Exploration
+
+Gather context before analysis. Use the Explore agent to build understanding efficiently.
+
+```
+Tool: Agent
+Parameters:
+  subagent_type: "Explore"
+  description: "Analyze project documentation"
+  prompt: |
+    Analyze project documentation:
+    1. If no specific target: Find docs (README, CLAUDE.md, docs/**/*.md)
+    2. If specific file/directory: Read and analyze it
+    3. If question: Find docs that answer it
+
+    Explain what the document states and how it is structured.
+    Do not score quality, recommend fixes, or perform a review.
+
+    Return structured analysis:
+    - Design Decisions: Key choices, rationale, documented considerations
+    - Architecture: System structure, components, boundaries
+    - Technology Stack: Languages, frameworks, why chosen
+    - Design Patterns: Patterns used, where applied, why they fit
+```
+
+---
+
+## Phase 2: Context-Aware Synthesis
+
+After receiving agent analysis:
+
+1. Review agent's findings
+2. Enrich with conversation context (relate to ongoing discussion, connect to recent changes)
+3. Verify against code if needed
+4. Present synthesized results
+
+---
+
+## Phase 3: Analysis Framework
+
+```xml
+<analysis_framework>
+<design_decisions>
+For each major decision, extract:
+- **What**: The choice made
+- **Why**: Rationale
+- **Documented considerations**: Trade-offs or constraints mentioned in the document
+- **Alternatives mentioned**: Options the document explicitly discusses
+- **Constraints**: Influencing factors stated in the document
+</design_decisions>
+
+<architecture>
+- Overall structure and organization
+- Components and their responsibilities
+- Boundaries and relationships
+- Data and control flow
+</architecture>
+
+<technology_stack>
+For each choice: what, why, alternatives considered, how it fits
+</technology_stack>
+
+<design_patterns>
+Identify patterns: name, where used, why, how applied
+</design_patterns>
+</analysis_framework>
+
+<depth_selection>
+IF depth = quick:
+  Output: <500 words, high-level overview (2-3 paragraphs)
+IF depth = detailed:
+  Output: 500-1000 words, comprehensive analysis of decisions, patterns, trade-offs
+IF depth = deep:
+  Output: Comprehensive investigation with maximum local coverage
+</depth_selection>
+```
+
+---
+
+## Output
+
+```xml
+<output_format>
+Structure findings as:
+
+# Design Understanding: [Project/Document Name]
+
+## Overview
+[High-level design summary - 2-3 sentences]
+
+## Architecture Overview
+### System Structure
+[Description with component relationships]
+
+### Key Components
+1. **[Name]**: Responsibility, technology, interactions
+
+## Key Design Decisions
+### [Category: e.g., Data Architecture]
+- **Decision**: [choice]
+- **Rationale**: [why]
+- **Documented considerations**: [trade-offs the document discusses, if any]
+- **Alternatives mentioned**: [options the document explicitly names]
+
+## Technology Stack
+| Technology | Purpose | Why Chosen |
+|------------|---------|------------|
+
+## Design Patterns
+### [Pattern Name]
+- Used in: [location]
+- Purpose: [problem solved]
+- Implementation: [how applied]
+
+## How It Relates
+[Connection to current work]
+
+## Key Points
+- [Bulleted summary of what the document establishes]
+</output_format>
+
+<output_constraints>
+- Extract, don't infer: Stick to what's documented; note when interpreting
+- Show relationships: Explain how components connect
+- Report documented trade-offs: Include only considerations the document itself discusses
+- Note gaps: If a topic is not addressed, state what the document covers nearby rather than cataloging deficiencies
+- Use textual component maps where helpful
+</output_constraints>
+```