Feature/rework scaffolding

.claude/CLAUDE.md

@@ -110,7 +110,7 @@ New Feature → [1] eftdb-feature-initializer
 | `test-writer` | Creates unit and integration tests | |
 | `test-coverage-planner` | Analyzes test coverage gaps | `/coverage-plan` |
 | `example-feature-generator` | Creates usage examples | |
-| `git-committer` | Formats, tests, stages, generates commit message | `/prepare-commit` |
+| `git-committer` | Formats, tests, generates commit message (does not stage) | `/prepare-commit` |
 | `code-detective` | Investigates bugs, traces history | |
 | `pr-code-reviewer` | Reviews PR changes against patterns | `/review` |
 | `eftdb-docs-writer` | Writes and updates documentation | |

.claude/agents/code-detective.md

@@ -1,6 +1,57 @@
 ---
 name: code-detective
-description: Use this agent when the user needs to understand the root cause of a bug, trace when it was introduced, identify the last working commit, or analyze code behavior without making any changes. This agent is for investigation and analysis only, not for fixing bugs.\n\nExamples:\n\n<example>\nContext: User is investigating why HypertableDiffer is not detecting chunk time interval changes.\n\nuser: "The HypertableDiffer doesn't seem to detect when I change the chunk time interval from 7 days to 1 day. Can you investigate when this broke?"\n\nassistant: "I'll use the code-detective agent to analyze the HypertableDiffer implementation and trace through the git history to find when this regression was introduced."\n\n<commentary>\nThe user is asking to investigate a bug's root cause and history, which is exactly what code-detective does. Use the Agent tool to launch code-detective for deep analysis of the differ logic and git history.\n</commentary>\n</example>\n\n<example>\nContext: User wants to understand why continuous aggregate scaffolding is generating incorrect column names.\n\nuser: "I scaffolded a continuous aggregate from the database and the column names in the generated entity don't match what's in the database. What's going on?"\n\nassistant: "Let me use the code-detective agent to trace through the scaffolding pipeline and identify where the column name resolution is going wrong."\n\n<commentary>\nThis is an investigation task to understand existing behavior and identify the issue source. Code-detective should analyze ContinuousAggregateScaffoldingExtractor, AnnotationApplier, and related naming convention handling without making changes.\n</commentary>\n</example>\n\n<example>\nContext: User is trying to understand when a feature stopped working.\n\nuser: "Reorder policies worked in version 1.2.0 but now in 1.3.0 they're not being applied during migrations. Can you find out what changed?"\n\nassistant: "I'll launch the code-detective agent to compare the git history between versions 1.2.0 and 1.3.0, focusing on ReorderPolicyDiffer and related migration code."\n\n<commentary>\nThe user needs historical analysis across versions to identify a regression. Code-detective should examine git commits, diffs, and potentially GitHub issues between the two versions.\n</commentary>\n</example>\n\n<example>\nContext: User wants to understand complex code flow before making changes.\n\nuser: "Before I add support for compression policies, I want to understand how the existing reorder policy implementation works end-to-end."\n\nassistant: "I'll use the code-detective agent to trace the complete flow of reorder policies from attribute/fluent API configuration through conventions, differs, generators, and scaffolding."\n\n<commentary>\nThis is a code comprehension task requiring deep analysis of implementation patterns. Code-detective should provide a detailed walkthrough without modifying anything.\n</commentary>\n</example>
+description: |-
+  Use this agent when the user needs to understand the root cause of a bug, trace when it was introduced, identify the last working commit, or analyze code behavior without making any changes. This agent is for investigation and analysis only, not for fixing bugs.
+
+  Examples:
+
+  <example>
+  Context: User is investigating why HypertableDiffer is not detecting chunk time interval changes.
+
+  user: "The HypertableDiffer doesn't seem to detect when I change the chunk time interval from 7 days to 1 day. Can you investigate when this broke?"
+
+  assistant: "I'll use the code-detective agent to analyze the HypertableDiffer implementation and trace through the git history to find when this regression was introduced."
+
+  <commentary>
+  The user is asking to investigate a bug's root cause and history, which is exactly what code-detective does. Use the Agent tool to launch code-detective for deep analysis of the differ logic and git history.
+  </commentary>
+  </example>
+
+  <example>
+  Context: User wants to understand why continuous aggregate scaffolding is generating incorrect column names.
+
+  user: "I scaffolded a continuous aggregate from the database and the column names in the generated entity don't match what's in the database. What's going on?"
+
+  assistant: "Let me use the code-detective agent to trace through the scaffolding pipeline and identify where the column name resolution is going wrong."
+
+  <commentary>
+  This is an investigation task to understand existing behavior and identify the issue source. Code-detective should analyze ContinuousAggregateScaffoldingExtractor, AnnotationApplier, and related naming convention handling without making changes.
+  </commentary>
+  </example>
+
+  <example>
+  Context: User is trying to understand when a feature stopped working.
+
+  user: "Reorder policies worked in version 1.2.0 but now in 1.3.0 they're not being applied during migrations. Can you find out what changed?"
+
+  assistant: "I'll launch the code-detective agent to compare the git history between versions 1.2.0 and 1.3.0, focusing on ReorderPolicyDiffer and related migration code."
+
+  <commentary>
+  The user needs historical analysis across versions to identify a regression. Code-detective should examine git commits, diffs, and potentially GitHub issues between the two versions.
+  </commentary>
+  </example>
+
+  <example>
+  Context: User wants to understand complex code flow before making changes.
+
+  user: "Before I add support for compression policies, I want to understand how the existing reorder policy implementation works end-to-end."
+
+  assistant: "I'll use the code-detective agent to trace the complete flow of reorder policies from attribute/fluent API configuration through conventions, differs, generators, and scaffolding."
+
+  <commentary>
+  This is a code comprehension task requiring deep analysis of implementation patterns. Code-detective should provide a detailed walkthrough without modifying anything.
+  </commentary>
+  </example>
 tools: Bash, Glob, Grep, Read, WebSearch, AskUserQuestion
 model: sonnet
 color: red

.claude/agents/eftdb-bug-fixer.md

@@ -1,6 +1,35 @@
 ---
 name: eftdb-bug-fixer
-description: Use this agent when bugs are discovered in existing runtime or design-time code within the CmdScale.EntityFrameworkCore.TimescaleDB library. This includes:\n\n<example>\nContext: User discovers a bug in the HypertableDiffer.\nuser: "The HypertableDiffer is not detecting changes to chunk time interval"\nassistant: "I'll use the eftdb-bug-fixer agent to analyze and fix the HypertableDiffer issue."\n<uses Task tool to invoke eftdb-bug-fixer>\n</example>\n\n<example>\nContext: SQL generation is incorrect for reorder policies.\nuser: "The ReorderPolicySqlGenerator is generating invalid SQL with wrong schema qualification"\nassistant: "I'll launch the eftdb-bug-fixer agent to fix the SQL generation bug in ReorderPolicySqlGenerator."\n<uses Task tool to invoke eftdb-bug-fixer>\n</example>\n\n<example>\nContext: Scaffolding extractor query is failing.\nuser: "The ContinuousAggregateScaffoldingExtractor is throwing NullReferenceException when extracting aggregate functions"\nassistant: "Let me use the eftdb-bug-fixer agent to debug and fix the scaffolding extractor."\n<uses Task tool to invoke eftdb-bug-fixer>\n</example>\n\n<example>\nContext: Another agent reports a bug during its work.\nuser: "The eftdb-scaffold-support agent reported a mismatch between runtime annotations and scaffolding expectations"\nassistant: "I'll use the eftdb-bug-fixer agent to resolve the annotation mismatch issue reported by the scaffolding agent."\n<uses Task tool to invoke eftdb-bug-fixer>\n</example>
+description: |-
+  Use this agent when bugs are discovered in existing runtime or design-time code within the CmdScale.EntityFrameworkCore.TimescaleDB library. This includes:
+
+  <example>
+  Context: User discovers a bug in the HypertableDiffer.
+  user: "The HypertableDiffer is not detecting changes to chunk time interval"
+  assistant: "I'll use the eftdb-bug-fixer agent to analyze and fix the HypertableDiffer issue."
+  <uses Task tool to invoke eftdb-bug-fixer>
+  </example>
+
+  <example>
+  Context: SQL generation is incorrect for reorder policies.
+  user: "The ReorderPolicySqlGenerator is generating invalid SQL with wrong schema qualification"
+  assistant: "I'll launch the eftdb-bug-fixer agent to fix the SQL generation bug in ReorderPolicySqlGenerator."
+  <uses Task tool to invoke eftdb-bug-fixer>
+  </example>
+
+  <example>
+  Context: Scaffolding extractor query is failing.
+  user: "The ContinuousAggregateScaffoldingExtractor is throwing NullReferenceException when extracting aggregate functions"
+  assistant: "Let me use the eftdb-bug-fixer agent to debug and fix the scaffolding extractor."
+  <uses Task tool to invoke eftdb-bug-fixer>
+  </example>
+
+  <example>
+  Context: Another agent reports a bug during its work.
+  user: "The eftdb-scaffold-support agent reported a mismatch between runtime annotations and scaffolding expectations"
+  assistant: "I'll use the eftdb-bug-fixer agent to resolve the annotation mismatch issue reported by the scaffolding agent."
+  <uses Task tool to invoke eftdb-bug-fixer>
+  </example>
 model: sonnet
 color: red
 ---
@@ -120,56 +149,7 @@ Before fixing, understand WHY the bug exists:
    - Use `SqlBuilderHelper` for SQL construction
    - Use `StoreObjectIdentifier` pattern for column names
 
-**Fix Pattern Examples:**
-
-```csharp
-// Bug: Missing null check causing NullReferenceException
-// INCORRECT FIX - Too broad
-public void ProcessEntity(IEntityType entity)
-{
-    try
-    {
-        var annotation = entity.FindAnnotation("SomeKey")?.Value;
-        // ... process
-    }
-    catch (Exception ex)
-    {
-        // Swallow all exceptions
-    }
-}
-
-// CORRECT FIX - Targeted null check
-public void ProcessEntity(IEntityType entity)
-{
-    IAnnotation? annotation = entity.FindAnnotation("SomeKey");
-    if (annotation?.Value == null)
-    {
-        return; // Or handle appropriately
-    }
-
-    // ... process with guaranteed non-null value
-}
-```
-
-```csharp
-// Bug: Column name not respecting naming convention
-// INCORRECT FIX - Hard-coded conversion
-string columnName = propertyName.ToSnakeCase(); // Don't assume convention
-
-// CORRECT FIX - Use EF Core's convention system
-StoreObjectIdentifier storeIdentifier = StoreObjectIdentifier.Table(tableName, schema);
-string columnName = property.GetColumnName(storeIdentifier);
-```
-
-```csharp
-// Bug: identifier not quoted via the helper
-// INCORRECT FIX - Hard-coded quotes
-string sql = $"SELECT * FROM \"{schema}\".\"{table}\"";
-
-// CORRECT FIX - Use SqlBuilderHelper
-string qualifiedName = SqlBuilderHelper.QualifiedIdentifier(table, schema);
-string sql = $"SELECT * FROM {qualifiedName}";
-```
+**Fix patterns:** For null-check, column-name resolution, and identifier-quoting approaches, see `.claude/reference/patterns.md` sections 7–8 — both include INCORRECT vs CORRECT examples.
 
 ### Phase 4: Verification
 
@@ -194,144 +174,26 @@ After implementing the fix:
 
 ## Common Debugging Techniques
 
-### For Annotation Issues:
-```csharp
-// Add diagnostic logging
-IAnnotation? annotation = entity.FindAnnotation(SomeAnnotations.KeyName);
-if (annotation == null)
-{
-    // Log: Expected annotation not found
-    return null;
-}
-
-// Verify annotation value type
-if (annotation.Value is not string expectedValue)
-{
-    // Log: Annotation value has unexpected type
-    return null;
-}
-```
-
-### For SQL Generation Issues:
-```csharp
-// Inspect the statements returned by the feature SqlGenerator
-List<string> statements = HypertableSqlGenerator.Generate(operation);
-foreach (string statement in statements)
-{
-    System.Diagnostics.Debug.WriteLine($"Generated SQL: {statement}");
-}
-```
-
-### For Differ Issues:
-```csharp
-// Compare properties one by one
-bool hasChanges =
-    sourceInfo.Property1 != targetInfo.Property1 ||
-    sourceInfo.Property2 != targetInfo.Property2 ||
-    !AreListsEqual(sourceInfo.List1, targetInfo.List1);
-
-// Log what changed
-if (sourceInfo.Property1 != targetInfo.Property1)
-{
-    // Log: Property1 changed from X to Y
-}
-```
+Add temporary `Console.Error.WriteLine` or `Debug.WriteLine` statements to inspect annotation values, generated SQL strings, or differ property comparisons. Remove all diagnostic output before committing.
 
 ## Handoff Protocol
 
-### Successful Fix Completion:
-
-```
-✅ BUG FIX COMPLETE
-
-Bug Description:
-[Brief description of the bug]
-
-Root Cause:
-[Explanation of why the bug occurred]
-
-Files Modified:
-- [File path 1] - [Brief description of change]
-- [File path 2] - [Brief description of change]
-
-Fix Summary:
-[1-2 paragraph explanation of what was changed and why]
-
-Verification:
-□ Solution builds successfully
-□ Bug reproduction case now works correctly
-□ No regressions observed
-□ Existing tests still pass (if applicable)
-
-NEXT STEPS:
-→ Use test-writer agent to add regression test
-   (Prevents this bug from reoccurring)
-
-→ Use git-committer agent when ready to commit
-   (Creates fix: [bug description] commit)
-
-RECOMMENDATION:
-Add test case covering: [specific scenario that exposed this bug]
-```
-
-### When Additional Issues are Discovered:
-
-While fixing one bug, you might discover related issues:
-
-```
-⚠️ ADDITIONAL ISSUE FOUND
-
-While fixing [Original Bug], discovered related issue:
-
-Secondary Issue:
-[Description of additional bug found]
-
-File Affected: [File path]
-
-Relationship to Original Bug:
-[How this relates to the bug being fixed]
-
-OPTIONS:
-1. Fix both issues together (if closely related and fix is still minimal)
-2. Fix original bug only, create separate bug report for secondary issue
-
-RECOMMENDATION: [Choice with rationale]
-
-If proceeding with option 2:
-→ Complete current fix first
-→ Document secondary issue clearly
-→ User can relaunch eftdb-bug-fixer for secondary issue
-```
-
-### When Fix Requires Design Change:
-
-If the bug cannot be fixed without significant design changes:
-
-```
-❌ BUG REQUIRES ARCHITECTURAL CHANGE
-
-Bug: [Description]
-File: [Path]
-
-Analysis:
-[Explanation of why simple fix won't work]
-
-Issue:
-The current architecture [describe limitation] which prevents a proper fix.
-
-Required Changes:
-1. [Architectural change 1]
-2. [Architectural change 2]
-3. [Impact on existing code]
-
-RECOMMENDATION:
-This is beyond bug-fixing scope. Options:
-1. Implement workaround with known limitations: [describe workaround]
-2. Plan architectural refactoring (coordinate with user)
-3. Document as known limitation if low impact
-
-Cannot proceed with standard bug fix. User decision required.
-```
+**On successful fix**, report:
+- Description of the bug and its root cause
+- Files modified with a one-line description of each change
+- Verification: solution builds, reproduction case resolved, no regressions, existing tests pass
+- Next step: launch `test-writer` agent to add a regression test
+
+**If an additional issue is found during the fix**, report:
+- Description of the secondary issue and which file is affected
+- How it relates to the original bug
+- Recommendation: fix both together (if closely related) or complete the original fix first and relaunch for the secondary issue
+
+**If the fix requires architectural change**, report:
+- Why a minimal fix is insufficient (the architectural constraint preventing it)
+- What structural changes would be required and their impact
+- Options: implement a known-limitation workaround, plan a refactoring, or document as a known limitation
+- Stop work — user decision required before proceeding
 
 ## Quality Standards
 

.claude/agents/eftdb-docs-writer.md

@@ -1,6 +1,43 @@
 ---
 name: eftdb-docs-writer
-description: Use this agent when the user requests documentation for CmdScale.EntityFrameworkCore.TimescaleDB features, API usage, configuration options, or any topic related to the TimescaleDB Entity Framework Core package. Examples include:\n\n<example>\nContext: User wants to document how to configure hypertables using the TimescaleDB EF Core library.\n\nuser: "I need documentation on how to set up hypertables in Entity Framework Core using the TimescaleDB package"\n\nassistant: "I'll use the Task tool to launch the eftdb-docs-writer agent to research the latest implementation and create comprehensive documentation covering both FluentAPI and DataAnnotations approaches."\n\n<commentary>\nThe user is requesting documentation on a specific TimescaleDB feature, which requires researching the current implementation and writing structured documentation.\n</commentary>\n</example>\n\n<example>\nContext: User has implemented a new feature and wants it documented.\n\nuser: "I just added support for continuous aggregates. Can you document this?"\n\nassistant: "I'll use the Task tool to launch the eftdb-docs-writer agent to analyze the implementation in the repository and create documentation for the continuous aggregates feature."\n\n<commentary>\nThe user needs documentation for a newly implemented feature, requiring repository analysis and documentation generation.\n</commentary>\n</example>\n\n<example>\nContext: User mentions updating or creating docs for TimescaleDB EF Core features.\n\nuser: "The compression settings documentation is outdated"\n\nassistant: "I'll use the Task tool to launch the eftdb-docs-writer agent to research the current compression implementation and update the documentation accordingly."\n\n<commentary>\nExisting documentation needs updating, requiring fresh analysis of the current implementation.\n</commentary>\n</example>
+description: |-
+  Use this agent when the user requests documentation for CmdScale.EntityFrameworkCore.TimescaleDB features, API usage, configuration options, or any topic related to the TimescaleDB Entity Framework Core package. Examples include:
+
+  <example>
+  Context: User wants to document how to configure hypertables using the TimescaleDB EF Core library.
+
+  user: "I need documentation on how to set up hypertables in Entity Framework Core using the TimescaleDB package"
+
+  assistant: "I'll use the Task tool to launch the eftdb-docs-writer agent to research the latest implementation and create comprehensive documentation covering both FluentAPI and DataAnnotations approaches."
+
+  <commentary>
+  The user is requesting documentation on a specific TimescaleDB feature, which requires researching the current implementation and writing structured documentation.
+  </commentary>
+  </example>
+
+  <example>
+  Context: User has implemented a new feature and wants it documented.
+
+  user: "I just added support for continuous aggregates. Can you document this?"
+
+  assistant: "I'll use the Task tool to launch the eftdb-docs-writer agent to analyze the implementation in the repository and create documentation for the continuous aggregates feature."
+
+  <commentary>
+  The user needs documentation for a newly implemented feature, requiring repository analysis and documentation generation.
+  </commentary>
+  </example>
+
+  <example>
+  Context: User mentions updating or creating docs for TimescaleDB EF Core features.
+
+  user: "The compression settings documentation is outdated"
+
+  assistant: "I'll use the Task tool to launch the eftdb-docs-writer agent to research the current compression implementation and update the documentation accordingly."
+
+  <commentary>
+  Existing documentation needs updating, requiring fresh analysis of the current implementation.
+  </commentary>
+  </example>
 model: sonnet
 color: cyan
 ---