docs: factory integration grill — decision record, ADRs, and chunk scope update
- Decision record covering 12 decisions from the factory integration grill - ADR-0008 (factory boundary: this repo is a provider, not a factory instance) - ADR-0009 (flat skill taxonomy with category metadata in frontmatter) - ADR-0010 (role skills in .agents/skills/; core/agents/ for subagent definitions) - Issue 0013 (LESSONS.md at repo root) - Issue 0014 (docs/spec/ living spec layer + VISION.md refactor) - ROADMAP Chunk 3 scope expanded: skills rebuild, new skills (session-handoff, governance-check, git-guardrails, write-adr), IaC/Gitea global optional - Per-skill process: implementation guidance Sections 4-5 and skills index referenced as starting point before web research and grilling - factory-research-gaps-conflicts.md marked superseded Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
32
docs/issues/0013-lessons-md.md
Normal file
32
docs/issues/0013-lessons-md.md
Normal file
@@ -0,0 +1,32 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user