shmakk 1.1.0 → 1.2.0

package/skills/dev-csharp-nunit.md

@@ -0,0 +1,72 @@
+---
+name: csharp-nunit
+description: 'Get best practices for NUnit unit testing, including data-driven tests'
+category: dev
+---
+
+# NUnit Best Practices
+
+Your goal is to help me write effective unit tests with NUnit, covering both standard and data-driven testing approaches.
+
+## Project Setup
+
+- Use a separate test project with naming convention `[ProjectName].Tests`
+- Reference Microsoft.NET.Test.Sdk, NUnit, and NUnit3TestAdapter packages
+- Create test classes that match the classes being tested (e.g., `CalculatorTests` for `Calculator`)
+- Use .NET SDK test commands: `dotnet test` for running tests
+
+## Test Structure
+
+- Apply `[TestFixture]` attribute to test classes
+- Use `[Test]` attribute for test methods
+- Follow the Arrange-Act-Assert (AAA) pattern
+- Name tests using the pattern `MethodName_Scenario_ExpectedBehavior`
+- Use `[SetUp]` and `[TearDown]` for per-test setup and teardown
+- Use `[OneTimeSetUp]` and `[OneTimeTearDown]` for per-class setup and teardown
+- Use `[SetUpFixture]` for assembly-level setup and teardown
+
+## Standard Tests
+
+- Keep tests focused on a single behavior
+- Avoid testing multiple behaviors in one test method
+- Use clear assertions that express intent
+- Include only the assertions needed to verify the test case
+- Make tests independent and idempotent (can run in any order)
+- Avoid test interdependencies
+
+## Data-Driven Tests
+
+- Use `[TestCase]` for inline test data
+- Use `[TestCaseSource]` for programmatically generated test data
+- Use `[Values]` for simple parameter combinations
+- Use `[ValueSource]` for property or method-based data sources
+- Use `[Random]` for random numeric test values
+- Use `[Range]` for sequential numeric test values
+- Use `[Combinatorial]` or `[Pairwise]` for combining multiple parameters
+
+## Assertions
+
+- Use `Assert.That` with constraint model (preferred NUnit style)
+- Use constraints like `Is.EqualTo`, `Is.SameAs`, `Contains.Item`
+- Use `Assert.AreEqual` for simple value equality (classic style)
+- Use `CollectionAssert` for collection comparisons
+- Use `StringAssert` for string-specific assertions
+- Use `Assert.Throws<T>` or `Assert.ThrowsAsync<T>` to test exceptions
+- Use descriptive messages in assertions for clarity on failure
+
+## Mocking and Isolation
+
+- Consider using Moq or NSubstitute alongside NUnit
+- Mock dependencies to isolate units under test
+- Use interfaces to facilitate mocking
+- Consider using a DI container for complex test setups
+
+## Test Organization
+
+- Group tests by feature or component
+- Use categories with `[Category("CategoryName")]`
+- Use `[Order]` to control test execution order when necessary
+- Use `[Author("DeveloperName")]` to indicate ownership
+- Use `[Description]` to provide additional test information
+- Consider `[Explicit]` for tests that shouldn't run automatically
+- Use `[Ignore("Reason")]` to temporarily skip tests

package/skills/dev-csharp-tunit.md

@@ -0,0 +1,101 @@
+---
+name: csharp-tunit
+description: 'Get best practices for TUnit unit testing, including data-driven tests'
+category: dev
+---
+
+# TUnit Best Practices
+
+Your goal is to help me write effective unit tests with TUnit, covering both standard and data-driven testing approaches.
+
+## Project Setup
+
+- Use a separate test project with naming convention `[ProjectName].Tests`
+- Reference TUnit package and TUnit.Assertions for fluent assertions
+- Create test classes that match the classes being tested (e.g., `CalculatorTests` for `Calculator`)
+- Use .NET SDK test commands: `dotnet test` for running tests
+- TUnit requires .NET 8.0 or higher
+
+## Test Structure
+
+- No test class attributes required (like xUnit/NUnit)
+- Use `[Test]` attribute for test methods (not `[Fact]` like xUnit)
+- Follow the Arrange-Act-Assert (AAA) pattern
+- Name tests using the pattern `MethodName_Scenario_ExpectedBehavior`
+- Use lifecycle hooks: `[Before(Test)]` for setup and `[After(Test)]` for teardown
+- Use `[Before(Class)]` and `[After(Class)]` for shared context between tests in a class
+- Use `[Before(Assembly)]` and `[After(Assembly)]` for shared context across test classes
+- TUnit supports advanced lifecycle hooks like `[Before(TestSession)]` and `[After(TestSession)]`
+
+## Standard Tests
+
+- Keep tests focused on a single behavior
+- Avoid testing multiple behaviors in one test method
+- Use TUnit's fluent assertion syntax with `await Assert.That()`
+- Include only the assertions needed to verify the test case
+- Make tests independent and idempotent (can run in any order)
+- Avoid test interdependencies (use `[DependsOn]` attribute if needed)
+
+## Data-Driven Tests
+
+- Use `[Arguments]` attribute for inline test data (equivalent to xUnit's `[InlineData]`)
+- Use `[MethodData]` for method-based test data (equivalent to xUnit's `[MemberData]`)
+- Use `[ClassData]` for class-based test data
+- Create custom data sources by implementing `ITestDataSource`
+- Use meaningful parameter names in data-driven tests
+- Multiple `[Arguments]` attributes can be applied to the same test method
+
+## Assertions
+
+- Use `await Assert.That(value).IsEqualTo(expected)` for value equality
+- Use `await Assert.That(value).IsSameReferenceAs(expected)` for reference equality
+- Use `await Assert.That(value).IsTrue()` or `await Assert.That(value).IsFalse()` for boolean conditions
+- Use `await Assert.That(collection).Contains(item)` or `await Assert.That(collection).DoesNotContain(item)` for collections
+- Use `await Assert.That(value).Matches(pattern)` for regex pattern matching
+- Use `await Assert.That(action).Throws<TException>()` or `await Assert.That(asyncAction).ThrowsAsync<TException>()` to test exceptions
+- Chain assertions with `.And` operator: `await Assert.That(value).IsNotNull().And.IsEqualTo(expected)`
+- Use `.Or` operator for alternative conditions: `await Assert.That(value).IsEqualTo(1).Or.IsEqualTo(2)`
+- Use `.Within(tolerance)` for DateTime and numeric comparisons with tolerance
+- All assertions are asynchronous and must be awaited
+
+## Advanced Features
+
+- Use `[Repeat(n)]` to repeat tests multiple times
+- Use `[Retry(n)]` for automatic retry on failure
+- Use `[ParallelLimit<T>]` to control parallel execution limits
+- Use `[Skip("reason")]` to skip tests conditionally
+- Use `[DependsOn(nameof(OtherTest))]` to create test dependencies
+- Use `[Timeout(milliseconds)]` to set test timeouts
+- Create custom attributes by extending TUnit's base attributes
+
+## Test Organization
+
+- Group tests by feature or component
+- Use `[Category("CategoryName")]` for test categorization
+- Use `[DisplayName("Custom Test Name")]` for custom test names
+- Consider using `TestContext` for test diagnostics and information
+- Use conditional attributes like custom `[WindowsOnly]` for platform-specific tests
+
+## Performance and Parallel Execution
+
+- TUnit runs tests in parallel by default (unlike xUnit which requires explicit configuration)
+- Use `[NotInParallel]` to disable parallel execution for specific tests
+- Use `[ParallelLimit<T>]` with custom limit classes to control concurrency
+- Tests within the same class run sequentially by default
+- Use `[Repeat(n)]` with `[ParallelLimit<T>]` for load testing scenarios
+
+## Migration from xUnit
+
+- Replace `[Fact]` with `[Test]`
+- Replace `[Theory]` with `[Test]` and use `[Arguments]` for data
+- Replace `[InlineData]` with `[Arguments]`
+- Replace `[MemberData]` with `[MethodData]`
+- Replace `Assert.Equal` with `await Assert.That(actual).IsEqualTo(expected)`
+- Replace `Assert.True` with `await Assert.That(condition).IsTrue()`
+- Replace `Assert.Throws<T>` with `await Assert.That(action).Throws<T>()`
+- Replace constructor/IDisposable with `[Before(Test)]`/`[After(Test)]`
+- Replace `IClassFixture<T>` with `[Before(Class)]`/`[After(Class)]`
+
+**Why TUnit over xUnit?**
+
+TUnit offers a modern, fast, and flexible testing experience with advanced features not present in xUnit, such as asynchronous assertions, more refined lifecycle hooks, and improved data-driven testing capabilities. TUnit's fluent assertions provide clearer and more expressive test validation, making it especially suitable for complex .NET projects.

package/skills/dev-csharp-xunit.md

@@ -0,0 +1,69 @@
+---
+name: csharp-xunit
+description: 'Get best practices for XUnit unit testing, including data-driven tests'
+category: dev
+---
+
+# XUnit Best Practices
+
+Your goal is to help me write effective unit tests with XUnit, covering both standard and data-driven testing approaches.
+
+## Project Setup
+
+- Use a separate test project with naming convention `[ProjectName].Tests`
+- Reference Microsoft.NET.Test.Sdk, xunit, and xunit.runner.visualstudio packages
+- Create test classes that match the classes being tested (e.g., `CalculatorTests` for `Calculator`)
+- Use .NET SDK test commands: `dotnet test` for running tests
+
+## Test Structure
+
+- No test class attributes required (unlike MSTest/NUnit)
+- Use fact-based tests with `[Fact]` attribute for simple tests
+- Follow the Arrange-Act-Assert (AAA) pattern
+- Name tests using the pattern `MethodName_Scenario_ExpectedBehavior`
+- Use constructor for setup and `IDisposable.Dispose()` for teardown
+- Use `IClassFixture<T>` for shared context between tests in a class
+- Use `ICollectionFixture<T>` for shared context between multiple test classes
+
+## Standard Tests
+
+- Keep tests focused on a single behavior
+- Avoid testing multiple behaviors in one test method
+- Use clear assertions that express intent
+- Include only the assertions needed to verify the test case
+- Make tests independent and idempotent (can run in any order)
+- Avoid test interdependencies
+
+## Data-Driven Tests
+
+- Use `[Theory]` combined with data source attributes
+- Use `[InlineData]` for inline test data
+- Use `[MemberData]` for method-based test data
+- Use `[ClassData]` for class-based test data
+- Create custom data attributes by implementing `DataAttribute`
+- Use meaningful parameter names in data-driven tests
+
+## Assertions
+
+- Use `Assert.Equal` for value equality
+- Use `Assert.Same` for reference equality
+- Use `Assert.True`/`Assert.False` for boolean conditions
+- Use `Assert.Contains`/`Assert.DoesNotContain` for collections
+- Use `Assert.Matches`/`Assert.DoesNotMatch` for regex pattern matching
+- Use `Assert.Throws<T>` or `await Assert.ThrowsAsync<T>` to test exceptions
+- Use fluent assertions library for more readable assertions
+
+## Mocking and Isolation
+
+- Consider using Moq or NSubstitute alongside XUnit
+- Mock dependencies to isolate units under test
+- Use interfaces to facilitate mocking
+- Consider using a DI container for complex test setups
+
+## Test Organization
+
+- Group tests by feature or component
+- Use `[Trait("Category", "CategoryName")]` for categorization
+- Use collection fixtures to group tests with shared dependencies
+- Consider output helpers (`ITestOutputHelper`) for test diagnostics
+- Skip tests conditionally with `Skip = "reason"` in fact/theory attributes

package/skills/dev-debug-failing-test.md

@@ -0,0 +1,90 @@
+---
+name: debug-failing-test
+description: Debug a failing test using an iterative logging approach, then clean up and document the learning.
+category: dev
+---
+
+Debug a failing unit test by iteratively adding verbose logging, running the test, and analyzing the output until the root cause is found and fixed.
+
+## Workflow
+
+### Phase 1: Initial Assessment
+
+1. **Run the failing test** to capture the current error message and stack trace
+2. **Read the test file** to understand what is being tested
+3. **Read the source file** being tested to understand the expected behavior
+4. **Identify the assertion that fails** and what values are involved
+
+### Phase 2: Iterative Debugging Loop
+
+Repeat until the root cause is understood:
+
+1. **Add verbose logging** around the suspicious code:
+    - Use `console.log('[DEBUG]', ...)` with descriptive labels
+    - Log input values, intermediate states, and return values
+    - Log before/after key operations
+    - Add timestamps if timing might be relevant
+
+2. **Run the test** and capture output
+
+3. **Assess the logging output:**
+    - What values are unexpected?
+    - Where does the behavior diverge from expectations?
+    - What additional logging would help narrow down the issue?
+
+4. **Decide next action:**
+    - If root cause is clear → proceed to fix
+    - If more information needed → add more targeted logging and repeat
+
+### Phase 3: Fix and Verify
+
+1. **Implement the fix** based on findings
+2. **Run the test** to verify it passes
+3. **Run related tests** to ensure no regressions
+
+### Phase 4: Clean Up
+
+1. **Remove ALL debugging artifacts:**
+    - Delete all `console.log('[DEBUG]', ...)` statements added
+    - Remove any temporary variables or code added for debugging
+    - Ensure the code is in a clean, production-ready state
+
+2. **Verify the test still passes** after cleanup
+
+### Phase 5: Document and Learn
+
+1. **Provide a summary** to the user (1-3 sentences):
+    - What was the bug?
+    - What was the fix?
+
+2. **Record the learning** by following the learning instructions (if you have them):
+    - Extract a single, clear learning from this debugging session
+    - Add it to the "Learnings" section of the most relevant instruction file
+    - If a similar learning already exists, increment its counter instead
+
+## Logging Conventions
+
+When adding debug logging, use this format for easy identification and removal:
+
+```typescript
+console.log('[DEBUG] <location>:', <value>);
+console.log('[DEBUG] before <operation>:', { input, state });
+console.log('[DEBUG] after <operation>:', { result, state });
+```
+
+## Example Debug Session
+
+```typescript
+// Added logging example:
+console.log('[DEBUG] getEnvironments input:', { workspaceFolder });
+const envs = await manager.getEnvironments(workspaceFolder);
+console.log('[DEBUG] getEnvironments result:', { count: envs.length, envs });
+```
+
+## Notes
+
+- Prefer targeted logging over flooding the output
+- Start with the failing assertion and work backwards
+- Consider async timing issues, race conditions, and mock setup problems
+- Check that mocks are returning expected values
+- Verify test setup/teardown is correct

package/skills/dev-diff-analyze.md

@@ -0,0 +1,32 @@
+---
+name: diff-analyze
+description: Analyze git diffs for risk scoring, reviewer recommendations, and change classification
+argument-hint: "[--branch BRANCH] [--pr PR#]"
+allowed-tools: mcp__claude-flow__analyze_diff mcp__claude-flow__analyze_diff-risk mcp__claude-flow__analyze_diff-classify mcp__claude-flow__analyze_diff-reviewers mcp__claude-flow__analyze_diff-stats mcp__claude-flow__analyze_file-risk Bash
+category: dev
+---
+
+# Diff Analysis
+
+Analyze git diffs for risk, complexity, and reviewer assignment.
+
+## When to use
+
+Before submitting a PR or after making significant changes, analyze the diff to understand risk level, get reviewer recommendations, and classify the type of change.
+
+## Steps
+
+1. **Analyze diff** — call `mcp__claude-flow__analyze_diff` with the diff content for a comprehensive analysis
+2. **Risk score** — call `mcp__claude-flow__analyze_diff-risk` for a quantified risk assessment
+3. **Classify changes** — call `mcp__claude-flow__analyze_diff-classify` to categorize (feature, bugfix, refactor, etc.)
+4. **Get reviewers** — call `mcp__claude-flow__analyze_diff-reviewers` for recommended reviewers based on code ownership
+5. **Diff stats** — call `mcp__claude-flow__analyze_diff-stats` for line counts, file counts, complexity metrics
+6. **File-level risk** — call `mcp__claude-flow__analyze_file-risk` for per-file risk breakdown
+
+## Risk factors
+
+- Files with high churn history
+- Security-sensitive paths (auth, crypto, permissions)
+- Large diffs (>500 lines)
+- Cross-module changes
+- Database migration files

package/skills/dev-diffs.md

@@ -0,0 +1,24 @@
+---
+name: diffs
+description: Use the diffs tool to produce real, shareable diffs (viewer URL, file artifact, or both) instead of manual edit summaries.
+category: dev
+---
+
+When you need to show edits as a real diff, prefer the `diffs` tool instead of writing a manual summary.
+
+The `diffs` tool accepts either `before` + `after` text, or a unified `patch` string.
+
+Use `mode=view` when you want an interactive gateway-hosted viewer. After the tool returns, use `details.viewerUrl` with the canvas tool via `canvas present` or `canvas navigate`.
+If the deployment uses a loopback trusted proxy (for example Tailscale Serve with `gateway.trustedProxies` including `127.0.0.1`), raw loopback viewer requests can fail closed without forwarded client-IP headers. In that topology, prefer `mode=file` / `mode=both`, or use a configured `viewerBaseUrl` / explicit proxy/public `baseUrl` when you need a shareable viewer URL.
+
+Use `mode=file` when you need a rendered file artifact. Set `fileFormat=png` (default) or `fileFormat=pdf`. The tool result includes `details.filePath`.
+
+For large or high-fidelity files, use `fileQuality` (`standard`|`hq`|`print`) and optionally override `fileScale`/`fileMaxWidth`.
+
+When you need to deliver the rendered file to a user or channel, do not rely on the raw tool-result renderer. Instead, call the `message` tool and pass `details.filePath` through `path` or `filePath`.
+
+Use `mode=both` when you want both the gateway viewer URL and the rendered artifact.
+
+If the user has configured diffs plugin defaults, prefer omitting `mode`, `theme`, `layout`, and related presentation options unless you need to override them for this specific diff.
+
+Include `path` for before/after text when you know the file name.

package/skills/dev-dotnet-best-practices.md

@@ -0,0 +1,86 @@
+---
+name: dotnet-best-practices
+description: 'Ensure .NET/C# code meets best practices for the solution/project.'
+category: dev
+---
+
+# .NET/C# Best Practices
+
+Your task is to ensure .NET/C# code in ${selection} meets the best practices specific to this solution/project. This includes:
+
+## Documentation & Structure
+
+- Create comprehensive XML documentation comments for all public classes, interfaces, methods, and properties
+- Include parameter descriptions and return value descriptions in XML comments
+- Follow the established namespace structure: {Core|Console|App|Service}.{Feature}
+
+## Design Patterns & Architecture
+
+- Use primary constructor syntax for dependency injection (e.g., `public class MyClass(IDependency dependency)`)
+- Implement the Command Handler pattern with generic base classes (e.g., `CommandHandler<TOptions>`)
+- Use interface segregation with clear naming conventions (prefix interfaces with 'I')
+- Follow the Factory pattern for complex object creation.
+
+## Dependency Injection & Services
+
+- Use constructor dependency injection with null checks via ArgumentNullException
+- Register services with appropriate lifetimes (Singleton, Scoped, Transient)
+- Use Microsoft.Extensions.DependencyInjection patterns
+- Implement service interfaces for testability
+
+## Resource Management & Localization
+
+- Use ResourceManager for localized messages and error strings
+- Separate LogMessages and ErrorMessages resource files
+- Access resources via `_resourceManager.GetString("MessageKey")`
+
+## Async/Await Patterns
+
+- Use async/await for all I/O operations and long-running tasks
+- Return Task or Task<T> from async methods
+- Use ConfigureAwait(false) where appropriate
+- Handle async exceptions properly
+
+## Testing Standards
+
+- Use MSTest framework with FluentAssertions for assertions
+- Follow AAA pattern (Arrange, Act, Assert)
+- Use Moq for mocking dependencies
+- Test both success and failure scenarios
+- Include null parameter validation tests
+
+## Configuration & Settings
+
+- Use strongly-typed configuration classes with data annotations
+- Implement validation attributes (Required, NotEmptyOrWhitespace)
+- Use IConfiguration binding for settings
+- Support appsettings.json configuration files
+
+## Semantic Kernel & AI Integration
+
+- Use Microsoft.SemanticKernel for AI operations
+- Implement proper kernel configuration and service registration
+- Handle AI model settings (ChatCompletion, Embedding, etc.)
+- Use structured output patterns for reliable AI responses
+
+## Error Handling & Logging
+
+- Use structured logging with Microsoft.Extensions.Logging
+- Include scoped logging with meaningful context
+- Throw specific exceptions with descriptive messages
+- Use try-catch blocks for expected failure scenarios
+
+## Performance & Security
+
+- Use C# 12+ features and .NET 8 optimizations where applicable
+- Implement proper input validation and sanitization
+- Use parameterized queries for database operations
+- Follow secure coding practices for AI/ML operations
+
+## Code Quality
+
+- Ensure SOLID principles compliance
+- Avoid code duplication through base classes and utilities
+- Use meaningful names that reflect domain concepts
+- Keep methods focused and cohesive
+- Implement proper disposal patterns for resources

package/skills/dev-dotnet-design-pattern-review.md

@@ -0,0 +1,43 @@
+---
+name: dotnet-design-pattern-review
+description: 'Review the C#/.NET code for design pattern implementation and suggest improvements.'
+category: dev
+---
+
+# .NET/C# Design Pattern Review
+
+Review the C#/.NET code in ${selection} for design pattern implementation and suggest improvements for the solution/project. Do not make any changes to the code, just provide a review.
+
+## Required Design Patterns
+
+- **Command Pattern**: Generic base classes (`CommandHandler<TOptions>`), `ICommandHandler<TOptions>` interface, `CommandHandlerOptions` inheritance, static `SetupCommand(IHost host)` methods
+- **Factory Pattern**: Complex object creation service provider integration
+- **Dependency Injection**: Primary constructor syntax, `ArgumentNullException` null checks, interface abstractions, proper service lifetimes
+- **Repository Pattern**: Async data access interfaces provider abstractions for connections
+- **Provider Pattern**: External service abstractions (database, AI), clear contracts, configuration handling
+- **Resource Pattern**: ResourceManager for localized messages, separate .resx files (LogMessages, ErrorMessages)
+
+## Review Checklist
+
+- **Design Patterns**: Identify patterns used. Are Command Handler, Factory, Provider, and Repository patterns correctly implemented? Missing beneficial patterns?
+- **Architecture**: Follow namespace conventions (`{Core|Console|App|Service}.{Feature}`)? Proper separation between Core/Console projects? Modular and readable?
+- **.NET Best Practices**: Primary constructors, async/await with Task returns, ResourceManager usage, structured logging, strongly-typed configuration?
+- **GoF Patterns**: Command, Factory, Template Method, Strategy patterns correctly implemented?
+- **SOLID Principles**: Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, Dependency Inversion violations?
+- **Performance**: Proper async/await, resource disposal, ConfigureAwait(false), parallel processing opportunities?
+- **Maintainability**: Clear separation of concerns, consistent error handling, proper configuration usage?
+- **Testability**: Dependencies abstracted via interfaces, mockable components, async testability, AAA pattern compatibility?
+- **Security**: Input validation, secure credential handling, parameterized queries, safe exception handling?
+- **Documentation**: XML docs for public APIs, parameter/return descriptions, resource file organization?
+- **Code Clarity**: Meaningful names reflecting domain concepts, clear intent through patterns, self-explanatory structure?
+- **Clean Code**: Consistent style, appropriate method/class size, minimal complexity, eliminated duplication?
+
+## Improvement Focus Areas
+
+- **Command Handlers**: Validation in base class, consistent error handling, proper resource management
+- **Factories**: Dependency configuration, service provider integration, disposal patterns
+- **Providers**: Connection management, async patterns, exception handling and logging
+- **Configuration**: Data annotations, validation attributes, secure sensitive value handling
+- **AI/ML Integration**: Semantic Kernel patterns, structured output handling, model configuration
+
+Provide specific, actionable recommendations for improvements aligned with the project's architecture and .NET best practices.

package/skills/dev-dotnet-timezone.md

@@ -0,0 +1,110 @@
+---
+name: dotnet-timezone
+description: '.NET timezone handling guidance for C# applications. Use when working with TimeZoneInfo, DateTimeOffset, NodaTime, UTC conversion, daylight saving time, scheduling across timezones, cross-platform Windows/IANA timezone IDs, or when a .NET user needs the timezone for a city, address, region, or country and copy-paste-ready C# code.'
+category: dev
+---
+
+# .NET Timezone
+
+Resolve timezone questions for .NET and C# code with production-safe guidance and copy-paste-ready snippets.
+
+## Start With The Right Path
+
+Identify the request type first:
+
+- Address or location lookup
+- Timezone ID lookup
+- UTC/local conversion
+- Cross-platform timezone compatibility
+- Scheduling or DST handling
+- API or persistence design
+
+If the library is unclear, default to `TimeZoneConverter` for cross-platform work. If the scenario involves recurring schedules or strict DST rules, prefer `NodaTime`.
+
+## Resolve Addresses And Locations
+
+If the user provides an address, city, region, country, or document containing place names:
+
+1. Extract each location from the input.
+2. Read `references/timezone-index.md` for common Windows and IANA mappings.
+3. If the exact location is not listed, infer the correct IANA zone from geography, then map it to the Windows ID.
+4. Return both IDs and a ready-to-use C# example.
+
+For each resolved location, provide:
+
+```text
+Location: <resolved place>
+Windows ID: <windows id>
+IANA ID: <iana id>
+UTC offset: <standard offset and DST offset when relevant>
+DST: <yes/no>
+```
+
+Then include a cross-platform snippet like:
+
+```csharp
+using TimeZoneConverter;
+
+TimeZoneInfo tz = TZConvert.GetTimeZoneInfo("Asia/Colombo");
+DateTime local = TimeZoneInfo.ConvertTimeFromUtc(DateTime.UtcNow, tz);
+```
+
+If multiple locations are present, include one block per location and then a combined multi-timezone snippet.
+
+If a location is ambiguous, list the possible timezone matches and ask the user to choose the correct one.
+
+## Look Up Timezone IDs
+
+Use `references/timezone-index.md` for Windows to IANA mappings.
+
+Always provide both formats:
+
+- Windows ID for `TimeZoneInfo.FindSystemTimeZoneById()` on Windows
+- IANA ID for Linux, containers, `NodaTime`, and `TimeZoneConverter`
+
+## Generate Code
+
+Use `references/code-patterns.md` and pick the smallest pattern that fits:
+
+- Pattern 1: `TimeZoneInfo` for Windows-only code
+- Pattern 2: `TimeZoneConverter` for cross-platform conversion
+- Pattern 3: `NodaTime` for strict timezone arithmetic and DST-sensitive scheduling
+- Pattern 4: `DateTimeOffset` for APIs and data transfer
+- Pattern 5: ASP.NET Core persistence and presentation
+- Pattern 6: recurring jobs and schedulers
+- Pattern 7: ambiguous and invalid DST timestamps
+
+Always include package guidance when recommending third-party libraries.
+
+## Warn About Common Pitfalls
+
+Mention the relevant warning when applicable:
+
+- `TimeZoneInfo.FindSystemTimeZoneById()` is platform-specific for timezone IDs.
+- Avoid storing `DateTime.Now` in databases; store UTC instead.
+- Treat `DateTimeKind.Unspecified` as a bug risk unless it is deliberate input.
+- DST transitions can skip or repeat local times.
+- Azure Windows and Azure Linux environments may expect different timezone ID formats.
+
+## Response Shape
+
+For address and location requests:
+
+1. Return the resolved timezone block for each location.
+2. State the recommended implementation in one sentence.
+3. Include a copy-paste-ready C# snippet.
+
+For code and architecture requests:
+
+1. State the recommended approach in one sentence.
+2. Provide the timezone IDs if relevant.
+3. Include the minimal working code snippet.
+4. Mention the package requirement if needed.
+5. Add one pitfall warning if it matters.
+
+Keep responses concise and code-first.
+
+## References
+
+- `references/timezone-index.md`: common Windows and IANA timezone mappings
+- `references/code-patterns.md`: ready-to-use .NET timezone patterns