Active_prgs/Gromulus/LessonsLearned.md

# Lessons Learned

## Purpose
This file captures implementation lessons from Gromulus so future changes (human or AI-assisted) avoid repeated mistakes.

Use this file to record:
- Regressions and production-impacting bugs.
- Design decisions and tradeoffs.
- Workflow improvements discovered during development.

## How To Add Entries
- Add newest entries to the top of `## Entries`.
- Keep each entry short and actionable.
- Include affected files/functions when possible.
- End each entry with a prevention rule that can be applied during future work.

## Entry Template
Copy this block for each new lesson:

```md
### [YYYY-MM-DD] Short Title
- Context: What feature/change was being worked on.
- Symptom: What failed or almost failed.
- Root cause: Why it happened.
- Resolution: What fixed it.
- Prevention rule: A specific rule/check for future changes.
- References: File paths, function names, issue IDs, or commit hashes.
```

## Entries

### [2026-03-08] Keep Schema Docs Aligned With Live Database
- Context: Updating outdated `models.py` and database documentation.
- Symptom: Schema docs referenced old table/column names and omitted active tables.
- Root cause: Documentation drift after iterative schema changes.
- Resolution: Rebuilt schema docs from canonical DDL and live DB introspection.
- Prevention rule: After schema-affecting changes, update both `models.py` and `Database Dictonary.md` in the same task.
- References: `models.py`, `Database Dictonary.md`, `GromulusDatabaseUtilities.py`.

### [2026-03-08] Preserve Legacy Table Shapes Used by Runtime Queries
- Context: DAT metadata tables were reviewed for ORM/doc updates.
- Symptom: It was tempting to "improve" tables by adding PKs, but runtime behavior depends on current shape.
- Root cause: Assuming idealized schema is always safe to apply retroactively.
- Resolution: Documented current schema faithfully (including tables without declared PKs).
- Prevention rule: Treat DB shape as a compatibility contract unless an explicit migration plan exists.
- References: `no_intro_main`, `tosec_main`, query paths in `Gromulus_Lib.py`.
Revision:	988
Committed:	Sun Mar 8 04:15:07 2026 UTC (2 weeks, 6 days ago) by nino.borges
Content type:	text/markdown
File size:	2113 byte(s)
Log Message:	Added a database dictionary markdown file which attempts to describe at a highlevel the database, tables, fields and the reason for these. also updaed the models.py file to reflect the updated database, since it was so out of date. I'm currently not using it beyond documenting the schema. also added a Projet Guidelines file and lessons learned file. These are my attempt at tryiing out spec-driven development. Projectguidelines is the core guide that will act as the source of truth of the application.
#	Content
1	# Lessons Learned
2
3	## Purpose
4	This file captures implementation lessons from Gromulus so future changes (human or AI-assisted) avoid repeated mistakes.
5
6	Use this file to record:
7	- Regressions and production-impacting bugs.
8	- Design decisions and tradeoffs.
9	- Workflow improvements discovered during development.
10
11	## How To Add Entries
12	- Add newest entries to the top of `## Entries`.
13	- Keep each entry short and actionable.
14	- Include affected files/functions when possible.
15	- End each entry with a prevention rule that can be applied during future work.
16
17	## Entry Template
18	Copy this block for each new lesson:
19
20	```md
21	### [YYYY-MM-DD] Short Title
22	- Context: What feature/change was being worked on.
23	- Symptom: What failed or almost failed.
24	- Root cause: Why it happened.
25	- Resolution: What fixed it.
26	- Prevention rule: A specific rule/check for future changes.
27	- References: File paths, function names, issue IDs, or commit hashes.
28	```
29
30	## Entries
31
32	### [2026-03-08] Keep Schema Docs Aligned With Live Database
33	- Context: Updating outdated `models.py` and database documentation.
34	- Symptom: Schema docs referenced old table/column names and omitted active tables.
35	- Root cause: Documentation drift after iterative schema changes.
36	- Resolution: Rebuilt schema docs from canonical DDL and live DB introspection.
37	- Prevention rule: After schema-affecting changes, update both `models.py` and `Database Dictonary.md` in the same task.
38	- References: `models.py`, `Database Dictonary.md`, `GromulusDatabaseUtilities.py`.
39
40	### [2026-03-08] Preserve Legacy Table Shapes Used by Runtime Queries
41	- Context: DAT metadata tables were reviewed for ORM/doc updates.
42	- Symptom: It was tempting to "improve" tables by adding PKs, but runtime behavior depends on current shape.
43	- Root cause: Assuming idealized schema is always safe to apply retroactively.
44	- Resolution: Documented current schema faithfully (including tables without declared PKs).
45	- Prevention rule: Treat DB shape as a compatibility contract unless an explicit migration plan exists.
46	- References: `no_intro_main`, `tosec_main`, query paths in `Gromulus_Lib.py`.