Documentation Patterns

This skill provides documentation-specific workflows and quality standards that extend beyond generic agentic patterns. Documentation requires unique quality criteria including accuracy, completeness, readability, consistency, and proper source attribution—areas where general-purpose frameworks lack domain expertise.

Purpose

Documentation queries demand specialized treatment. Unlike code generation or system operations, documentation must balance comprehensiveness with clarity, synthesize information from multiple sources with proper citation, and ensure factual accuracy without hallucination. This skill implements domain-specific patterns for:

• Quality Metrics: Readability scoring, completeness checklists, accuracy validation, consistency checks
• Structure Templates: Standardized formats for API docs, tutorials, reference docs, troubleshooting guides
• Reuse Patterns: Common section libraries, template inheritance, content deduplication
• Validation Strategies: Broken link detection, citation verification, source alignment checking
• Anti-Hallucination Protocols: 8 mandatory controls enforcing source verification and explicit gap disclosure

When to Use This Skill

Invoke this skill for ALL documentation-related queries, including:

• Answering questions about codebases, features, or system architecture
• Creating documentation (API docs, tutorials, guides, troubleshooting docs)
• Reviewing or improving existing documentation
• Synthesizing information from multiple documentation sources
• Validating documentation accuracy and completeness
• Ensuring proper citation and source attribution
• Any query where response quality depends on documentation standards

Integration Point: Documentation queries ALWAYS benefit from doc-patterns. Invoke at query start for classification and quality guidance.

Query Classification System

Before responding to any documentation query, classify it to determine appropriate depth and tool selection.

Type A: Direct Queries (5-10s response)

Characteristics:

• Single factual question answerable from 1-2 files
• Simple lookup or definition request
• No synthesis required
• Straightforward citation

Examples:

• "What port does the API server use?"
• "Where is the authentication module located?"
• "What is the command to run tests?"

Response Strategy:

• Use Read + Grep for targeted search
• Provide direct answer (2-3 sentences)
• Include single citation with line numbers
• Level 1 progressive disclosure

Tools: Read, Grep

Type B: Progressive Queries (15-30s response)

Characteristics:

• Requires information from 2-3 files
• Needs synthesis or examples
• Multiple related concepts
• Several citations needed

Examples:

• "How does the authentication flow work?"
• "Explain the database migration process"
• "What are the available API endpoints and their parameters?"

Response Strategy:

• Use Read + Grep + Glob for comprehensive search
• Provide detailed explanation with examples
• Include multiple citations from all sources
• Level 2 progressive disclosure
• Related topics for further exploration

Tools: Read, Grep, Glob, Skill

Type C: Research Queries (45-90s response)

Characteristics:

• Requires synthesis across 4+ files
• Architectural analysis or design rationale
• Trade-off evaluation
• Multi-source validation needed
• Evidence-based recommendations

Examples:

• "Compare the authentication approaches used across the codebase"
• "Document the complete deployment architecture"
• "Analyze the testing strategy and coverage patterns"

Response Strategy:

• Delegate to research-specialist via Task tool
• Multi-source investigation with credibility scoring
• Executive summary + detailed analysis
• Trade-offs table comparing options
• Level 3 progressive disclosure with all sources
• Explicit confidence level and limitations

Tools: Task (delegate to research-specialist), Read, Grep, Glob, Skill

Decision Tree: See references/query-classification.md for complete classification criteria and examples.

Quality Metrics Framework

Readability

Flesch-Kincaid Grade Level: Target 8-12 for technical documentation

Checks:

• Sentence length (aim for 15-20 words average)
• Paragraph length (3-5 sentences)
• Use of active voice
• Minimal jargon (or jargon explained)
• Clear section hierarchy

Completeness

Section Checklist (varies by doc type):

API Documentation:

• Endpoint description
• HTTP method
• Parameters (required/optional)
• Request examples
• Response examples
• Error codes
• Authentication requirements

Tutorial:

• Prerequisites
• Step-by-step instructions
• Code examples
• Expected outcomes
• Troubleshooting section
• Next steps

Reference:

• Overview/Purpose
• All parameters documented
• Return values
• Examples
• Related topics

Accuracy

Source Validation:

• Every factual claim cited with file:line_number
• Minimum 2 sources for critical information (Type B/C queries)
• Code examples tested or extracted from actual code
• Version awareness (check git timestamps)

Credibility Scoring:

• HIGH: 3+ sources confirm, recent timestamps
• MEDIUM: 2 sources confirm
• LOW: 1 source only

Consistency

Terminology:

• Use project-specific terms consistently
• Maintain glossary for domain terms
• Follow established naming conventions

Formatting:

• Consistent code block formatting
• Standardized heading hierarchy
• Uniform citation style

Structure Templates

API Documentation Template

## [Endpoint Name]

**Description:** [1-2 sentence overview]

**HTTP Method:** [GET/POST/PUT/DELETE/PATCH]

**URL:** `/api/v1/resource`

**Authentication:** [Required/Optional/None] - [Method]

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| param1 | string | Yes | Description |
| param2 | integer | No | Description (default: value) |

**Request Example:**

\`\`\`json
{
  "param1": "value",
  "param2": 123
}
\`\`\`

**Response Example (200 OK):**

\`\`\`json
{
  "status": "success",
  "data": {}
}
\`\`\`

**Error Responses:**

- `400 Bad Request`: Invalid parameters
- `401 Unauthorized`: Missing authentication
- `404 Not Found`: Resource not found

**Source:** [file.py:123-145]

Tutorial Template

# [Tutorial Title]

## Prerequisites

- [Requirement 1]
- [Requirement 2]

## Overview

[1-2 paragraphs explaining what will be accomplished]

## Step 1: [Action]

[Detailed instructions]

\`\`\`bash
# Command example
command --flag value
\`\`\`

**Expected Output:**
\`\`\`
Output example
\`\`\`

## Step 2: [Action]

[Continue pattern...]

## Troubleshooting

**Problem:** [Common issue]
**Solution:** [How to resolve]

## Next Steps

- [Related tutorial or topic]
- [Advanced concepts]

**Sources:**
- [file1.md:10-20]
- [file2.py:50-75]

For complete templates, see references/response-templates.md.

Citation Standards

Mandatory Format: file_path:line_number or file_path:line_start-line_end

Examples:

• .claude/CLAUDE.md:73 (single line)
• .claude/skills/orchestrator/SKILL.md:120-145 (range)

Requirements:

• ALWAYS verify source with Read tool before citing
• Include line numbers in ALL citations
• Provide 1-3 lines of context around citation
• Multi-source validation for critical information (Type B/C queries)

Credibility Annotation:

• List all sources after claims
• Score credibility: HIGH (3+ sources), MEDIUM (2 sources), LOW (1 source)
• Disclose if information based on single source

See references/citation-standards.md for complete guidelines.

Progressive Disclosure Levels

Structure responses with three disclosure levels to match query depth:

Level 1: Quick Answer (Type A):

• Direct answer (2-3 sentences)
• Single citation
• Optional: Brief example

Level 2: Detailed Explanation (Type B):

• Introduction with context
• Detailed explanation with examples
• Code examples if applicable
• Multiple citations from all sources
• Related topics section

Level 3: Comprehensive Analysis (Type C):

• Executive summary of key findings
• Recommended approach with rationale
• Detailed multi-source analysis
• Trade-offs table
• All sources with credibility scores
• Explicit limitations and unknowns
• Confidence level (HIGH/MEDIUM/LOW)
• Related topics and further reading

Match disclosure level to query type for optimal context usage.

Anti-Hallucination Integration

This skill integrates 8 mandatory anti-hallucination controls:

AH-001: Source Verification Mandate:

• NEVER cite without Read tool verification
• All factual claims require source confirmation

AH-002: File Discovery via Search:

• ALWAYS use Grep/Glob before assuming files exist
• Verify file paths before claiming locations

AH-003: Explicit 'I Don't Know' Response:

• Say "I don't have documentation on X" when source not found
• NEVER fabricate information to fill gaps

AH-004: Line Number Citation Requirement:

• ALL citations MUST include line numbers
• Format: file:line or file:line_start-line_end

AH-005: Multi-Source Validation:

• Critical information requires 2+ sources for confirmation
• Type C queries require 3+ sources minimum

AH-006: Confidence Scoring:

• Include HIGH/MEDIUM/LOW confidence with every response
• Base on source count and agreement

AH-007: Version Awareness:

• Check git timestamps to determine currency
• Note if information may be outdated

AH-008: Gap Disclosure:

• Explicitly disclose documentation gaps when identified
• Suggest where information should exist

See references/anti-hallucination-protocols.md for implementation details.

Integration with Agentic Patterns

Doc-patterns builds on agentic-patterns framework with documentation-specific implementations:

Gather Context (Documentation-Specific):

• Hierarchical documentation search: Index → Section → Details
• Multi-angle investigation: Check specs, implementation, tests, docs
• Citation collection during search (not after response)

Take Action (Documentation-Specific):

• Apply structure templates for consistent formatting
• Use reuse patterns from common sections library
• Generate with quality metrics in mind

Verify Work (Documentation-Specific):

• Run validation scripts (validate_citations.py, check_doc_completeness.py)
• Check against quality metrics (readability, completeness, accuracy, consistency)
• Verify all citations resolve to actual locations

Integration with Memory Management

Apply memory-management's Reuse > Adapt > Generate strategy to documentation artifacts:

Documentation Query Planning:

1. Query memory: search_memory.py --query "API authentication documentation"
2. Classify overlap:
   • REUSE (≥0.90): Use existing documentation response as-is
   • ADAPT (0.731-0.89): Modify existing documentation for new context
   • GENERATE (<0.731): Create new documentation from sources

After Documentation Generation:

1. Save to memory: save_artifact.py --path response.json --description "JWT authentication flow documentation" --tags documentation,authentication,api

Benefits:

• Consistent answers to similar questions
• Faster responses through documentation reuse
• Accumulated organizational knowledge base

Validation Strategies

Programmatic Validation

validate_citations.py: Verify all citations resolve to actual file:line locations

python scripts/validate_citations.py \
  --response "Authentication uses JWT tokens (.claude/CLAUDE.md:73)" \
  --base-path /home/user/project

Exit codes:

• 0: All citations valid
• 1: Invalid citations found
• 2: Error occurred

check_doc_completeness.py: Verify response completeness against query aspects

python scripts/check_doc_completeness.py \
  --query "How does authentication work?" \
  --response "[response text]" \
  --type B

Exit codes:

• 0: Complete
• 1: Incomplete aspects identified
• 2: Error occurred

Manual Validation Checklist

Before finalizing documentation response:

• All citations include line numbers
• Citations verified with Read tool
• Query classification correct (Type A/B/C)
• Appropriate disclosure level used
• Quality metrics met (readability, completeness, accuracy, consistency)
• Anti-hallucination protocols followed
• Confidence level included (Type C)
• Gaps explicitly disclosed

Quick Reference Checklists

Quality Checklist

• Readability: Clear, concise, appropriate grade level
• Completeness: All query aspects addressed
• Accuracy: All claims cited and verified
• Consistency: Terminology and formatting standardized

Structure Checklist

• Appropriate template used (API/Tutorial/Reference/Troubleshooting)
• All template sections completed
• Progressive disclosure level matches query type
• Code examples formatted correctly (single fenced blocks, language specified)

Validation Checklist

• All citations verified with Read tool
• Line numbers included in all citations
• Multi-source validation for critical info (Type B/C)
• Validation scripts executed (validate_citations.py, check_doc_completeness.py)
• Confidence level included and justified
• Gaps disclosed explicitly

Reference Documentation

For detailed implementation guidance, see bundled reference files:

• query-classification.md - Complete classification criteria, decision tree, tool selection per type, examples
• citation-standards.md - Citation format standards, multi-source validation patterns, credibility scoring rubric
• anti-hallucination-protocols.md - 8 mandatory controls with implementation patterns and examples
• response-templates.md - Complete templates for Type A/B/C responses, progressive disclosure patterns, formatting standards

Summary

Invoke this skill for all documentation queries to ensure:

1. Proper Classification: Type A/B/C determines appropriate depth and tools
2. Quality Standards: Readability, completeness, accuracy, consistency metrics met
3. Accurate Citation: file:line format, source verification, multi-source validation
4. Anti-Hallucination: 8 mandatory controls prevent fabrication and gaps
5. Structural Consistency: Templates ensure standardized, professional documentation
6. Validation: Programmatic checks verify citation validity and completeness

Documentation is a specialized domain requiring domain-specific quality criteria. This skill provides the workflows, templates, and validation strategies to ensure professional, accurate, complete documentation responses.