From 741017e5fab79a9a73b394133b028d5827fe3b9c Mon Sep 17 00:00:00 2001 From: Aaron Powell Date: Fri, 13 Mar 2026 14:19:27 +1100 Subject: [PATCH] Combining skills into a single skill with an internal decision tree --- docs/README.skills.md | 3 +- .../SKILL.md | 193 ------------------ skills/oo-component-documentation/SKILL.md | 74 +++++++ .../assets/documentation-template.md | 97 +++++++++ .../references/create-mode.md | 32 +++ .../references/update-mode.md | 32 +++ .../SKILL.md | 162 --------------- 7 files changed, 236 insertions(+), 357 deletions(-) delete mode 100644 skills/create-oo-component-documentation/SKILL.md create mode 100644 skills/oo-component-documentation/SKILL.md create mode 100644 skills/oo-component-documentation/assets/documentation-template.md create mode 100644 skills/oo-component-documentation/references/create-mode.md create mode 100644 skills/oo-component-documentation/references/update-mode.md delete mode 100644 skills/update-oo-component-documentation/SKILL.md diff --git a/docs/README.skills.md b/docs/README.skills.md index fa97cb2f..34ed89d3 100644 --- a/docs/README.skills.md +++ b/docs/README.skills.md @@ -79,7 +79,6 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to | [create-github-pull-request-from-specification](../skills/create-github-pull-request-from-specification/SKILL.md) | Create GitHub Pull Request for feature request from specification file using pull_request_template.md template. | None | | [create-implementation-plan](../skills/create-implementation-plan/SKILL.md) | Create a new implementation plan file for new features, refactoring existing code or upgrading packages, design, architecture or infrastructure. | None | | [create-llms](../skills/create-llms/SKILL.md) | Create an llms.txt file from scratch based on repository structure following the llms.txt specification at https://llmstxt.org/ | None | -| [create-oo-component-documentation](../skills/create-oo-component-documentation/SKILL.md) | Create comprehensive, standardized documentation for object-oriented components following industry best practices and architectural documentation standards. | None | | [create-readme](../skills/create-readme/SKILL.md) | Create a README.md file for the project | None | | [create-specification](../skills/create-specification/SKILL.md) | Create a new specification file for the solution, optimized for Generative AI consumption. | None | | [create-spring-boot-java-project](../skills/create-spring-boot-java-project/SKILL.md) | Create Spring Boot Java Project Skeleton | None | @@ -173,6 +172,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to | [next-intl-add-language](../skills/next-intl-add-language/SKILL.md) | Add new language to a Next.js + next-intl application | None | | [noob-mode](../skills/noob-mode/SKILL.md) | Plain-English translation layer for non-technical Copilot CLI users. Translates every approval prompt, error message, and technical output into clear, jargon-free English with color-coded risk indicators. | `references/examples.md`
`references/glossary.md` | | [nuget-manager](../skills/nuget-manager/SKILL.md) | Manage NuGet packages in .NET projects/solutions. Use this skill when adding, removing, or updating NuGet package versions. It enforces using `dotnet` CLI for package management and provides strict procedures for direct file edits only when updating versions. | None | +| [oo-component-documentation](../skills/oo-component-documentation/SKILL.md) | Create or update standardized object-oriented component documentation using a shared template plus mode-specific guidance for new and existing docs. | `assets/documentation-template.md`
`references/create-mode.md`
`references/update-mode.md` | | [openapi-to-application-code](../skills/openapi-to-application-code/SKILL.md) | Generate a complete, production-ready application from an OpenAPI specification | None | | [pdftk-server](../skills/pdftk-server/SKILL.md) | Skill for using the command-line tool pdftk (PDFtk Server) for working with PDF files. Use when asked to merge PDFs, split PDFs, rotate pages, encrypt or decrypt PDFs, fill PDF forms, apply watermarks, stamp overlays, extract metadata, burst documents into pages, repair corrupted PDFs, attach or extract files, or perform any PDF manipulation from the command line. | `references/download.md`
`references/pdftk-cli-examples.md`
`references/pdftk-man-page.md`
`references/pdftk-server-license.md`
`references/third-party-materials.md` | | [penpot-uiux-design](../skills/penpot-uiux-design/SKILL.md) | Comprehensive guide for creating professional UI/UX designs in Penpot using MCP tools. Use this skill when: (1) Creating new UI/UX designs for web, mobile, or desktop applications, (2) Building design systems with components and tokens, (3) Designing dashboards, forms, navigation, or landing pages, (4) Applying accessibility standards and best practices, (5) Following platform guidelines (iOS, Android, Material Design), (6) Reviewing or improving existing Penpot designs for usability. Triggers: "design a UI", "create interface", "build layout", "design dashboard", "create form", "design landing page", "make it accessible", "design system", "component library". | `references/accessibility.md`
`references/component-patterns.md`
`references/platform-guidelines.md`
`references/setup-troubleshooting.md` | @@ -235,7 +235,6 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to | [update-implementation-plan](../skills/update-implementation-plan/SKILL.md) | Update an existing implementation plan file with new or update requirements to provide new features, refactoring existing code or upgrading packages, design, architecture or infrastructure. | None | | [update-llms](../skills/update-llms/SKILL.md) | Update the llms.txt file in the root folder to reflect changes in documentation or specifications following the llms.txt specification at https://llmstxt.org/ | None | | [update-markdown-file-index](../skills/update-markdown-file-index/SKILL.md) | Update a markdown file section with an index/table of files from a specified folder. | None | -| [update-oo-component-documentation](../skills/update-oo-component-documentation/SKILL.md) | Update existing object-oriented component documentation following industry best practices and architectural documentation standards. | None | | [update-specification](../skills/update-specification/SKILL.md) | Update an existing specification file for the solution, optimized for Generative AI consumption based on new requirements or updates to any existing code. | None | | [vscode-ext-commands](../skills/vscode-ext-commands/SKILL.md) | Guidelines for contributing commands in VS Code extensions. Indicates naming convention, visibility, localization and other relevant attributes, following VS Code extension development guidelines, libraries and good practices | None | | [vscode-ext-localization](../skills/vscode-ext-localization/SKILL.md) | Guidelines for proper localization of VS Code extensions, following VS Code extension development guidelines, libraries and good practices | None | diff --git a/skills/create-oo-component-documentation/SKILL.md b/skills/create-oo-component-documentation/SKILL.md deleted file mode 100644 index 03432598..00000000 --- a/skills/create-oo-component-documentation/SKILL.md +++ /dev/null @@ -1,193 +0,0 @@ ---- -name: create-oo-component-documentation -description: 'Create comprehensive, standardized documentation for object-oriented components following industry best practices and architectural documentation standards.' ---- - -# Generate Standard OO Component Documentation - -Create comprehensive documentation for the object-oriented component(s) at: `${input:ComponentPath}`. - -Analyze the component by examining code in the provided path. If folder, analyze all source files. If single file, treat as main component and analyze related files in same directory. - -## Documentation Standards - -- DOC-001: Follow C4 Model documentation levels (Context, Containers, Components, Code) -- DOC-002: Align with Arc42 software architecture documentation template -- DOC-003: Comply with IEEE 1016 Software Design Description standard -- DOC-004: Use Agile Documentation principles (just enough documentation that adds value) -- DOC-005: Target developers and maintainers as primary audience - -## Analysis Instructions - -- ANA-001: Determine path type (folder vs single file) and identify primary component -- ANA-002: Examine source code files for class structures and inheritance -- ANA-003: Identify design patterns and architectural decisions -- ANA-004: Document public APIs, interfaces, and dependencies -- ANA-005: Recognize creational/structural/behavioral patterns -- ANA-006: Document method parameters, return values, exceptions -- ANA-007: Assess performance, security, reliability, maintainability -- ANA-008: Infer integration patterns and data flow - -## Language-Specific Optimizations - -- LNG-001: **C#/.NET** - async/await, dependency injection, configuration, disposal -- LNG-002: **Java** - Spring framework, annotations, exception handling, packaging -- LNG-003: **TypeScript/JavaScript** - modules, async patterns, types, npm -- LNG-004: **Python** - packages, virtual environments, type hints, testing - -## Error Handling - -- ERR-001: Path doesn't exist - provide correct format guidance -- ERR-002: No source files found - suggest alternative locations -- ERR-003: Unclear structure - document findings and request clarification -- ERR-004: Non-standard patterns - document custom approaches -- ERR-005: Insufficient code - focus on available information, highlight gaps - -## Output Format - -Generate well-structured Markdown with clear heading hierarchy, code blocks, tables, bullet points, and proper formatting for readability and maintainability. - -## File Location - -The documentation should be saved in the `/docs/components/` directory and named according to the convention: `[component-name]-documentation.md`. - -## Required Documentation Structure - -The documentation file must follow the template below, ensuring that all sections are filled out appropriately. The front matter for the markdown should be structured correctly as per the example following: - -```md ---- -title: [Component Name] - Technical Documentation -component_path: `${input:ComponentPath}` -version: [Optional: e.g., 1.0, Date] -date_created: [YYYY-MM-DD] -last_updated: [Optional: YYYY-MM-DD] -owner: [Optional: Team/Individual responsible for this component] -tags: [Optional: List of relevant tags or categories, e.g., `component`,`service`,`tool`,`infrastructure`,`documentation`,`architecture` etc] ---- - -# [Component Name] Documentation - -[A short concise introduction to the component and its purpose within the system.] - -## 1. Component Overview - -### Purpose/Responsibility -- OVR-001: State component's primary responsibility -- OVR-002: Define scope (included/excluded functionality) -- OVR-003: Describe system context and relationships - -## 2. Architecture Section - -- ARC-001: Document design patterns used (Repository, Factory, Observer, etc.) -- ARC-002: List internal and external dependencies with purposes -- ARC-003: Document component interactions and relationships -- ARC-004: Include visual diagrams (UML class, sequence, component) -- ARC-005: Create mermaid diagram showing component structure, relationships, and dependencies - -### Component Structure and Dependencies Diagram - -Include a comprehensive mermaid diagram that shows: -- **Component structure** - Main classes, interfaces, and their relationships -- **Internal dependencies** - How components interact within the system -- **External dependencies** - External libraries, services, databases, APIs -- **Data flow** - Direction of dependencies and interactions -- **Inheritance/composition** - Class hierarchies and composition relationships - -```mermaid -graph TD - subgraph "Component System" - A[Main Component] --> B[Internal Service] - A --> C[Internal Repository] - B --> D[Business Logic] - C --> E[Data Access Layer] - end - - subgraph "External Dependencies" - F[External API] - G[Database] - H[Third-party Library] - I[Configuration Service] - end - - A --> F - E --> G - B --> H - A --> I - - classDiagram - class MainComponent { - +property: Type - +method(): ReturnType - +asyncMethod(): Promise~Type~ - } - class InternalService { - +businessOperation(): Result - } - class ExternalAPI { - <> - +apiCall(): Data - } - - MainComponent --> InternalService - MainComponent --> ExternalAPI -``` - -## 3. Interface Documentation - -- INT-001: Document all public interfaces and usage patterns -- INT-002: Create method/property reference table -- INT-003: Document events/callbacks/notification mechanisms - -| Method/Property | Purpose | Parameters | Return Type | Usage Notes | -|-----------------|---------|------------|-------------|-------------| -| [Name] | [Purpose] | [Parameters] | [Type] | [Notes] | - -## 4. Implementation Details - -- IMP-001: Document main implementation classes and responsibilities -- IMP-002: Describe configuration requirements and initialization -- IMP-003: Document key algorithms and business logic -- IMP-004: Note performance characteristics and bottlenecks - -## 5. Usage Examples - -### Basic Usage - -```csharp -// Basic usage example -var component = new ComponentName(); -component.DoSomething(); -``` - -### Advanced Usage - -```csharp -// Advanced configuration patterns -var options = new ComponentOptions(); -var component = ComponentFactory.Create(options); -await component.ProcessAsync(data); -``` - -- USE-001: Provide basic usage examples -- USE-002: Show advanced configuration patterns -- USE-003: Document best practices and recommended patterns - -## 6. Quality Attributes - -- QUA-001: Security (authentication, authorization, data protection) -- QUA-002: Performance (characteristics, scalability, resource usage) -- QUA-003: Reliability (error handling, fault tolerance, recovery) -- QUA-004: Maintainability (standards, testing, documentation) -- QUA-005: Extensibility (extension points, customization options) - -## 7. Reference Information - -- REF-001: List dependencies with versions and purposes -- REF-002: Complete configuration options reference -- REF-003: Testing guidelines and mock setup -- REF-004: Troubleshooting (common issues, error messages) -- REF-005: Related documentation links -- REF-006: Change history and migration notes - -``` diff --git a/skills/oo-component-documentation/SKILL.md b/skills/oo-component-documentation/SKILL.md new file mode 100644 index 00000000..7994b07c --- /dev/null +++ b/skills/oo-component-documentation/SKILL.md @@ -0,0 +1,74 @@ +--- +name: oo-component-documentation +description: 'Create or update standardized object-oriented component documentation using a shared template plus mode-specific guidance for new and existing docs.' +--- + +# OO Component Documentation + +Create new documentation for an object-oriented component or update an existing component documentation file by analyzing the current implementation. + +## Determine the mode first + +Choose the workflow before writing anything: + +1. Use **update mode** when the user provides an existing documentation Markdown file, points to a docs path, or explicitly asks to refresh or revise existing documentation. Follow [references/update-mode.md](references/update-mode.md). +2. Use **create mode** when the user provides a source file or folder, points to a component path, or asks to generate documentation from code. Follow [references/create-mode.md](references/create-mode.md). +3. If both code and an existing documentation file are provided, treat the existing documentation file as the output target and use the current source code as the source of truth. +4. If the request is ambiguous, infer the mode from the path type whenever possible: existing Markdown documentation file means update mode; source/component path means create mode. + +## Documentation standards + +- DOC-001: Follow C4 Model documentation levels (Context, Containers, Components, Code) +- DOC-002: Align with Arc42 software architecture documentation template +- DOC-003: Comply with IEEE 1016 Software Design Description standard +- DOC-004: Use Agile Documentation principles (just enough documentation that adds value) +- DOC-005: Target developers and maintainers as the primary audience + +## Shared analysis guidance + +- ANA-001: Determine the primary component boundary and whether the input represents a folder, file, or existing documentation target +- ANA-002: Examine source code files for class structures, inheritance, composition, and interfaces +- ANA-003: Identify design patterns, architectural decisions, and integration points +- ANA-004: Document or refresh public APIs, interfaces, dependencies, and usage patterns +- ANA-005: Capture method parameters, return values, asynchronous behavior, exceptions, and lifecycle concerns +- ANA-006: Assess performance, security, reliability, maintainability, and extensibility characteristics +- ANA-007: Infer data flow, collaboration patterns, and relationships with surrounding components +- ANA-008: Keep the documentation grounded in the implementation; avoid inventing behavior that is not supported by the code + +## Shared output requirements + +- Use [assets/documentation-template.md](assets/documentation-template.md) as the canonical section checklist and baseline structure. +- Keep the output in Markdown with a clear heading hierarchy, tables where useful, code blocks for examples, and Mermaid diagrams when architecture relationships need to be visualized. +- Make examples and interface descriptions match the current implementation instead of generic placeholders. +- Include only information that can be supported by the code, project structure, configuration, or clearly stated assumptions. +- When source coverage is incomplete, document the limitation explicitly instead of guessing. + +## Language-specific optimizations + +- LNG-001: **C#/.NET** - async/await, dependency injection, configuration, disposal, options patterns +- LNG-002: **Java** - Spring framework, annotations, exception handling, packaging, dependency injection +- LNG-003: **TypeScript/JavaScript** - modules, async patterns, types, npm dependencies, runtime boundaries +- LNG-004: **Python** - packages, virtual environments, type hints, testing, dependency management + +## Error handling + +- ERR-001: If the path does not exist, explain what path was expected and whether the skill needs a source path or an existing documentation file +- ERR-002: If no relevant source files are found, document the gap and suggest the likely locations to inspect next +- ERR-003: If the documentation target cannot be inferred from the request, state the ambiguity and ask for the missing path only when inference is not possible +- ERR-004: If the code uses non-standard architectural patterns, document the custom approach rather than forcing it into a generic pattern +- ERR-005: If source access is incomplete, continue with available evidence and clearly call out any unsupported sections + +## Workflow + +1. Determine whether the task is create mode or update mode. +2. Inspect the component implementation and any related files needed to understand its public surface area and internal structure. +3. Use [assets/documentation-template.md](assets/documentation-template.md) as the shared documentation scaffold. +4. Apply the mode-specific rules in [references/create-mode.md](references/create-mode.md) or [references/update-mode.md](references/update-mode.md). +5. Produce or revise the documentation so that diagrams, examples, interfaces, dependencies, and quality attributes reflect the current implementation. + +## Completion criteria + +- The documentation clearly identifies the component purpose, architecture, interfaces, implementation details, usage patterns, quality attributes, and references. +- Front matter fields are accurate for the selected mode. +- Examples and diagrams match the implementation. +- Any unknowns, gaps, or assumptions are explicitly called out. diff --git a/skills/oo-component-documentation/assets/documentation-template.md b/skills/oo-component-documentation/assets/documentation-template.md new file mode 100644 index 00000000..fb0038f4 --- /dev/null +++ b/skills/oo-component-documentation/assets/documentation-template.md @@ -0,0 +1,97 @@ +--- +title: [Component Name] - Technical Documentation +component_path: [Source component path] +version: [Optional version] +date_created: [YYYY-MM-DD] +last_updated: [Optional YYYY-MM-DD] +owner: [Optional team or individual] +tags: [Optional list of relevant tags] +--- + +# [Component Name] Documentation + +[Concise introduction describing the component purpose and role in the system.] + +## 1. Component Overview + +### Purpose/Responsibility + +- OVR-001: State the component's primary responsibility +- OVR-002: Define scope, including included and excluded responsibilities +- OVR-003: Describe system context and major relationships + +## 2. Architecture Section + +- ARC-001: Document design patterns used +- ARC-002: List internal and external dependencies with their purpose +- ARC-003: Describe component interactions and relationships +- ARC-004: Include visual diagrams where they clarify structure or behavior +- ARC-005: Provide a Mermaid diagram showing structure, relationships, and dependencies + +### Component Structure and Dependencies Diagram + +Show the current: + +- Component structure +- Internal dependencies +- External dependencies +- Data flow +- Inheritance and composition relationships + +```mermaid +graph TD + A[Primary Component] --> B[Collaborator] + A --> C[Dependency] +``` + +## 3. Interface Documentation + +- INT-001: Document public interfaces and usage patterns +- INT-002: Provide a method or property reference table +- INT-003: Cover events, callbacks, or notification mechanisms when applicable + +| Method/Property | Purpose | Parameters | Return Type | Usage Notes | +|-----------------|---------|------------|-------------|-------------| +| [Name] | [Purpose] | [Parameters] | [Type] | [Notes] | + +## 4. Implementation Details + +- IMP-001: Describe main implementation classes and responsibilities +- IMP-002: Capture configuration requirements and initialization patterns +- IMP-003: Summarize key algorithms or business logic +- IMP-004: Note performance characteristics and bottlenecks + +## 5. Usage Examples + +### Basic Usage + +```text +[Basic usage example aligned with the component language and API] +``` + +### Advanced Usage + +```text +[Advanced configuration or orchestration example aligned with the current implementation] +``` + +- USE-001: Provide basic usage examples +- USE-002: Show advanced configuration patterns +- USE-003: Document best practices and recommended patterns + +## 6. Quality Attributes + +- QUA-001: Security +- QUA-002: Performance +- QUA-003: Reliability +- QUA-004: Maintainability +- QUA-005: Extensibility + +## 7. Reference Information + +- REF-001: List dependencies with versions and purposes where available +- REF-002: Document configuration options +- REF-003: Provide testing guidance and mock setup notes +- REF-004: Capture troubleshooting notes and common issues +- REF-005: Link related documentation +- REF-006: Add change history or migration notes when relevant diff --git a/skills/oo-component-documentation/references/create-mode.md b/skills/oo-component-documentation/references/create-mode.md new file mode 100644 index 00000000..fa917b30 --- /dev/null +++ b/skills/oo-component-documentation/references/create-mode.md @@ -0,0 +1,32 @@ +# Create mode + +Use this workflow when the input is a component source path or the user asks to generate new documentation from code. + +## Input handling + +- Accept a single file or a folder path representing the component. +- If the input is a folder, analyze the relevant source files in that folder and nearby supporting files. +- If the input is a single file, treat it as the primary component entry point and inspect adjacent files as needed to understand collaborators and interfaces. + +## Create-specific requirements + +- Save the new documentation in `/docs/components/`. +- Name the file `[component-name]-documentation.md`. +- Set `component_path` to the source path provided by the user. +- Set `date_created` to the current date. +- Set `last_updated` only if the repository convention for the target area expects it at creation time. +- Populate optional metadata such as `version`, `owner`, and `tags` only when they can be inferred reliably. + +## Create-specific analysis focus + +- Determine the primary component name and responsibilities from the code structure. +- Identify the initial system context, scope boundaries, dependencies, design patterns, and collaboration model. +- Build interface tables and usage examples from the actual public surface area. +- Create a Mermaid diagram that introduces the component structure, dependencies, and data flow for a reader seeing the documentation for the first time. + +## Create-specific output guidance + +- Use the full section structure from `../assets/documentation-template.md`. +- Write the introduction as a fresh overview of what the component does and why it exists. +- Prefer complete sections over placeholders; if information is unavailable, mark the section with a short limitation note instead of leaving template text behind. +- Include change history or migration notes only if there is evidence of prior versions or migration concerns in the code or repository history. diff --git a/skills/oo-component-documentation/references/update-mode.md b/skills/oo-component-documentation/references/update-mode.md new file mode 100644 index 00000000..a87287fa --- /dev/null +++ b/skills/oo-component-documentation/references/update-mode.md @@ -0,0 +1,32 @@ +# Update mode + +Use this workflow when the input is an existing documentation Markdown file or the user asks to refresh existing component documentation. + +## Input handling + +- Read the existing documentation first to understand the current structure, terminology, and any front matter metadata. +- Extract the component source path from the `component_path` front matter when present. +- If `component_path` is missing, infer the component path from the documentation content and surrounding repository structure. +- Use the current implementation as the source of truth when the documentation and code disagree. + +## Update-specific requirements + +- Preserve the existing documentation file as the output target. +- Preserve `date_created`. +- Update `last_updated` to the current date. +- Preserve version history and ownership metadata when still accurate; refresh them only when the code or repository evidence indicates they have changed. +- Maintain the existing organization where it is still useful, but ensure the content remains consistent with the shared template expectations. + +## Update-specific analysis focus + +- Compare the existing documentation with the current code to identify stale APIs, outdated diagrams, renamed dependencies, and changed usage patterns. +- Highlight breaking changes, deprecated features, or major architectural shifts when they are evident. +- Refresh method tables, examples, diagrams, dependency lists, and quality attribute notes to match the implementation as it exists today. +- Add missing sections only when the component has grown or the current documentation omits information now needed for maintainers. + +## Update-specific output guidance + +- Keep useful editorial choices from the existing document, but remove stale or misleading content. +- Update examples so they compile conceptually against the current API shape. +- Refresh Mermaid diagrams rather than replacing them with generic placeholders. +- Add migration notes or change history when the update reveals important compatibility or behavior changes. diff --git a/skills/update-oo-component-documentation/SKILL.md b/skills/update-oo-component-documentation/SKILL.md deleted file mode 100644 index 446967b4..00000000 --- a/skills/update-oo-component-documentation/SKILL.md +++ /dev/null @@ -1,162 +0,0 @@ ---- -name: update-oo-component-documentation -description: 'Update existing object-oriented component documentation following industry best practices and architectural documentation standards.' ---- - -# Update Standard OO Component Documentation - -Update the existing documentation file at: `${file}` by analyzing the corresponding component code. - -Extract the component path from the existing documentation's front matter (`component_path` field) or infer it from the documentation content. Analyze the current component implementation and update the documentation accordingly. - -**Documentation Standards:** - -- DOC-001: Follow C4 Model documentation levels (Context, Containers, Components, Code) -- DOC-002: Align with Arc42 software architecture documentation template -- DOC-003: Comply with IEEE 1016 Software Design Description standard -- DOC-004: Use Agile Documentation principles (just enough documentation that adds value) -- DOC-005: Target developers and maintainers as primary audience - -**Analysis Instructions:** - -- ANA-001: Read existing documentation to understand component context and structure -- ANA-002: Identify component path from front matter or content analysis -- ANA-003: Examine current source code files for class structures and inheritance -- ANA-004: Compare existing documentation with current implementation -- ANA-005: Identify design patterns and architectural changes -- ANA-006: Update public APIs, interfaces, and dependencies -- ANA-007: Recognize new/changed creational/structural/behavioral patterns -- ANA-008: Update method parameters, return values, exceptions -- ANA-009: Reassess performance, security, reliability, maintainability -- ANA-010: Update integration patterns and data flow - -**Language-Specific Optimizations:** - -- LNG-001: **C#/.NET** - async/await, dependency injection, configuration, disposal -- LNG-002: **Java** - Spring framework, annotations, exception handling, packaging -- LNG-003: **TypeScript/JavaScript** - modules, async patterns, types, npm -- LNG-004: **Python** - packages, virtual environments, type hints, testing - -**Update Strategy:** - -- UPD-001: Preserve existing documentation structure and format -- UPD-002: Update `last_updated` field to current date -- UPD-003: Maintain version history in front matter if present -- UPD-004: Add new sections if component has significantly expanded -- UPD-005: Mark deprecated features or breaking changes -- UPD-006: Update examples to reflect current API -- UPD-007: Refresh dependency lists and versions -- UPD-008: Update mermaid diagrams to reflect current architecture - -**Error Handling:** - -- ERR-001: Documentation file doesn't exist - provide guidance on file location -- ERR-002: Component path not found in documentation - request clarification -- ERR-003: Source code has moved - suggest updated paths -- ERR-004: Major architectural changes - highlight breaking changes -- ERR-005: Insufficient access to source - document limitations - -**Output Format:** - -Update the existing Markdown file maintaining its structure while refreshing content to match current implementation. Preserve formatting, heading hierarchy, and existing organizational decisions. - -**Required Documentation Structure:** - -Update the existing documentation following the same template structure, ensuring all sections reflect current implementation: - -```md ---- -title: [Component Name] - Technical Documentation -component_path: [Current component path] -version: [Updated version if applicable] -date_created: [Original creation date - preserve] -last_updated: [YYYY-MM-DD - update to current date] -owner: [Preserve existing or update if changed] -tags: [Update tags as needed based on current functionality] ---- - -# [Component Name] Documentation - -[Update introduction to reflect current component purpose and capabilities] - -## 1. Component Overview - -### Purpose/Responsibility -- OVR-001: Update component's primary responsibility -- OVR-002: Refresh scope (included/excluded functionality) -- OVR-003: Update system context and relationships - -## 2. Architecture Section - -- ARC-001: Update design patterns used (Repository, Factory, Observer, etc.) -- ARC-002: Refresh internal and external dependencies with current purposes -- ARC-003: Update component interactions and relationships -- ARC-004: Update visual diagrams (UML class, sequence, component) -- ARC-005: Refresh mermaid diagram showing current component structure, relationships, and dependencies - -### Component Structure and Dependencies Diagram - -Update the mermaid diagram to show current: -- **Component structure** - Current classes, interfaces, and their relationships -- **Internal dependencies** - How components currently interact within the system -- **External dependencies** - Current external libraries, services, databases, APIs -- **Data flow** - Current direction of dependencies and interactions -- **Inheritance/composition** - Current class hierarchies and composition relationships - -```mermaid -[Update diagram to reflect current architecture] -``` - -## 3. Interface Documentation - -- INT-001: Update all public interfaces and current usage patterns -- INT-002: Refresh method/property reference table with current API -- INT-003: Update events/callbacks/notification mechanisms - -| Method/Property | Purpose | Parameters | Return Type | Usage Notes | -|-----------------|---------|------------|-------------|-------------| -| [Update table with current API] | | | | | - -## 4. Implementation Details - -- IMP-001: Update main implementation classes and current responsibilities -- IMP-002: Refresh configuration requirements and initialization patterns -- IMP-003: Update key algorithms and business logic -- IMP-004: Update performance characteristics and bottlenecks - -## 5. Usage Examples - -### Basic Usage - -```csharp -// Update basic usage example to current API -``` - -### Advanced Usage - -```csharp -// Update advanced configuration patterns to current implementation -``` - -- USE-001: Update basic usage examples -- USE-002: Refresh advanced configuration patterns -- USE-003: Update best practices and recommended patterns - -## 6. Quality Attributes - -- QUA-001: Update security (authentication, authorization, data protection) -- QUA-002: Refresh performance (characteristics, scalability, resource usage) -- QUA-003: Update reliability (error handling, fault tolerance, recovery) -- QUA-004: Refresh maintainability (standards, testing, documentation) -- QUA-005: Update extensibility (extension points, customization options) - -## 7. Reference Information - -- REF-001: Update dependencies with current versions and purposes -- REF-002: Refresh configuration options reference -- REF-003: Update testing guidelines and mock setup -- REF-004: Refresh troubleshooting (common issues, error messages) -- REF-005: Update related documentation links -- REF-006: Add change history and migration notes for this update - -```