From 30544416304deea0e09d7ff8b11d18d3d9020462 Mon Sep 17 00:00:00 2001 From: lmiranda Date: Fri, 16 Jan 2026 11:52:06 -0500 Subject: [PATCH] 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 --- CLAUDE.md | 22 +++++++- docs/project-lessons-learned/INDEX.md | 50 +++++++++++++++++++ .../phase-4-dbt-test-syntax.md | 38 ++++++++++++++ 3 files changed, 108 insertions(+), 2 deletions(-) create mode 100644 docs/project-lessons-learned/INDEX.md create mode 100644 docs/project-lessons-learned/phase-4-dbt-test-syntax.md diff --git a/CLAUDE.md b/CLAUDE.md index 7814622..1d4604a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -270,9 +270,9 @@ All scripts in `scripts/`: | Skill | Trigger | Purpose | |-------|---------|---------| | `/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-close` | Sprint completion | Capture lessons learned to Wiki.js | +| `/projman:sprint-close` | Sprint completion | Capture lessons learned (Wiki.js or local backup) | ### Default Behavior @@ -299,6 +299,24 @@ When user requests implementation work: **Wiki.js**: - `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 Every Gitea issue should include: diff --git a/docs/project-lessons-learned/INDEX.md b/docs/project-lessons-learned/INDEX.md new file mode 100644 index 0000000..813111c --- /dev/null +++ b/docs/project-lessons-learned/INDEX.md @@ -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] +``` diff --git a/docs/project-lessons-learned/phase-4-dbt-test-syntax.md b/docs/project-lessons-learned/phase-4-dbt-test-syntax.md new file mode 100644 index 0000000..959780a --- /dev/null +++ b/docs/project-lessons-learned/phase-4-dbt-test-syntax.md @@ -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