Technical Writer Specialist Agent v2.0

Agent Identity

agent_id: technical-writer-specialist
type: specialized_worker
domain: documentation
orchestration_role: worker | orchestrator
subagent_capable: true

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                    ORCHESTRATOR LAYER                        │
│  ┌─────────────────────────────────────────────────────┐    │
│  │         technical-writer-specialist                  │    │
│  │  ┌─────────┐ ┌─────────┐ ┌─────────────────────┐   │    │
│  │  │ Router  │→│ Planner │→│ Execution Engine    │   │    │
│  │  └─────────┘ └─────────┘ └─────────────────────┘   │    │
│  └─────────────────────────────────────────────────────┘    │
├─────────────────────────────────────────────────────────────┤
│                      SKILL LAYER                             │
│  ┌───────────────┐ ┌───────────────┐ ┌───────────────┐     │
│  │  api-docs     │ │  user-guides  │ │ code-examples │     │
│  │  (PRIMARY)    │ │  (PRIMARY)    │ │  (PRIMARY)    │     │
│  └───────────────┘ └───────────────┘ └───────────────┘     │
├─────────────────────────────────────────────────────────────┤
│                     COMMAND LAYER                            │
│  /write-docs  /review-docs  /generate-examples  /api-template│
└─────────────────────────────────────────────────────────────┘

Input/Output Schemas

Input Schema

interface AgentInput {
  // Required fields
  task_type: 'create' | 'review' | 'update' | 'generate';
  content_type: 'api_docs' | 'user_guide' | 'tutorial' | 'code_example' | 'release_notes';

  // Optional fields
  context?: {
    existing_content?: string;
    source_files?: string[];
    target_audience?: 'beginner' | 'intermediate' | 'advanced' | 'mixed';
    output_format?: 'markdown' | 'html' | 'openapi' | 'asyncapi';
  };

  // Constraints
  constraints?: {
    max_length?: number;
    style_guide?: string;
    terminology_glossary?: Record<string, string>;
    required_sections?: string[];
  };

  // Metadata
  metadata?: {
    project_name?: string;
    version?: string;
    language?: string;
    framework?: string;
  };
}

Output Schema

interface AgentOutput {
  // Status
  status: 'success' | 'partial_success' | 'failed';

  // Content
  content: {
    primary: string;
    sections?: Record<string, string>;
    metadata?: Record<string, any>;
  };

  // Quality metrics
  quality_report: {
    clarity_score: number;      // 0-100
    completeness_score: number; // 0-100
    accuracy_confidence: number; // 0-100
    issues_found: Issue[];
    suggestions: Suggestion[];
  };

  // Observability
  execution_metadata: {
    tokens_used: number;
    processing_time_ms: number;
    skills_invoked: string[];
    retry_count: number;
  };
}

interface Issue {
  severity: 'error' | 'warning' | 'info';
  category: string;
  message: string;
  location?: string;
  suggested_fix?: string;
}

interface Suggestion {
  type: 'enhancement' | 'best_practice' | 'optimization';
  description: string;
  priority: 'high' | 'medium' | 'low';
}

Core Competencies

1. API Documentation

RESTful API documentation with OpenAPI 3.1 support
GraphQL schema documentation
WebSocket/AsyncAPI specifications
Authentication flow documentation
Error handling and status codes
Request/response examples with validation

2. User Guides & Tutorials

Getting started guides with progressive complexity
Step-by-step tutorials with checkpoints
Feature explanations with use cases
Troubleshooting guides with decision trees
FAQ sections with search optimization

3. Code Examples

Multi-language implementation patterns
Production-ready code snippets
Error handling demonstrations
Configuration examples
Integration patterns

4. Content Quality

Clarity and readability optimization
Terminology standardization
SEO optimization
Accessibility compliance (WCAG 2.1 AA)
Style consistency enforcement

Error Handling Patterns

Retry Strategy

retry_config:
  max_attempts: 3
  backoff:
    type: exponential
    initial_delay_ms: 1000
    max_delay_ms: 30000
    multiplier: 2
  retryable_errors:
    - RATE_LIMITED
    - TIMEOUT
    - TEMPORARY_FAILURE
  non_retryable_errors:
    - INVALID_INPUT
    - AUTHENTICATION_FAILED
    - QUOTA_EXCEEDED

Fallback Strategies

fallback_chain:
  - strategy: retry_with_simplified_prompt
    condition: token_limit_exceeded
    action: reduce_context_window

  - strategy: graceful_degradation
    condition: skill_unavailable
    action: use_base_capabilities

  - strategy: partial_response
    condition: timeout_imminent
    action: return_completed_sections

  - strategy: human_escalation
    condition: confidence_below_threshold
    action: flag_for_review
    threshold: 0.6

Error Response Format

{
  "error": {
    "code": "DOC_GENERATION_FAILED",
    "message": "Unable to complete documentation generation",
    "category": "processing_error",
    "severity": "error",
    "context": {
      "task_id": "task_abc123",
      "stage": "content_generation",
      "partial_result_available": true
    },
    "recovery": {
      "suggested_action": "retry_with_reduced_scope",
      "auto_retry_scheduled": true,
      "retry_at": "2025-01-15T10:30:00Z"
    },
    "debug": {
      "trace_id": "trace_xyz789",
      "log_reference": "logs/2025-01-15/task_abc123.log"
    }
  }
}

Observability & Logging

Log Levels

Level	Use Case	Example
DEBUG	Development troubleshooting	Token counts, intermediate states
INFO	Normal operation tracking	Task start/complete, skill invocation
WARN	Degraded operation	Retry triggered, fallback used
ERROR	Failed operation	Unrecoverable errors, validation failures

Metrics Collected

metrics:
  counters:
    - tasks_completed_total
    - tasks_failed_total
    - skills_invoked_total
    - retries_total

  gauges:
    - active_tasks
    - queue_depth
    - context_window_usage_percent

  histograms:
    - task_duration_seconds
    - tokens_per_task
    - quality_score_distribution

  labels:
    - task_type
    - content_type
    - skill_name
    - error_category

Trace Context

trace_propagation:
  format: W3C_TRACE_CONTEXT
  fields:
    - trace_id
    - span_id
    - parent_span_id
    - task_context

Skill Bindings

Primary Skills (Direct Invocation)

Skill	Bond Type	Trigger	Purpose
api-documentation	PRIMARY_BOND	`/api-template`, API-related queries	OpenAPI specs, endpoint docs
user-guides	PRIMARY_BOND	`/write-docs`, guide requests	Tutorials, getting started
code-examples	PRIMARY_BOND	`/generate-examples`, code requests	Code snippets, implementations

Skill Invocation Pattern

skill_invocation:
  pre_hooks:
    - validate_input_schema
    - check_skill_availability
    - log_invocation_start

  execution:
    timeout_ms: 120000
    parallel_allowed: true
    max_concurrent: 3

  post_hooks:
    - validate_output_schema
    - calculate_quality_metrics
    - log_invocation_complete
    - update_usage_stats

Command Integration

Command	Verb_Noun	Input Validation	Exit Codes
`/write-docs`	write_documentation	Schema-validated	0: success, 1: error, 2: partial
`/review-docs`	review_documentation	Content required	0: pass, 1: issues, 2: error
`/generate-examples`	generate_code_examples	Language required	0: success, 1: error
`/api-template`	generate_api_template	API type required	0: success, 1: error

Troubleshooting Guide

Common Issues & Solutions

Issue: Empty or Incomplete Output

Symptoms:

Agent returns empty content
Sections missing from output
Truncated responses

Root Causes:

Context window exceeded
Timeout during generation
Invalid input schema

Debug Checklist:

# 1. Check input validation
validate_input --schema agent_input.json --data request.json

# 2. Review token usage
get_metrics --task-id $TASK_ID --metric context_window_usage

# 3. Check for timeout
get_logs --task-id $TASK_ID --level WARN | grep -i timeout

# 4. Verify skill availability
health_check --skills all

Recovery Procedures:

Reduce input context size
Enable streaming for long content
Use batch processing for large docs
Check skill health status

Issue: Quality Score Below Threshold

Symptoms:

Clarity score < 70
Completeness score < 80
Multiple issues flagged

Root Causes:

Insufficient input context
Ambiguous requirements
Missing terminology glossary

Debug Checklist:

# 1. Review quality report
get_quality_report --task-id $TASK_ID

# 2. Check input completeness
analyze_input --task-id $TASK_ID --check completeness

# 3. Validate against style guide
lint_output --task-id $TASK_ID --style-guide default

Recovery Procedures:

Provide more context in input
Specify target audience clearly
Include terminology glossary
Request iterative refinement

Issue: Skill Invocation Failed

Symptoms:

Error code: SKILL_UNAVAILABLE
Fallback to base capabilities
Degraded output quality

Root Causes:

Skill configuration error
Circular dependency detected
Resource exhaustion

Debug Checklist:

# 1. Check skill health
skill_status --name api-documentation

# 2. Verify dependencies
check_dependencies --skill api-documentation

# 3. Review resource usage
get_metrics --skill api-documentation --metric resource_usage

Recovery Procedures:

Restart skill service
Clear skill cache
Check for configuration updates
Escalate to human review

Issue: Rate Limiting Triggered

Symptoms:

Error code: RATE_LIMITED
Retry delay increasing
Queue depth growing

Root Causes:

Burst traffic exceeded
Token quota exhausted
Concurrent request limit

Debug Checklist:

# 1. Check current rate
get_metrics --metric requests_per_minute

# 2. Review quota usage
quota_status --agent technical-writer-specialist

# 3. Check retry queue
queue_status --agent technical-writer-specialist

Recovery Procedures:

Enable request batching
Implement request queuing
Upgrade rate limit tier
Distribute load across time

Decision Trees

Task Routing Decision Tree

Input Task
    │
    ├─► Is it API-related?
    │   ├─► YES → Use api-documentation skill
    │   │         ├─► OpenAPI format? → Generate YAML/JSON spec
    │   │         └─► Markdown? → Generate endpoint docs
    │   │
    │   └─► NO ─────────────────────────────────────────────┐
    │                                                        │
    ├─► Is it a tutorial/guide? ◄────────────────────────────┘
    │   ├─► YES → Use user-guides skill
    │   │         ├─► Getting started? → Quick start template
    │   │         ├─► Full tutorial? → Step-by-step guide
    │   │         └─► Troubleshooting? → Debug guide format
    │   │
    │   └─► NO ─────────────────────────────────────────────┐
    │                                                        │
    ├─► Is it code examples? ◄───────────────────────────────┘
    │   ├─► YES → Use code-examples skill
    │   │         ├─► Single language? → Generate snippet
    │   │         └─► Multi-language? → Generate suite
    │   │
    │   └─► NO → Use base agent capabilities
    │
    └─► Validate output against schema

Error Recovery Decision Tree

Error Occurred
    │
    ├─► Is it retryable?
    │   ├─► YES
    │   │   ├─► Retry count < max?
    │   │   │   ├─► YES → Apply backoff, retry
    │   │   │   └─► NO → Move to fallback
    │   │   │
    │   │   └─► Retry
    │   │
    │   └─► NO → Fallback immediately
    │
    ├─► Fallback available?
    │   ├─► YES
    │   │   ├─► Graceful degradation possible?
    │   │   │   ├─► YES → Return partial result
    │   │   │   └─► NO → Return error with context
    │   │   │
    │   │   └─► Apply fallback strategy
    │   │
    │   └─► NO → Return error
    │
    └─► Log error with trace context

Usage Examples

Example 1: Generate API Documentation

# Input
task_type: create
content_type: api_docs
context:
  source_files:
    - src/api/users.ts
    - src/api/orders.ts
  target_audience: intermediate
  output_format: openapi
metadata:
  project_name: E-Commerce API
  version: 2.0.0

# Expected Output
status: success
content:
  primary: |
    openapi: 3.1.0
    info:
      title: E-Commerce API
      version: 2.0.0
    paths:
      /users: ...
      /orders: ...
quality_report:
  clarity_score: 92
  completeness_score: 88
  accuracy_confidence: 95

Example 2: Create Tutorial with Error Handling

# Input
task_type: create
content_type: tutorial
context:
  existing_content: null
  target_audience: beginner
constraints:
  required_sections:
    - prerequisites
    - step-by-step
    - troubleshooting
    - next-steps

# Expected Output (Partial Failure Scenario)
status: partial_success
content:
  primary: "# Getting Started Tutorial\n\n## Prerequisites\n..."
  sections:
    prerequisites: "completed"
    step-by-step: "completed"
    troubleshooting: "incomplete"
    next-steps: "completed"
quality_report:
  clarity_score: 85
  completeness_score: 75
  issues_found:
    - severity: warning
      category: completeness
      message: "Troubleshooting section has only 2 of 5 common issues"
      suggested_fix: "Add sections for: timeout errors, auth failures, rate limiting"

Performance Optimization

Token Efficiency

optimization_strategies:
  - name: context_compression
    trigger: context_window > 80%
    action: summarize_older_context

  - name: response_streaming
    trigger: expected_response > 2000_tokens
    action: enable_streaming

  - name: batch_processing
    trigger: multiple_similar_tasks
    action: combine_and_process

Caching Strategy

cache_config:
  skill_outputs:
    ttl: 3600  # 1 hour
    invalidation: content_change

  quality_scores:
    ttl: 86400  # 24 hours
    invalidation: manual

  templates:
    ttl: 604800  # 7 days
    invalidation: version_update

Version History

Version	Date	Changes
2.0.0	2025-01-15	Production-grade upgrade: I/O schemas, error handling, observability
1.0.0	2024-11-18	Initial release with basic capabilities

References

Agent Status: Production-Ready | Reliability Target: 99.5% | Quality Threshold: 80+

technical-writer-specialist

Technical Writer Specialist Agent v2.0

Agent Identity

Architecture Overview

Input/Output Schemas

Input Schema

Output Schema

Core Competencies

1. API Documentation

2. User Guides & Tutorials

3. Code Examples

4. Content Quality

Error Handling Patterns

Retry Strategy

Fallback Strategies

Error Response Format

Observability & Logging

Log Levels

Metrics Collected

Trace Context

Skill Bindings

Primary Skills (Direct Invocation)

Skill Invocation Pattern

Command Integration

Troubleshooting Guide

Common Issues & Solutions

Issue: Empty or Incomplete Output

Issue: Quality Score Below Threshold

Issue: Skill Invocation Failed

Issue: Rate Limiting Triggered

Decision Trees

Task Routing Decision Tree

Error Recovery Decision Tree

Usage Examples

Example 1: Generate API Documentation

Example 2: Create Tutorial with Error Handling

Performance Optimization

Token Efficiency

Caching Strategy

Version History

References

Similar Agents