[IMPORTANT] Use TaskCreate to break ALL work into small tasks BEFORE starting — including tasks for each file read. This prevents context loss from long files. For simple tasks, AI MUST ask user whether to skip.

Prerequisites: MUST READ .claude/skills/shared/evidence-based-reasoning-protocol.md before executing.

Quick Summary

Goal: Autonomous documentation generation with structured templates for code comments, API docs, and architecture docs (subagent variant of documentation ).

Workflow:

• Identify Type — Code comments, API documentation, or architecture documentation

• Apply Pattern — C# XML docs, TypeScript JSDoc, API endpoint docs, README structure, or inline comments

• Follow Guidelines — Document "why" not "what", include examples, keep close to code, update with changes

Key Rules:

• Autonomous: Use for documentation tasks without user feedback loop

• DO: Document public APIs, explain "why", include usage examples, keep docs close to code

• DON'T: State obvious, leave TODOs indefinitely, duplicate code in docs, create separate stale docs

• Comment Types: <summary> for public APIs, // for complex logic, TODO /FIXME /HACK /NOTE markers

Be skeptical. Apply critical thinking, sequential thinking. Every claim needs traced proof.

Skill Variant: Use this skill for autonomous documentation generation with structured templates. For interactive documentation tasks with user feedback, use documentation instead.

Documentation Workflow

When to Use This Skill

• Creating API documentation

• Writing code comments

• Updating README files

• Generating architecture documentation

Documentation Types

1. Code Comments

• XML docs for public APIs

• Inline comments for complex logic

• TODO/FIXME for technical debt

2. API Documentation

• Endpoint descriptions

• Request/response schemas

• Error codes and handling

3. Architecture Documentation

• Component diagrams

• Data flow documentation

• Integration guides

Pattern 1: C# XML Documentation

/// <summary> /// Saves or updates an employee entity. /// </summary> /// <remarks> /// This command handles both create and update operations. /// For new employees, the Id should be null or empty. /// </remarks> /// <example> /// <code> /// var command = new SaveEmployeeCommand /// { /// Name = "John Doe", /// Email = "john@example.com" /// }; /// var result = await handler.HandleAsync(command, cancellationToken); /// </code> /// </example> public sealed class SaveEmployeeCommand : CqrsCommand<SaveEmployeeCommandResult> // project CQRS command base { /// <summary> /// The unique identifier of the employee. /// Null or empty for new employees. /// </summary> public string? Id { get; set; }

/// <summary>
/// The employee's full name.
/// </summary>
/// <value>Must be non-empty and max 200 characters.</value>
public string Name { get; set; } = string.Empty;

}

/// <summary> /// Represents a unique expression for finding an employee. /// </summary> /// <param name="companyId">The company identifier.</param> /// <param name="userId">The user identifier.</param> /// <returns>An expression that matches the unique employee.</returns> public static Expression<Func<Employee, bool>> UniqueExpr(string companyId, string userId) => e => e.CompanyId == companyId && e.UserId == userId;

Pattern 2: TypeScript JSDoc

/**

• Manages the feature list state and operations.
• @example
• @Component({
• providers: [FeatureListStore]
• })
• export class FeatureListComponent {
• constructor(private store: FeatureListStore) {

• store.loadItems();
  

• }
• }

/ @Injectable() export class FeatureListStore extends BaseVmStore<FeatureListState> { /*

• Loads items from the API with current filters.
• @remarks
• This effect automatically tracks loading state under the key 'loadItems'.
• Use isLoading$('loadItems') to check loading status.
• @see {@link FeatureApiService.getList} / public loadItems = this.effectSimple(() => / ... */);

/**

• Updates the filter criteria and resets to first page.
• @param filters - Partial filter object to merge with current filters
• @example
• // Filter by status
• store.setFilters({ status: FeatureStatus.Active });
• // Filter by search text
• store.setFilters({ searchText: 'keyword' });

*/ public setFilters(filters: Partial<FeatureFilters>): void { // ... } }

/**

• Represents a feature entity from the API. / export interface FeatureDto { /* Unique identifier */ id: string;

/** Display name of the feature */ name: string;

/**

• Current status of the feature.
• @default FeatureStatus.Draft */ status: FeatureStatus; }

Pattern 3: API Endpoint Documentation

/// <summary> /// Employee management endpoints. /// </summary> [ApiController] [Route("api/[controller]")] [Authorize] // project authorization attribute (see docs/backend-patterns-reference.md) public class EmployeeController : BaseController // project controller base { /// <summary> /// Retrieves a paginated list of employees. /// </summary> /// <param name="query">Query parameters for filtering and pagination.</param> /// <returns>Paginated list of employees.</returns> /// <response code="200">Returns the employee list.</response> /// <response code="400">Invalid query parameters.</response> /// <response code="401">Unauthorized - authentication required.</response> /// <response code="403">Forbidden - insufficient permissions.</response> [HttpGet] [ProducesResponseType(typeof(GetEmployeeListQueryResult), StatusCodes.Status200OK)] [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status400BadRequest)] public async Task<IActionResult> GetList([FromQuery] GetEmployeeListQuery query) => Ok(await Cqrs.SendAsync(query));

/// <summary>
/// Creates or updates an employee.
/// </summary>
/// <param name="command">Employee data to save.</param>
/// <returns>The saved employee.</returns>
/// <response code="200">Employee saved successfully.</response>
/// <response code="400">Validation failed.</response>
/// <response code="404">Employee not found (for updates).</response>
[HttpPost]
[ProducesResponseType(typeof(SaveEmployeeCommandResult), StatusCodes.Status200OK)]
[ProducesResponseType(typeof(ValidationProblemDetails), StatusCodes.Status400BadRequest)]
[ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
public async Task<IActionResult> Save([FromBody] SaveEmployeeCommand command)
    => Ok(await Cqrs.SendAsync(command));

}

Pattern 4: README Documentation

Feature Name

Brief description of what this feature does.

Overview

More detailed explanation of the feature's purpose and functionality.

Architecture

┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐ │ Frontend │────▶│ API Layer │────▶│ Domain Layer │ │ Component │ │ Controller │ │ Entity │ └─────────────────┘ └──────────────────┘ └─────────────────┘

Usage

Backend

// Example usage
var command = new SaveFeatureCommand { Name = "Example" };
var result = await handler.HandleAsync(command, cancellationToken);

Frontend

// Example usage
this.store.loadItems();

Configuration

Setting
Description
Default

MaxItems

Maximum items per page
50

CacheTimeout

Cache duration in seconds
300

API Endpoints

Method
Endpoint
Description

GET
/api/feature

List features

POST
/api/feature

Create/update feature

DELETE
/api/feature/{id}

Delete feature

Error Handling

Code
Description

400
Invalid request data

404
Feature not found

409
Conflict (duplicate)

Related

- Entity Documentation

- API Reference

## Pattern 5: Inline Code Comments

```csharp
protected override async Task<SaveEmployeeCommandResult> HandleAsync(
    SaveEmployeeCommand request, CancellationToken cancellationToken)
{
    // Step 1: Determine if this is a create or update operation
    var isCreate = request.Id.IsNullOrEmpty();

    // Step 2: Get or create the entity
    var employee = isCreate
        ? request.MapToNewEntity()
            .With(e => e.CreatedBy = RequestContext.UserId())
        : await repository.GetByIdAsync(request.Id, cancellationToken)
            .EnsureFound($"Employee not found: {request.Id}")
            .Then(existing => request.UpdateEntity(existing));

    // Step 3: Validate business rules
    // NOTE: This checks for duplicate codes within the same company
    await employee.ValidateAsync(repository, cancellationToken).EnsureValidAsync();

    // Step 4: Persist changes
    // The repository automatically raises entity events for cross-service sync
    var saved = await repository.CreateOrUpdateAsync(employee, cancellationToken);

    // Step 5: Return result
    return new SaveEmployeeCommandResult
    {
        Employee = new EmployeeDto(saved)
    };
}

Documentation Guidelines

DO

- Document public APIs with XML/JSDoc

- Explain "why" not "what"

- Include usage examples

- Keep documentation close to code

- Update docs when code changes

DON'T

- State the obvious

- Leave TODO comments indefinitely

- Write documentation that duplicates code

- Create separate docs that become stale

Comment Types

Type
When to Use

/// <summary>

Public API documentation

// Explanation

Complex logic explanation

// TODO:

Planned improvements

// FIXME:

Known issues

// HACK:

Temporary workarounds

// NOTE:

Important information

Verification Checklist

-  Public APIs have XML/JSDoc documentation

-  Complex logic has explanatory comments

-  Examples are provided where helpful

-  Documentation is accurate and up-to-date

-  No obvious/redundant comments

-  TODO/FIXME items are actionable

IMPORTANT Task Planning Notes (MUST FOLLOW)

- Always plan and break work into many small todo tasks

- Always add a final review todo task to verify work quality and identify fixes/enhancements