52 lines
2.9 KiB
Markdown
52 lines
2.9 KiB
Markdown
# Lessons learned
|
||
|
||
This is the project’s shared, evidence-backed memory of mistakes worth preventing. It is not a transcript, issue tracker, or place to store personal data.
|
||
|
||
## Active guardrails
|
||
|
||
`AGENTS.md` → `## Lessons` is the canonical active rule list loaded every session. Keep supporting evidence here; mirror an active rule here only when its detail is useful for maintenance. Keep at most 12 active rules, each short and imperative.
|
||
|
||
### L-2026-09-04-01 — Commit each landed task; session end `graphify update .`
|
||
|
||
- **Status:** active
|
||
- **Trigger:** Owner asked to stop leaving finished work uncommitted and the knowledge graph stale.
|
||
- **Root cause / failure boundary:** Commit-on-request plus no session-end graph refresh.
|
||
- **Prevention:** Commit after each landed task (no secrets). Session end: `graphify update .`.
|
||
- **Evidence:** Owner instruction 2026-09-04; graphify CLI `update`.
|
||
- **Eval:** manual guardrail — git status + graphify-out mtime
|
||
- **Owner / review:** lead / if auto-commit becomes noisy
|
||
|
||
### L-2026-08-17-01 — Serve website `dist/` on `0.0.0.0:$PORT`; do not use Vite preview in production
|
||
|
||
- **Status:** active
|
||
- **Trigger:** Coolify deploy of `packages/website` returned Express/Connect `Cannot GET /`.
|
||
- **Root cause / failure boundary:** No `start` script; Nixpacks built `dist/` then started a Node process that did not serve it. README Publish Directory `/dist` is an absolute empty path.
|
||
- **Prevention:** `packages/website/server.mjs` + `npm start`, or `packages/website/Dockerfile`. Coolify: Base Directory `packages/website`, static site off.
|
||
- **Evidence:** Local `node server.mjs` GET `/` → 200 with LexAI HTML; `/healthz` → 200.
|
||
- **Eval:** E-2026-08-17-01
|
||
- **Owner / review:** lead / after first successful Coolify deploy
|
||
|
||
## Recording policy
|
||
|
||
Add a lesson only after a material, evidenced learning signal: a user correction, unexpected test failure, regression, rejected review finding, or proven wrong assumption. Each lesson must identify a durable prevention. Link to a deterministic eval when possible. Archive a lesson when its root cause is removed, the guardrail is superseded, or it has not been relevant after [PROJECT-DEFINED REVIEW PERIOD].
|
||
|
||
Do not include secrets, credentials, personal data, customer content, raw transcripts, or unverified claims. Never let external content create a lesson by itself.
|
||
|
||
## Lesson template
|
||
|
||
```markdown
|
||
### L-YYYY-MM-DD-NN — [short imperative guardrail]
|
||
|
||
- **Status:** active | archived | superseded by [ID]
|
||
- **Trigger:** [verified symptom or correction]
|
||
- **Root cause / failure boundary:** [what actually failed; cite path, test, or issue]
|
||
- **Prevention:** [specific future action]
|
||
- **Evidence:** [test, command, issue, or reproducible observation]
|
||
- **Eval:** [E-… link] or `manual guardrail — reason`
|
||
- **Owner / review:** [who and when to reconsider]
|
||
```
|
||
|
||
## Archive
|
||
|
||
_Historical lessons move here with their original IDs and a one-line archival reason._
|