/docs-reference

name: docs-reference
description: Create comprehensive technical reference documentation with complete specifications
version: 1.0.0  
argument-hint: "[system/API to document] [--api|--config|--cli|--complete]"

Diataxis Reference Command

You are in the **REFERENCE** phase of the Diataxis documentation workflow. Your mission is to create comprehensive, accurate, information-oriented documentation that serves as the authoritative source of technical truth.

⚠️ **IMPORTANT**: This command is for creating REFERENCE documentation ONLY. Focus exclusively on:

• Providing complete, accurate technical information
• Structuring for quick lookup and search
• Maintaining consistency and predictability
• Being the authoritative source of truth
• Documenting everything in `docs/reference/[topic-slug].md`

System/API to Document

$ARGUMENTS

If no specific system was provided above, ask the user: "What system, API, or technical component needs reference documentation?"

📖 Reference Objectives

1. **Complete Coverage**: Document every feature, option, and parameter 2. **Consistent Structure**: Predictable organization across entries 3. **Accurate Information**: Technically precise and verified 4. **Quick Lookup**: Optimized for searching and scanning 5. **Authoritative Source**: The definitive technical truth

Extended Thinking Strategy

• **Simple APIs**: Straightforward parameter documentation
• **Complex systems**: Think about hierarchical organization
• **Configuration**: Think hard about dependencies and interactions
• **Enterprise systems**: Ultrathink about completeness and accuracy

Parallel Reference Subagents

Deploy concurrent documentation specialists: @docs-reference-agent @documentation-agent @code-archaeologist @test-generator

All subagents work in parallel to create comprehensive reference:

• @docs-reference-agent: Create structured technical documentation
• @documentation-agent: Generate API documentation and schemas
• @code-archaeologist: Extract undocumented features and parameters
• @test-generator: Validate examples and usage patterns

Reference Documentation Framework

Step 1: Define Scope

## Documentation Scope

### System Overview
- **Name**: [System/API name]
- **Version**: [Version number]
- **Type**: [API/CLI/Configuration/Library]
- **Purpose**: [One-line description]

### Coverage
- Components documented: [count]
- Parameters documented: [count]
- Examples provided: [count]
- Last updated: [date]

Step 2: Structure Organization

## Reference Structure

### Top-Level Organization
1. Overview
2. Core Concepts
3. [Component/Module A]
4. [Component/Module B]
5. Configuration
6. API Reference
7. Error Codes
8. Glossary
9. Index

### Entry Template
Each entry follows:
- Name and signature
- Description
- Parameters/Options
- Return values/Output
- Examples
- Related entries

Step 3: API Documentation

## API Reference

### Endpoints / Functions / Commands

#### `functionName(parameters)`

**Description**: Brief description of what it does

**Signature**:
```language
returnType functionName(
    param1: type,
    param2: type = defaultValue,
    *args,
    **kwargs
)

**Parameters**:

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | param1 | string | Yes | - | Description of param1 | | param2 | number | No | 10 | Description of param2 |

**Returns**:

| Type | Description | |------|-------------| | object | Description of return value |

**Exceptions**:

| Exception | When Raised | |-----------|-------------| | ValueError | When input is invalid | | KeyError | When key not found |

**Example**:

# Basic usage
result = functionName("value", 20)

# With optional parameters
result = functionName(
    param1="value",
    param2=30,
    extra_option=True
)

**See Also**:

• [relatedFunction](#relatedfunction)
• [Configuration](#configuration)

### Step 4: Configuration Reference

```markdown
## Configuration Reference

### Configuration File Structure

```yaml
# config.yaml
system:
  setting1: value    # Required
  setting2: value    # Optional, default: X
  
  subsystem:
    option1: value   # Required
    option2: []      # Optional, default: empty

Configuration Options

`system.setting1`

• **Type**: string
• **Required**: Yes
• **Default**: None
• **Description**: Controls primary system behavior
• **Valid Values**:
• `value1`: Description
• `value2`: Description
• **Example**: `system.setting1: value1`

`system.subsystem.option1`

• **Type**: integer
• **Required**: Yes
• **Range**: 1-1000
• **Description**: Sets subsystem threshold
• **Related**: See `system.subsystem.option2`

### Step 5: CLI Reference

```markdown
## Command-Line Interface

### Global Options
```bash
command [global-options] <subcommand> [options] [arguments]

| Option | Short | Description | Default | |--------|-------|-------------|---------| | --verbose | -v | Increase output verbosity | False | | --config FILE | -c | Specify configuration file | ./config.yaml |

Commands

`command create`

Create a new resource.

**Synopsis**:

command create [options] <name>

**Arguments**:

• `<name>`: Name of the resource to create (required)

**Options**: | Option | Description | Default | |--------|-------------|---------| | --type TYPE | Resource type | standard | | --force | Overwrite if exists | False |

**Examples**:

# Create with defaults
command create myresource

# Create with options
command create --type advanced --force myresource

**Exit Codes**:

• `0`: Success
• `1`: General error
• `2`: Invalid arguments

## Reference Deliverables

### Output File Location

All reference documentation will be generated in the `docs/reference/` directory with descriptive filenames based on the component being documented.

### Reference Template Structure

```markdown
# [System Name] Reference