docs: Add local lessons learned backup system
- Create docs/project-lessons-learned/ for local lesson storage - Add INDEX.md with lesson template and index table - Document Phase 4 dbt test syntax deprecation lesson - Update CLAUDE.md with backup method when Wiki.js unavailable This provides a fallback for capturing lessons learned while Wiki.js integration is being configured. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
50
docs/project-lessons-learned/INDEX.md
Normal file
50
docs/project-lessons-learned/INDEX.md
Normal file
@@ -0,0 +1,50 @@
|
||||
# Project Lessons Learned
|
||||
|
||||
This folder contains lessons learned from sprints and development work. These lessons help prevent repeating mistakes and capture valuable insights.
|
||||
|
||||
**Note:** This is a temporary local backup while Wiki.js integration is being configured. Once Wiki.js is ready, lessons will be migrated there for better searchability.
|
||||
|
||||
---
|
||||
|
||||
## Lessons Index
|
||||
|
||||
| Date | Sprint/Phase | Title | Tags |
|
||||
|------|--------------|-------|------|
|
||||
| 2026-01-16 | Phase 4 | [dbt Test Syntax Deprecation](./phase-4-dbt-test-syntax.md) | dbt, testing, yaml, deprecation |
|
||||
|
||||
---
|
||||
|
||||
## How to Use
|
||||
|
||||
### When Starting a Sprint
|
||||
1. Review relevant lessons in this folder before implementation
|
||||
2. Search by tags or keywords to find applicable insights
|
||||
3. Apply prevention strategies from past lessons
|
||||
|
||||
### When Closing a Sprint
|
||||
1. Document any significant lessons learned
|
||||
2. Use the template below
|
||||
3. Add entry to the index table above
|
||||
|
||||
---
|
||||
|
||||
## Lesson Template
|
||||
|
||||
```markdown
|
||||
# [Sprint/Phase] - [Lesson Title]
|
||||
|
||||
## Context
|
||||
[What were you trying to do?]
|
||||
|
||||
## Problem
|
||||
[What went wrong or what insight emerged?]
|
||||
|
||||
## Solution
|
||||
[How did you solve it?]
|
||||
|
||||
## Prevention
|
||||
[How can this be avoided in future sprints?]
|
||||
|
||||
## Tags
|
||||
[Comma-separated tags for search]
|
||||
```
|
||||
38
docs/project-lessons-learned/phase-4-dbt-test-syntax.md
Normal file
38
docs/project-lessons-learned/phase-4-dbt-test-syntax.md
Normal file
@@ -0,0 +1,38 @@
|
||||
# Phase 4 - dbt Test Syntax Deprecation
|
||||
|
||||
## Context
|
||||
Implementing dbt mart models with `accepted_values` tests for tier columns (safety_tier, income_quintile, amenity_tier) that should only contain values 1-5.
|
||||
|
||||
## Problem
|
||||
dbt 1.9+ introduced a deprecation warning for generic test arguments. The old syntax:
|
||||
|
||||
```yaml
|
||||
tests:
|
||||
- accepted_values:
|
||||
values: [1, 2, 3, 4, 5]
|
||||
```
|
||||
|
||||
Produces deprecation warnings:
|
||||
```
|
||||
MissingArgumentsPropertyInGenericTestDeprecation: Arguments to generic tests should be nested under the `arguments` property.
|
||||
```
|
||||
|
||||
## Solution
|
||||
Nest test arguments under the `arguments` property:
|
||||
|
||||
```yaml
|
||||
tests:
|
||||
- accepted_values:
|
||||
arguments:
|
||||
values: [1, 2, 3, 4, 5]
|
||||
```
|
||||
|
||||
This applies to all generic tests with arguments, not just `accepted_values`.
|
||||
|
||||
## Prevention
|
||||
- When writing dbt schema YAML files, always use the `arguments:` nesting for generic tests
|
||||
- Run `dbt parse --no-partial-parse` to catch all deprecation warnings before they become errors
|
||||
- Check dbt changelog when upgrading versions for breaking changes to test syntax
|
||||
|
||||
## Tags
|
||||
dbt, testing, yaml, deprecation, syntax, schema
|
||||
Reference in New Issue
Block a user