Name: update-docs
Author: Wizardworks-AB

Prompt file imported from Wizardworks-AB/wizardworks-client-agent-template (.claude/commands/update-docs.md). Copyright stays with the author.

Update Documentation Command

This command helps keep documentation synchronized with code changes. Documentation must be maintained as code evolves to prevent information decay.

Usage

/update-docs                              # Review and update all changed docs
/update-docs MagicService                 # Update docs for specific component
/update-docs api-endpoints                # Update API documentation
/update-docs setup-guide                  # Update setup/installation docs
/update-docs architecture                 # Update architecture documentation
/update-docs --audit                      # Audit all documentation

What This Command Does

Spawns Documentation Agent: Launches documentation specialist
Scans Code Changes: Finds what changed in recent commits
Identifies Outdated Docs: Detects documentation that's out of sync
Suggests Updates: Provides specific documentation updates needed
Generates Examples: Creates code examples from actual code
Validates Links: Checks for broken references and links
Updates API Docs: Regenerates API documentation from code
Maintains Table of Contents: Keeps navigation current

Documentation Types

1. API Documentation

Location: docs/api/

What to Document:

Endpoint URL and method
Request parameters and types
Response format and types
Error codes and messages
Authentication requirements
Rate limiting
Examples

Template:

## Get Magic by ID

**Endpoint**: `GET /api/magic/{publicMagicId}`

**Authentication**: Required (Bearer token)

**Parameters**:
| Name | Type | Required | Description |
|------|------|----------|-------------|
| publicMagicId | string | Yes | Public ID of the magic item |

**Response** (200 OK):
```json
{
  "publicMagicId": "abc123",
  "name": "Fireball",
  "description": "A powerful fire spell",
  "category": "offensive",
  "power": 85,
  "isActive": true,
  "createdAt": "2025-01-23T10:30:00Z"
}

Error Responses:

Code	Message	Description
401	Unauthorized	Missing or invalid authentication
404	Not Found	Magic item not found
500	Internal Error	Server error

Example Request:

curl -X GET https://api.wizardworks.com/api/magic/abc123 \
  -H "Authorization: Bearer YOUR_TOKEN"

Example Response:

{
  "publicMagicId": "abc123",
  "name": "Fireball",
  "description": "A powerful fire spell",
  "category": "offensive",
  "power": 85,
  "isActive": true,
  "createdAt": "2025-01-23T10:30:00Z"
}


### 2. Architecture Documentation

**Location**: `docs/architecture/`

**What to Document**:
- System design and diagram
- Component responsibilities
- Data flow
- Integration points
- Technology choices with rationale
- Deployment architecture

**Template**:
```markdown
# Magic Service Architecture

## Overview

The Magic Service manages creation, retrieval, and management of magic items in Wizardworks.

## Architecture Diagram

┌──────────────────┐ │ React Client │ └────────┬─────────┘ │ REST API ┌────────▼──────────────────────┐ │ Magic API (.NET Core) │ │ ┌────────────────────────┐ │ │ │ Controllers │ │ │ │ - MagicController │ │ │ └────────┬───────────────┘ │ │ │ │ │ ┌────────▼───────────────┐ │ │ │ Services │ │ │ │ - MagicService │ │ │ │ - SearchService │ │ │ └────────┬───────────────┘ │ │ │ │ │ ┌────────▼───────────────┐ │ │ │ Repositories │ │ │ │ - MagicRepository │ │ │ └────────┬───────────────┘ │ └────────┬──────────────────────┘ │ EF Core ┌────────▼──────────────┐ │ SQL Database │ │ - Magics table │ │ - Indexes │ └───────────────────────┘


## Components

### Controllers
- **MagicController**: Handles HTTP requests for magic CRUD operations
- Validates input using DTOs
- Returns appropriate HTTP status codes
- Never exposes database IDs

### Services
- **MagicService**: Core business logic for magic operations
- Generates public IDs
- Manages transactions
- Handles validation

- **SearchService**: Advanced search and filtering
- Text search with scoring
- Faceted filtering
- Caching for performance

### Repositories
- **MagicRepository**: Data access layer
- Uses Entity Framework Core
- Implements query optimization
- Handles database transactions

## Data Models

### Entity (Database)
```csharp
public class Magic
{
    public int MagicId { get; set; }              // Internal DB ID
    public string PublicMagicId { get; set; }     // External Public ID
    public string Name { get; set; }
    public string? Description { get; set; }
    public string Category { get; set; }
    public int Power { get; set; }
    public DateTime CreatedAt { get; set; }
    public DateTime? UpdatedAt { get; set; }
    public bool IsActive { get; set; }
}

DTO (API)

public class MagicDto
{
    public string PublicMagicId { get; set; }     // Only public ID
    public string Name { get; set; }
    public string? Description { get; set; }
    public string Category { get; set; }
    public int Power { get; set; }
    public DateTime CreatedAt { get; set; }
    public bool IsActive { get; set; }
}

Key Design Decisions

Public ID Pattern

All external APIs use Public IDs (UUIDs)
Database IDs never exposed
Provides security through obscurity
See: decisions/public-id-pattern.md

Controller-Service-Repository

Clear separation of concerns
Testable layers
Service layer contains business logic
See: decisions/layered-architecture.md

Troubleshooting

Issue: Migration Failed

error: Unable to determine a valid ordering of the set of migrations

Solution:

# Remove the problematic migration
dotnet ef migrations remove

# Create a new one
dotnet ef migrations add FixedMigration

# Apply to database
dotnet ef database update

Issue: Tests Fail Locally but Pass in CI

Verify database is running
Check connection string
Clear test cache: dotnet test --no-build --configuration Release /t:Rebuild

Using the Wizardworks CLI

All Wizardworks commands:

/tdd - Test-driven development
/code-review - Code quality review
/security-review - Security scan
/plan - Architecture planning
/build-fix - Fix build errors
/e2e - End-to-end testing
/refactor-clean - Code refactoring
/update-docs - Update documentation


### 4. Configuration Documentation

**Location**: `docs/configuration/`

**What to Document**:
- Environment variables
- Configuration files
- Secrets management
- Feature flags
- Deployment configurations

**Template**:
```markdown
# Magic Service Configuration

## Environment Variables

| Variable | Type | Required | Description | Example |
|----------|------|----------|-------------|---------|
| ConnectionStrings__DefaultConnection | string | Yes | Database connection | Server=localhost;Database=wizardworks |
| OpenAI__ApiKey | string | Yes | OpenAI API key | sk-... |
| AzureAd__Authority | string | Yes | Azure AD authority | https://login.microsoftonline.com/common |
| AzureAd__ClientId | string | Yes | Azure AD client ID | xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx |
| AzureAd__ClientSecret | string | Yes | Azure AD secret | xxxxxxxxxxxxxx |
| Logging__LogLevel__Default | string | No | Log level | Information |
| ASPNETCORE_ENVIRONMENT | string | No | Environment | Development/Staging/Production |

## Local Development (.env)

```bash
# Create .env file (in .gitignore)
ConnectionStrings__DefaultConnection=Server=localhost;Database=wizardworks;User Id=sa;Password=YourPassword;
OpenAI__ApiKey=your-test-key
AzureAd__Authority=https://login.microsoftonline.com/common
AzureAd__ClientId=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
AzureAd__ClientSecret=test-secret
ASPNETCORE_ENVIRONMENT=Development
Logging__LogLevel__Default=Information

Production Configuration

See deployment/bicep/parameters.prod.json

Secrets are managed via Azure Key Vault:

All sensitive values in Key Vault
Application references Key Vault URIs
No secrets in configuration files


### 5. Database Schema Documentation

**Location**: `docs/database/`

**What to Document**:
- Table schemas
- Relationships
- Indexes
- Migration history

**Template**:
```markdown
# Database Schema

## Magics Table

```sql
CREATE TABLE Magics (
    MagicId INT PRIMARY KEY IDENTITY(1,1),
    PublicMagicId NVARCHAR(12) UNIQUE NOT NULL,
    Name NVARCHAR(200) NOT NULL,
    Description NVARCHAR(MAX) NULL,
    Category NVARCHAR(50) NOT NULL,
    Power INT NOT NULL CHECK (Power >= 0 AND Power <= 100),
    IsActive BIT NOT NULL DEFAULT 1,
    CreatedAt DATETIME2 NOT NULL DEFAULT GETUTCDATE(),
    UpdatedAt DATETIME2 NULL,
    CONSTRAINT idx_magic_name UNIQUE (Name)
);

CREATE INDEX idx_magic_category ON Magics(Category);
CREATE INDEX idx_magic_active ON Magics(IsActive);
CREATE INDEX idx_magic_public_id ON Magics(PublicMagicId);

Relationships

Magics → Categories (FK: Category)
Users → Magic (many-to-many through UserMagicFavorites)

Indexes

Table	Column	Type	Purpose
Magics	PublicMagicId	Unique	Fast public ID lookups
Magics	Category	Standard	Category filtering
Magics	IsActive	Standard	Active status filtering
Magics	Name	Unique	Prevent duplicates


## Maintaining Documentation

### When to Update

Update documentation when:
- Adding new API endpoints
- Changing data models
- Modifying architecture
- Adding configuration options
- Updating deployment process
- Fixing bugs (if documentation-related)
- Adding features

### Documentation Quality Checklist

- [ ] Accurate and current
- [ ] Examples are valid and tested
- [ ] All code examples work
- [ ] Links are valid and not broken
- [ ] Consistent formatting
- [ ] Clear and concise language
- [ ] Table of contents is current
- [ ] API docs match actual endpoints
- [ ] Setup instructions work end-to-end
- [ ] Architecture diagrams are accurate
- [ ] Configuration docs complete
- [ ] Troubleshooting section helpful

## Documentation Tools & Standards

### Markdown Standards

```markdown
# Main Title (H1)

## Section (H2)

### Subsection (H3)

- Bullet point
- Another point

1. Numbered list
2. Second item

**Bold text**
*Italic text*

`code snippet`

\`\`\`language
code block
\`\`\`

| Header 1 | Header 2 |
|----------|----------|
| Value 1 | Value 2 |

Code Examples

Always include:

What the code does
Prerequisites
Step-by-step instructions
Expected output
Common errors

Diagrams

Use ASCII art or Mermaid:

graph TD
    A[Client] -->|HTTP Request| B[Controller]
    B -->|Business Logic| C[Service]
    C -->|Query| D[Repository]
    D -->|SQL| E[Database]

Automated Documentation Generation

API Documentation (Swagger/OpenAPI)

// Program.cs
builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new OpenApiInfo
    {
        Title = "Magic Service API",
        Version = "v1",
        Description = "Wizardworks Magic Management API"
    });

    var xmlFilename = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    options.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, xmlFilename));
});

app.UseSwagger();
app.UseSwaggerUI();

XML Comments for API

/// <summary>
/// Creates a new magic item
/// </summary>
/// <param name="dto">Magic creation data</param>
/// <returns>Created magic item</returns>
/// <remarks>
/// Sample request:
///
///     POST /api/magic
///     {
///        "name": "Fireball",
///        "description": "A fire spell",
///        "category": "offensive",
///        "power": 85
///     }
/// </remarks>
/// <response code="201">Magic item created successfully</response>
/// <response code="400">Invalid input</response>
/// <response code="401">Unauthorized</response>
[HttpPost]
[ProducesResponseType(StatusCodes.Status201Created)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public async Task<IActionResult> Create([FromBody] CreateMagicDto dto)
{
    var result = await _service.CreateAsync(dto);
    return CreatedAtAction(nameof(Get), new { publicMagicId = result.PublicMagicId }, result);
}

Documentation Audit

Periodically audit documentation:

# Check for broken links
npm install -g markdown-link-check
find docs -name "*.md" -exec markdown-link-check {} \;

# Generate word count
wc -w docs/**/*.md

# Find outdated references
grep -r "TODO\|FIXME\|DEPRECATED" docs/

When to Use This Command

After implementing new features
After API changes
After architecture changes
During code reviews
Before releases
When onboarding new team members
When documentation audit due
After fixing bugs that affected docs

Related Commands

Use /code-review to identify documentation gaps
Use /plan when documenting architecture
Use /refactor-clean when restructuring code

As a Wizardworks Employee

Documentation is as important as code. Good documentation:

Enables team productivity
Reduces onboarding time
Prevents bugs
Makes systems maintainable
Preserves institutional knowledge

Remember: If it's not documented, it doesn't exist. Keep docs current.

Install update-docs and it becomes one more candidate the router can pick - when it fits.

A listing is a routing target with a manifest: what it does, which domains it covers, what it costs and who publishes it. Once installed it sits beside your own models and tools, is scored like any other candidate for each request, and shows up in the trace when it wins. Ratings come from workspaces that installed it, one per account.

# Update Documentation Command This command helps keep documentation synchronized with code changes. Documentation must be maintained as code evolves to prevent information decay. ## Usage ```bash /update-docs # Review and update all changed docs /update-docs MagicService # Update docs for specific component /update-docs api-endpoints # Update API documentation /update-docs setup-guide # Update setup/installation docs /update-docs architecture # Update architecture documentation /update-docs --audit # Audit all documentation ``` ## What This Command Does 1. **Spawns Documentation Agent**: Launches documentation specialist 2. **Scans Code Changes**: Finds what changed in recent commits 3. **Identifies Outdated Docs**: Detects documentation that's out of sync 4. **Suggests Updates**: Provides specific documentation updates needed 5. **Generates Examples**: Creates code examples from actual code 6. **Validates Links**: Checks for broken references and links 7. **Updates API Docs**: Regenerates API documentation from code 8. **Maintains Table of Contents**: Keeps navigation current ## Documentation Types ### 1. API Documentation **Location**: `docs/api/` **What to Document**: - Endpoint URL and method - Request parameters and types - Response format and types - Error codes and messages - Authentication requirements - Rate limiting - Examples **Template**: ```markdown ## Get Magic by ID **Endpoint**: `GET /api/magic/{publicMagicId}` **Authentication**: Required (Bearer token) **Parameters**: | Name | Type | Required | Description | |------|------|----------|-------------| | publicMagicId | string | Yes | Public ID of the magic item | **Response** (200 OK): ```json { "publicMagicId": "abc123", "name": "Fireball", "description": "A powerful fire spell", "category": "offensive", "power": 85, "isActive": true, "createdAt": "2025-01-23T10:30:00Z" } ``` **Error Responses**: | Code | Message | Description | |------|---------|-------------| | 401 | Unauthorized | Missing or invalid authentication | | 404 | Not Found | Magic item not found | | 500 | Internal Error | Server error | **Example Request**: ```bash curl -X GET https://api.wizardworks.com/api/magic/abc123 \ -H "Authorization: Bearer YOUR_TOKEN" ``` **Example Response**: ```json { "publicMagicId": "abc123", "name": "Fireball", "description": "A powerful fire spell", "category": "offensive", "power": 85, "isActive": true, "createdAt": "2025-01-23T10:30:00Z" } ``` ``` ### 2. Architecture Documentation **Location**: `docs/architecture/` **What to Document**: - System design and diagram - Component responsibilities - Data flow - Integration points - Technology choices with rationale - Deployment architecture **Template**: ```markdown # Magic Service Architecture ## Overview The Magic Service manages creation, retrieval, and management of magic items in Wizardworks. ## Architecture Diagram ``` ┌──────────────────┐ │ React Client │ └────────┬─────────┘ │ REST API ┌────────▼──────────────────────┐ │ Magic API (.NET Core) │ │ ┌────────────────────────┐ │ │ │ Controllers │ │ │ │ - MagicController │ │ │ └────────┬───────────────┘ │ │ │ │ │ ┌────────▼───────────────┐ │ │ │ Services │ │ │ │ - MagicService │ │ │ │ - SearchService │ │ │ └────────┬───────────────┘ │ │ │ │ │ ┌────────▼───────────────┐ │ │ │ Repositories │ │ │ │ - MagicRepository │ │ │ └────────┬───────────────┘ │ └────────┬──────────────────────┘ │ EF Core ┌────────▼──────────────┐ │ SQL Database │ │ - Magics table │ │ - Indexes │ └───────────────────────┘ ``` ## Components ### Controllers - **MagicController**: Handles HTTP requests for magic CRUD operations - Validates input using DTOs - Returns appropriate HTTP status codes - Never exposes database IDs ### Services - **MagicService**: Core business logic for magic operations - Generates public IDs - Manages transactions - Handles validation - **SearchService**: Advanced search and filtering - Text search with scoring - Faceted filtering - Caching for performance ### Repositories - **MagicRepository**: Data access layer - Uses Entity Framework Core - Implements query optimization - Handles database transactions ## Data Models ### Entity (Database) ```csharp public class Magic { public int MagicId { get; set; } // Internal DB ID public string PublicMagicId { get; set; } // External Public ID public string Name { get; set; } public string? Description { get; set; } public string Category { get; set; } public int Power { get; set; } public DateTime CreatedAt { get; set; } public DateTime? UpdatedAt { get; set; } public bool IsActive { get; set; } } ``` ### DTO (API) ```csharp public class MagicDto { public string PublicMagicId { get; set; } // Only public ID public string Name { get; set; } public string? Description { get; set; } public string Category { get; set; } public int Power { get; set; } public DateTime CreatedAt { get; set; } public bool IsActive { get; set; } } ``` ## Key Design Decisions ### Public ID Pattern - All external APIs use Public IDs (UUIDs) - Database IDs never exposed - Provides security through obscurity - See: `decisions/public-id-pattern.md` ### Controller-Service-Repository - Clear separation of concerns - Testable layers - Service layer contains business logic - See: `decisions/layered-architecture.md` ## Related Documentation - API Documentation: `docs/api/magic/` - Database Schema: `docs/database/schema.md` - Deployment Guide: `docs/deployment/` ``` ### 3. Developer Guide **Location**: `docs/guides/` **What to Document**: - How to set up development environment - How to run the application locally - How to run tests - How to build Docker container - How to deploy - Common troubleshooting **Template**: ```markdown # Magic Service Developer Guide ## Local Development Setup ### Prerequisites - .NET 9 SDK or later - SQL Server 2019+ or PostgreSQL 13+ - Git ### Clone Repository ```bash git clone https://github.com/wizardworks/magic-service.git cd magic-service ``` ### Configure Database #### Option 1: SQL Server (Local) ```bash # Create database sqlcmd -S localhost -U sa -P YourPassword -Q "CREATE DATABASE Wizardworks" # Update connection string dotnet user-secrets set "ConnectionStrings:DefaultConnection" \ "Server=localhost;Database=Wizardworks;User Id=sa;Password=YourPassword;" ``` #### Option 2: PostgreSQL (Docker) ```bash # Start PostgreSQL docker run --name postgres -e POSTGRES_PASSWORD=password -p 5432:5432 -d postgres:15 # Create database docker exec postgres psql -U postgres -c "CREATE DATABASE wizardworks" # Update connection string dotnet user-secrets set "ConnectionStrings:DefaultConnection" \ "Server=localhost;Port=5432;Database=wizardworks;User Id=postgres;Password=password;" ``` ### Apply Migrations ```bash # Create migration dotnet ef migrations add InitialCreate # Apply to database dotnet ef database update ``` ### Run Locally ```bash # Restore dependencies dotnet restore # Run application dotnet run # Application starts at: https://localhost:5001 ``` ### Running Tests ```bash # Run all tests dotnet test # Run with coverage dotnet test /p:CollectCoverage=true /p:CoverletOutputFormat=opencover # View coverage report reportgenerator -reports:coverage.opencover.xml -targetdir:coverage-report open coverage-report/index.html ``` ### Docker Development ```bash # Build Docker image docker build -t magic-service:latest . # Run container docker run -p 5001:5001 \ -e ConnectionStrings__DefaultConnection="Server=postgres;Database=wizardworks;User Id=postgres;Password=password;" \ magic-service:latest ``` ## Troubleshooting ### Issue: Migration Failed ``` error: Unable to determine a valid ordering of the set of migrations ``` **Solution**: ```bash # Remove the problematic migration dotnet ef migrations remove # Create a new one dotnet ef migrations add FixedMigration # Apply to database dotnet ef database update ``` ### Issue: Tests Fail Locally but Pass in CI - Verify database is running - Check connection string - Clear test cache: `dotnet test --no-build --configuration Release /t:Rebuild` ## Using the Wizardworks CLI All Wizardworks commands: - `/tdd` - Test-driven development - `/code-review` - Code quality review - `/security-review` - Security scan - `/plan` - Architecture planning - `/build-fix` - Fix build errors - `/e2e` - End-to-end testing - `/refactor-clean` - Code refactoring - `/update-docs` - Update documentation ``` ### 4. Configuration Documentation **Location**: `docs/configuration/` **What to Document**: - Environment variables - Configuration files - Secrets management - Feature flags - Deployment configurations **Template**: ```markdown # Magic Service Configuration ## Environment Variables | Variable | Type | Required | Description | Example | |----------|------|----------|-------------|---------| | ConnectionStrings__DefaultConnection | string | Yes | Database connection | Server=localhost;Database=wizardworks | | OpenAI__ApiKey | string | Yes | OpenAI API key | sk-... | | AzureAd__Authority | string | Yes | Azure AD authority | https://login.microsoftonline.com/common | | AzureAd__ClientId | string | Yes | Azure AD client ID | xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx | | AzureAd__ClientSecret | string | Yes | Azure AD secret | xxxxxxxxxxxxxx | | Logging__LogLevel__Default | string | No | Log level | Information | | ASPNETCORE_ENVIRONMENT | string | No | Environment | Development/Staging/Production | ## Local Development (.env) ```bash # Create .env file (in .gitignore) ConnectionStrings__DefaultConnection=Server=localhost;Database=wizardworks;User Id=sa;Password=YourPassword; OpenAI__ApiKey=your-test-key AzureAd__Authority=https://login.microsoftonline.com/common AzureAd__ClientId=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx AzureAd__ClientSecret=test-secret ASPNETCORE_ENVIRONMENT=Development Logging__LogLevel__Default=Information ``` ## Production Configuration See `deployment/bicep/parameters.prod.json` Secrets are managed via Azure Key Vault: - All sensitive values in Key Vault - Application references Key Vault URIs - No secrets in configuration files ``` ### 5. Database Schema Documentation **Location**: `docs/database/` **What to Document**: - Table schemas - Relationships - Indexes - Migration history **Template**: ```markdown # Database Schema ## Magics Table ```sql CREATE TABLE Magics ( MagicId INT PRIMARY KEY IDENTITY(1,1), PublicMagicId NVARCHAR(12) UNIQUE NOT NULL, Name NVARCHAR(200) NOT NULL, Description NVARCHAR(MAX) NULL, Category NVARCHAR(50) NOT NULL, Power INT NOT NULL CHECK (Power >= 0 AND Power <= 100), IsActive BIT NOT NULL DEFAULT 1, CreatedAt DATETIME2 NOT NULL DEFAULT GETUTCDATE(), UpdatedAt DATETIME2 NULL, CONSTRAINT idx_magic_name UNIQUE (Name) ); CREATE INDEX idx_magic_category ON Magics(Category); CREATE INDEX idx_magic_active ON Magics(IsActive); CREATE INDEX idx_magic_public_id ON Magics(PublicMagicId); ``` ## Relationships - Magics → Categories (FK: Category) - Users → Magic (many-to-many through UserMagicFavorites) ## Indexes | Table | Column | Type | Purpose | |-------|--------|------|---------| | Magics | PublicMagicId | Unique | Fast public ID lookups | | Magics | Category | Standard | Category filtering | | Magics | IsActive | Standard | Active status filtering | | Magics | Name | Unique | Prevent duplicates | ``` ## Maintaining Documentation ### When to Update Update documentation when: - Adding new API endpoints - Changing data models - Modifying architecture - Adding configuration options - Updating deployment process - Fixing bugs (if documentation-related) - Adding features ### Documentation Quality Checklist - [ ] Accurate and current - [ ] Examples are valid and tested - [ ] All code examples work - [ ] Links are valid and not broken - [ ] Consistent formatting - [ ] Clear and concise language - [ ] Table of contents is current - [ ] API docs match actual endpoints - [ ] Setup instructions work end-to-end - [ ] Architecture diagrams are accurate - [ ] Configuration docs complete - [ ] Troubleshooting section helpful ## Documentation Tools & Standards ### Markdown Standards ```markdown # Main Title (H1) ## Section (H2) ### Subsection (H3) - Bullet point - Another point 1. Numbered list 2. Second item **Bold text** *Italic text* `code snippet` \`\`\`language code block \`\`\` | Header 1 | Header 2 | |----------|----------| | Value 1 | Value 2 | ``` ### Code Examples Always include: - What the code does - Prerequisites - Step-by-step instructions - Expected output - Common errors ### Diagrams Use ASCII art or Mermaid: ```mermaid graph TD A[Client] -->|HTTP Request| B[Controller] B -->|Business Logic| C[Service] C -->|Query| D[Repository] D -->|SQL| E[Database] ``` ## Automated Documentation Generation ### API Documentation (Swagger/OpenAPI) ```csharp // Program.cs builder.Services.AddSwaggerGen(options => { options.SwaggerDoc("v1", new OpenApiInfo { Title = "Magic Service API", Version = "v1", Description = "Wizardworks Magic Management API" }); var xmlFilename = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml"; options.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, xmlFilename)); }); app.UseSwagger(); app.UseSwaggerUI(); ``` ### XML Comments for API ```csharp /// <summary> /// Creates a new magic item /// </summary> /// <param name="dto">Magic creation data</param> /// <returns>Created magic item</returns> /// <remarks> /// Sample request: /// /// POST /api/magic /// { /// "name": "Fireball", /// "description": "A fire spell", /// "category": "offensive", /// "power": 85 /// } /// </remarks> /// <response code="201">Magic item created successfully</response> /// <response code="400">Invalid input</response> /// <response code="401">Unauthorized</response> [HttpPost] [ProducesResponseType(StatusCodes.Status201Created)] [ProducesResponseType(StatusCodes.Status400BadRequest)] public async Task<IActionResult> Create([FromBody] CreateMagicDto dto) { var result = await _service.CreateAsync(dto); return CreatedAtAction(nameof(Get), new { publicMagicId = result.PublicMagicId }, result); } ``` ## Documentation Audit Periodically audit documentation: ```bash # Check for broken links npm install -g markdown-link-check find docs -name "*.md" -exec markdown-link-check {} \; # Generate word count wc -w docs/**/*.md # Find outdated references grep -r "TODO\|FIXME\|DEPRECATED" docs/ ``` ## When to Use This Command - **After implementing new features** - **After API changes** - **After architecture changes** - **During code reviews** - **Before releases** - **When onboarding new team members** - **When documentation audit due** - **After fixing bugs that affected docs** ## Related Commands - Use `/code-review` to identify documentation gaps - Use `/plan` when documenting architecture - Use `/refactor-clean` when restructuring code ## As a Wizardworks Employee Documentation is as important as code. Good documentation: - Enables team productivity - Reduces onboarding time - Prevents bugs - Makes systems maintainable - Preserves institutional knowledge **Remember**: If it's not documented, it doesn't exist. Keep docs current.

{ "prompt": "# Update Documentation Command\n\nThis command helps keep documentation synchronized with code changes. Documentation must be maintained as code evolves to prevent information decay.\n\n## Usage\n\n```bash\n/update-docs # Review and update all changed docs\n/update-docs MagicService # Update docs for specific component\n/update-docs api-endpoints # Update API documentation\n/update-docs setup-guide # Update setup/installation docs\n/update-docs architecture # Update architecture documentation\n/update-docs --audit # Audit all documentation\n```\n\n## What This Command Does\n\n1. **Spawns Documentation Agent**: Launches documentation specialist\n2. **Scans Code Changes**: Finds what changed in recent commits\n3. **Identifies Outdated Docs**: Detects documentation that's out of sync\n4. **Suggests Updates**: Provides specific documentation updates needed\n5. **Generates Examples**: Creates code examples from actual code\n6. **Validates Links**: Checks for broken references and links\n7. **Updates API Docs**: Regenerates API documentation from code\n8. **Maintains Table of Contents**: Keeps navigation current\n\n## Documentation Types\n\n### 1. API Documentation\n\n**Location**: `docs/api/`\n\n**What to Document**:\n- Endpoint URL and method\n- Request parameters and types\n- Response format and types\n- Error codes and messages\n- Authentication requirements\n- Rate limiting\n- Examples\n\n**Template**:\n```markdown\n## Get Magic by ID\n\n**Endpoint**: `GET /api/magic/{publicMagicId}`\n\n**Authentication**: Required (Bearer token)\n\n**Parameters**:\n| Name | Type | Required | Description |\n|------|------|----------|-------------|\n| publicMagicId | string | Yes | Public ID of the magic item |\n\n**Response** (200 OK):\n```json\n{\n \"publicMagicId\": \"abc123\",\n \"name\": \"Fireball\",\n \"description\": \"A powerful fire spell\",\n \"category\": \"offensive\",\n \"power\": 85,\n \"isActive\": true,\n \"createdAt\": \"2025-01-23T10:30:00Z\"\n}\n```\n\n**Error Responses**:\n| Code | Message | Description |\n|------|---------|-------------|\n| 401 | Unauthorized | Missing or invalid authentication |\n| 404 | Not Found | Magic item not found |\n| 500 | Internal Error | Server error |\n\n**Example Request**:\n```bash\ncurl -X GET https://api.wizardworks.com/api/magic/abc123 \\\n -H \"Authorization: Bearer YOUR_TOKEN\"\n```\n\n**Example Response**:\n```json\n{\n \"publicMagicId\": \"abc123\",\n \"name\": \"Fireball\",\n \"description\": \"A powerful fire spell\",\n \"category\": \"offensive\",\n \"power\": 85,\n \"isActive\": true,\n \"createdAt\": \"2025-01-23T10:30:00Z\"\n}\n```\n```\n\n### 2. Architecture Documentation\n\n**Location**: `docs/architecture/`\n\n**What to Document**:\n- System design and diagram\n- Component responsibilities\n- Data flow\n- Integration points\n- Technology choices with rationale\n- Deployment architecture\n\n**Template**:\n```markdown\n# Magic Service Architecture\n\n## Overview\n\nThe Magic Service manages creation, retrieval, and management of magic items in Wizardworks.\n\n## Architecture Diagram\n\n```\n┌──────────────────┐\n│ React Client │\n└────────┬─────────┘\n │ REST API\n┌────────▼──────────────────────┐\n│ Magic API (.NET Core) │\n│ ┌────────────────────────┐ │\n│ │ Controllers │ │\n│ │ - MagicController │ │\n│ └────────┬───────────────┘ │\n│ │ │\n│ ┌────────▼───────────────┐ │\n│ │ Services │ │\n│ │ - MagicService │ │\n│ │ - SearchService │ │\n│ └────────┬───────────────┘ │\n│ │ │\n│ ┌────────▼───────────────┐ │\n│ │ Repositories │ │\n│ │ - MagicRepository │ │\n│ └────────┬───────────────┘ │\n└────────┬──────────────────────┘\n │ EF Core\n┌────────▼──────────────┐\n│ SQL Database │\n│ - Magics table │\n│ - Indexes │\n└───────────────────────┘\n```\n\n## Components\n\n### Controllers\n- **MagicController**: Handles HTTP requests for magic CRUD operations\n- Validates input using DTOs\n- Returns appropriate HTTP status codes\n- Never exposes database IDs\n\n### Services\n- **MagicService**: Core business logic for magic operations\n- Generates public IDs\n- Manages transactions\n- Handles validation\n\n- **SearchService**: Advanced search and filtering\n- Text search with scoring\n- Faceted filtering\n- Caching for performance\n\n### Repositories\n- **MagicRepository**: Data access layer\n- Uses Entity Framework Core\n- Implements query optimization\n- Handles database transactions\n\n## Data Models\n\n### Entity (Database)\n```csharp\npublic class Magic\n{\n public int MagicId { get; set; } // Internal DB ID\n public string PublicMagicId { get; set; } // External Public ID\n public string Name { get; set; }\n public string? Description { get; set; }\n public string Category { get; set; }\n public int Power { get; set; }\n public DateTime CreatedAt { get; set; }\n public DateTime? UpdatedAt { get; set; }\n public bool IsActive { get; set; }\n}\n```\n\n### DTO (API)\n```csharp\npublic class MagicDto\n{\n public string PublicMagicId { get; set; } // Only public ID\n public string Name { get; set; }\n public string? Description { get; set; }\n public string Category { get; set; }\n public int Power { get; set; }\n public DateTime CreatedAt { get; set; }\n public bool IsActive { get; set; }\n}\n```\n\n## Key Design Decisions\n\n### Public ID Pattern\n- All external APIs use Public IDs (UUIDs)\n- Database IDs never exposed\n- Provides security through obscurity\n- See: `decisions/public-id-pattern.md`\n\n### Controller-Service-Repository\n- Clear separation of concerns\n- Testable layers\n- Service layer contains business logic\n- See: `decisions/layered-architecture.md`\n\n## Related Documentation\n- API Documentation: `docs/api/magic/`\n- Database Schema: `docs/database/schema.md`\n- Deployment Guide: `docs/deployment/`\n```\n\n### 3. Developer Guide\n\n**Location**: `docs/guides/`\n\n**What to Document**:\n- How to set up development environment\n- How to run the application locally\n- How to run tests\n- How to build Docker container\n- How to deploy\n- Common troubleshooting\n\n**Template**:\n```markdown\n# Magic Service Developer Guide\n\n## Local Development Setup\n\n### Prerequisites\n- .NET 9 SDK or later\n- SQL Server 2019+ or PostgreSQL 13+\n- Git\n\n### Clone Repository\n```bash\ngit clone https://github.com/wizardworks/magic-service.git\ncd magic-service\n```\n\n### Configure Database\n\n#### Option 1: SQL Server (Local)\n```bash\n# Create database\nsqlcmd -S localhost -U sa -P YourPassword -Q \"CREATE DATABASE Wizardworks\"\n\n# Update connection string\ndotnet user-secrets set \"ConnectionStrings:DefaultConnection\" \\\n \"Server=localhost;Database=Wizardworks;User Id=sa;Password=YourPassword;\"\n```\n\n#### Option 2: PostgreSQL (Docker)\n```bash\n# Start PostgreSQL\ndocker run --name postgres -e POSTGRES_PASSWORD=password -p 5432:5432 -d postgres:15\n\n# Create database\ndocker exec postgres psql -U postgres -c \"CREATE DATABASE wizardworks\"\n\n# Update connection string\ndotnet user-secrets set \"ConnectionStrings:DefaultConnection\" \\\n \"Server=localhost;Port=5432;Database=wizardworks;User Id=postgres;Password=password;\"\n```\n\n### Apply Migrations\n```bash\n# Create migration\ndotnet ef migrations add InitialCreate\n\n# Apply to database\ndotnet ef database update\n```\n\n### Run Locally\n```bash\n# Restore dependencies\ndotnet restore\n\n# Run application\ndotnet run\n\n# Application starts at: https://localhost:5001\n```\n\n### Running Tests\n```bash\n# Run all tests\ndotnet test\n\n# Run with coverage\ndotnet test /p:CollectCoverage=true /p:CoverletOutputFormat=opencover\n\n# View coverage report\nreportgenerator -reports:coverage.opencover.xml -targetdir:coverage-report\nopen coverage-report/index.html\n```\n\n### Docker Development\n```bash\n# Build Docker image\ndocker build -t magic-service:latest .\n\n# Run container\ndocker run -p 5001:5001 \\\n -e ConnectionStrings__DefaultConnection=\"Server=postgres;Database=wizardworks;User Id=postgres;Password=password;\" \\\n magic-service:latest\n```\n\n## Troubleshooting\n\n### Issue: Migration Failed\n```\nerror: Unable to determine a valid ordering of the set of migrations\n```\n\n**Solution**:\n```bash\n# Remove the problematic migration\ndotnet ef migrations remove\n\n# Create a new one\ndotnet ef migrations add FixedMigration\n\n# Apply to database\ndotnet ef database update\n```\n\n### Issue: Tests Fail Locally but Pass in CI\n- Verify database is running\n- Check connection string\n- Clear test cache: `dotnet test --no-build --configuration Release /t:Rebuild`\n\n## Using the Wizardworks CLI\n\nAll Wizardworks commands:\n- `/tdd` - Test-driven development\n- `/code-review` - Code quality review\n- `/security-review` - Security scan\n- `/plan` - Architecture planning\n- `/build-fix` - Fix build errors\n- `/e2e` - End-to-end testing\n- `/refactor-clean` - Code refactoring\n- `/update-docs` - Update documentation\n```\n\n### 4. Configuration Documentation\n\n**Location**: `docs/configuration/`\n\n**What to Document**:\n- Environment variables\n- Configuration files\n- Secrets management\n- Feature flags\n- Deployment configurations\n\n**Template**:\n```markdown\n# Magic Service Configuration\n\n## Environment Variables\n\n| Variable | Type | Required | Description | Example |\n|----------|------|----------|-------------|---------|\n| ConnectionStrings__DefaultConnection | string | Yes | Database connection | Server=localhost;Database=wizardworks |\n| OpenAI__ApiKey | string | Yes | OpenAI API key | sk-... |\n| AzureAd__Authority | string | Yes | Azure AD authority | https://login.microsoftonline.com/common |\n| AzureAd__ClientId | string | Yes | Azure AD client ID | xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx |\n| AzureAd__ClientSecret | string | Yes | Azure AD secret | xxxxxxxxxxxxxx |\n| Logging__LogLevel__Default | string | No | Log level | Information |\n| ASPNETCORE_ENVIRONMENT | string | No | Environment | Development/Staging/Production |\n\n## Local Development (.env)\n\n```bash\n# Create .env file (in .gitignore)\nConnectionStrings__DefaultConnection=Server=localhost;Database=wizardworks;User Id=sa;Password=YourPassword;\nOpenAI__ApiKey=your-test-key\nAzureAd__Authority=https://login.microsoftonline.com/common\nAzureAd__ClientId=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\nAzureAd__ClientSecret=test-secret\nASPNETCORE_ENVIRONMENT=Development\nLogging__LogLevel__Default=Information\n```\n\n## Production Configuration\n\nSee `deployment/bicep/parameters.prod.json`\n\nSecrets are managed via Azure Key Vault:\n- All sensitive values in Key Vault\n- Application references Key Vault URIs\n- No secrets in configuration files\n```\n\n### 5. Database Schema Documentation\n\n**Location**: `docs/database/`\n\n**What to Document**:\n- Table schemas\n- Relationships\n- Indexes\n- Migration history\n\n**Template**:\n```markdown\n# Database Schema\n\n## Magics Table\n\n```sql\nCREATE TABLE Magics (\n MagicId INT PRIMARY KEY IDENTITY(1,1),\n PublicMagicId NVARCHAR(12) UNIQUE NOT NULL,\n Name NVARCHAR(200) NOT NULL,\n Description NVARCHAR(MAX) NULL,\n Category NVARCHAR(50) NOT NULL,\n Power INT NOT NULL CHECK (Power >= 0 AND Power <= 100),\n IsActive BIT NOT NULL DEFAULT 1,\n CreatedAt DATETIME2 NOT NULL DEFAULT GETUTCDATE(),\n UpdatedAt DATETIME2 NULL,\n CONSTRAINT idx_magic_name UNIQUE (Name)\n);\n\nCREATE INDEX idx_magic_category ON Magics(Category);\nCREATE INDEX idx_magic_active ON Magics(IsActive);\nCREATE INDEX idx_magic_public_id ON Magics(PublicMagicId);\n```\n\n## Relationships\n\n- Magics → Categories (FK: Category)\n- Users → Magic (many-to-many through UserMagicFavorites)\n\n## Indexes\n\n| Table | Column | Type | Purpose |\n|-------|--------|------|---------|\n| Magics | PublicMagicId | Unique | Fast public ID lookups |\n| Magics | Category | Standard | Category filtering |\n| Magics | IsActive | Standard | Active status filtering |\n| Magics | Name | Unique | Prevent duplicates |\n```\n\n## Maintaining Documentation\n\n### When to Update\n\nUpdate documentation when:\n- Adding new API endpoints\n- Changing data models\n- Modifying architecture\n- Adding configuration options\n- Updating deployment process\n- Fixing bugs (if documentation-related)\n- Adding features\n\n### Documentation Quality Checklist\n\n- [ ] Accurate and current\n- [ ] Examples are valid and tested\n- [ ] All code examples work\n- [ ] Links are valid and not broken\n- [ ] Consistent formatting\n- [ ] Clear and concise language\n- [ ] Table of contents is current\n- [ ] API docs match actual endpoints\n- [ ] Setup instructions work end-to-end\n- [ ] Architecture diagrams are accurate\n- [ ] Configuration docs complete\n- [ ] Troubleshooting section helpful\n\n## Documentation Tools & Standards\n\n### Markdown Standards\n\n```markdown\n# Main Title (H1)\n\n## Section (H2)\n\n### Subsection (H3)\n\n- Bullet point\n- Another point\n\n1. Numbered list\n2. Second item\n\n**Bold text**\n*Italic text*\n\n`code snippet`\n\n\\`\\`\\`language\ncode block\n\\`\\`\\`\n\n| Header 1 | Header 2 |\n|----------|----------|\n| Value 1 | Value 2 |\n```\n\n### Code Examples\n\nAlways include:\n- What the code does\n- Prerequisites\n- Step-by-step instructions\n- Expected output\n- Common errors\n\n### Diagrams\n\nUse ASCII art or Mermaid:\n\n```mermaid\ngraph TD\n A[Client] -->|HTTP Request| B[Controller]\n B -->|Business Logic| C[Service]\n C -->|Query| D[Repository]\n D -->|SQL| E[Database]\n```\n\n## Automated Documentation Generation\n\n### API Documentation (Swagger/OpenAPI)\n\n```csharp\n// Program.cs\nbuilder.Services.AddSwaggerGen(options =>\n{\n options.SwaggerDoc(\"v1\", new OpenApiInfo\n {\n Title = \"Magic Service API\",\n Version = \"v1\",\n Description = \"Wizardworks Magic Management API\"\n });\n\n var xmlFilename = $\"{Assembly.GetExecutingAssembly().GetName().Name}.xml\";\n options.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, xmlFilename));\n});\n\napp.UseSwagger();\napp.UseSwaggerUI();\n```\n\n### XML Comments for API\n\n```csharp\n/// <summary>\n/// Creates a new magic item\n/// </summary>\n/// <param name=\"dto\">Magic creation data</param>\n/// <returns>Created magic item</returns>\n/// <remarks>\n/// Sample request:\n///\n/// POST /api/magic\n/// {\n/// \"name\": \"Fireball\",\n/// \"description\": \"A fire spell\",\n/// \"category\": \"offensive\",\n/// \"power\": 85\n/// }\n/// </remarks>\n/// <response code=\"201\">Magic item created successfully</response>\n/// <response code=\"400\">Invalid input</response>\n/// <response code=\"401\">Unauthorized</response>\n[HttpPost]\n[ProducesResponseType(StatusCodes.Status201Created)]\n[ProducesResponseType(StatusCodes.Status400BadRequest)]\npublic async Task<IActionResult> Create([FromBody] CreateMagicDto dto)\n{\n var result = await _service.CreateAsync(dto);\n return CreatedAtAction(nameof(Get), new { publicMagicId = result.PublicMagicId }, result);\n}\n```\n\n## Documentation Audit\n\nPeriodically audit documentation:\n\n```bash\n# Check for broken links\nnpm install -g markdown-link-check\nfind docs -name \"*.md\" -exec markdown-link-check {} \\;\n\n# Generate word count\nwc -w docs/**/*.md\n\n# Find outdated references\ngrep -r \"TODO\\|FIXME\\|DEPRECATED\" docs/\n```\n\n## When to Use This Command\n\n- **After implementing new features**\n- **After API changes**\n- **After architecture changes**\n- **During code reviews**\n- **Before releases**\n- **When onboarding new team members**\n- **When documentation audit due**\n- **After fixing bugs that affected docs**\n\n## Related Commands\n\n- Use `/code-review` to identify documentation gaps\n- Use `/plan` when documenting architecture\n- Use `/refactor-clean` when restructuring code\n\n## As a Wizardworks Employee\n\nDocumentation is as important as code. Good documentation:\n- Enables team productivity\n- Reduces onboarding time\n- Prevents bugs\n- Makes systems maintainable\n- Preserves institutional knowledge\n\n**Remember**: If it's not documented, it doesn't exist. Keep docs current.", "variables": [], "notes": "Update documentation to match code changes", "metadata": { "source": { "provider": "github-claude-commands", "repository": "https://github.com/Wizardworks-AB/wizardworks-client-agent-template", "path": ".claude/commands/update-docs.md", "ref": "bb0d642308561d803c4726c214a4dc0d795328bd", "url": "https://github.com/Wizardworks-AB/wizardworks-client-agent-template/blob/bb0d642308561d803c4726c214a4dc0d795328bd/.claude/commands/update-docs.md", "key": "Wizardworks-AB/wizardworks-client-agent-template/.claude/commands/update-docs.md" } } }

update-docs

About

Update Documentation Command

Usage

What This Command Does

Documentation Types

1. API Documentation

DTO (API)

Key Design Decisions

Public ID Pattern

Controller-Service-Repository

Related Documentation

Configure Database

Option 1: SQL Server (Local)

Option 2: PostgreSQL (Docker)

Apply Migrations

Run Locally

Running Tests

Docker Development