Defame1297
b55eede1ef
Add LESSONS.md as the long-loop feedback log at repo root. Patterns observed during development graduate to standing rules when three or more entries appear. Introduce docs/spec/ as the living spec layer: overview.md (deployed state) and architecture.md (directory structure, install pipeline, provider model, governance layer). Refactor docs/VISION.md to goals and intent only — architecture content moved to docs/spec/architecture.md. Update CLAUDE.md and CONTEXT.md to reference the new spec files. Close issues 0013 and 0014. Update ROADMAP and factory integration note to reflect completion. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
33 lines
1.7 KiB
Markdown
33 lines
1.7 KiB
Markdown
# 0013 — LESSONS.md for this repo ✅
|
|
|
|
## What to build
|
|
|
|
Create `LESSONS.md` at the repo root. This file is the long-loop feedback mechanism for this repo — patterns noticed during active development get written here, and repeated patterns graduate to standing rules.
|
|
|
|
**File structure:**
|
|
|
|
```markdown
|
|
# Lessons
|
|
|
|
Patterns observed during development of this repo. Three or more entries on the same pattern → promote to CONTEXT.md (or the relevant instruction file) as a standing rule.
|
|
|
|
## [date] [short title]
|
|
[observation — what happened, what was learned, what should change]
|
|
```
|
|
|
|
**Graduation rule:** When three or more entries cover the same pattern, the human reviews and promotes the pattern to the appropriate standing location: CONTEXT.md for domain-level principles, `core/instructions/coding.md` for coding conventions, `core/instructions/git.md` for git conventions, or `core/instructions/testing.md` for testing conventions. The graduated entries are marked `[graduated → target file]` rather than deleted (audit trail).
|
|
|
|
**Who writes to it:** The session-handoff skill (Chunk 3) prompts LESSONS.md extraction before closing a session. The human may also write directly.
|
|
|
|
**What belongs here:** Non-obvious observations — a rule that was misapplied, a pattern that caused friction, a decision that turned out wrong in practice. Not summaries of what was built (that's git history) or planned changes (that's issues).
|
|
|
|
## Acceptance criteria
|
|
|
|
- [ ] `LESSONS.md` exists at repo root with the structure above
|
|
- [ ] Graduation rule is documented in the file header
|
|
- [ ] CONTEXT.md docs convention is updated to reference LESSONS.md as an artifact type
|
|
|
|
## Blocked by
|
|
|
|
None.
|