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:
22
CLAUDE.md
22
CLAUDE.md
@@ -270,9 +270,9 @@ All scripts in `scripts/`:
|
|||||||
| Skill | Trigger | Purpose |
|
| Skill | Trigger | Purpose |
|
||||||
|-------|---------|---------|
|
|-------|---------|---------|
|
||||||
| `/projman:sprint-plan` | New sprint or phase implementation | Architecture analysis + Gitea issue creation |
|
| `/projman:sprint-plan` | New sprint or phase implementation | Architecture analysis + Gitea issue creation |
|
||||||
| `/projman:sprint-start` | Beginning implementation work | Load lessons learned, start execution |
|
| `/projman:sprint-start` | Beginning implementation work | Load lessons learned (Wiki.js or local), start execution |
|
||||||
| `/projman:sprint-status` | Check progress | Review blockers and completion status |
|
| `/projman:sprint-status` | Check progress | Review blockers and completion status |
|
||||||
| `/projman:sprint-close` | Sprint completion | Capture lessons learned to Wiki.js |
|
| `/projman:sprint-close` | Sprint completion | Capture lessons learned (Wiki.js or local backup) |
|
||||||
|
|
||||||
### Default Behavior
|
### Default Behavior
|
||||||
|
|
||||||
@@ -299,6 +299,24 @@ When user requests implementation work:
|
|||||||
**Wiki.js**:
|
**Wiki.js**:
|
||||||
- `search_lessons`, `create_lesson`, `search_pages`, `get_page`
|
- `search_lessons`, `create_lesson`, `search_pages`, `get_page`
|
||||||
|
|
||||||
|
### Lessons Learned (Backup Method)
|
||||||
|
|
||||||
|
**When Wiki.js is unavailable**, use the local backup in `docs/project-lessons-learned/`:
|
||||||
|
|
||||||
|
**At Sprint Start:**
|
||||||
|
1. Review `docs/project-lessons-learned/INDEX.md` for relevant past lessons
|
||||||
|
2. Search lesson files by tags/keywords before implementation
|
||||||
|
3. Apply prevention strategies from applicable lessons
|
||||||
|
|
||||||
|
**At Sprint Close:**
|
||||||
|
1. Try Wiki.js `create_lesson` first
|
||||||
|
2. If Wiki.js fails, create lesson in `docs/project-lessons-learned/`
|
||||||
|
3. Use naming convention: `{phase-or-sprint}-{short-description}.md`
|
||||||
|
4. Update `INDEX.md` with new entry
|
||||||
|
5. Follow the lesson template in INDEX.md
|
||||||
|
|
||||||
|
**Migration:** Once Wiki.js is configured, lessons will be migrated there for better searchability.
|
||||||
|
|
||||||
### Issue Structure
|
### Issue Structure
|
||||||
|
|
||||||
Every Gitea issue should include:
|
Every Gitea issue should include:
|
||||||
|
|||||||
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