1# Entry Examples
2 
3Concrete examples of well-formatted entries with all fields.
4 
5## Learning: Correction
6 
7```markdown
8## [LRN-20250115-001] correction
9 
10**Logged**: 2025-01-15T10:30:00Z
11**Priority**: high
12**Status**: pending
13**Area**: tests
14 
15### Summary
16Incorrectly assumed pytest fixtures are scoped to function by default
17 
18### Details
19When writing test fixtures, I assumed all fixtures were function-scoped. 
20User corrected that while function scope is the default, the codebase 
21convention uses module-scoped fixtures for database connections to 
22improve test performance.
23 
24### Suggested Action
25When creating fixtures that involve expensive setup (DB, network), 
26check existing fixtures for scope patterns before defaulting to function scope.
27 
28### Metadata
29- Source: user_feedback
30- Related Files: tests/conftest.py
31- Tags: pytest, testing, fixtures
32 
33---
34```
35 
36## Learning: Knowledge Gap (Resolved)
37 
38```markdown
39## [LRN-20250115-002] knowledge_gap
40 
41**Logged**: 2025-01-15T14:22:00Z
42**Priority**: medium
43**Status**: resolved
44**Area**: config
45 
46### Summary
47Project uses pnpm not npm for package management
48 
49### Details
50Attempted to run `npm install` but project uses pnpm workspaces.
51Lock file is `pnpm-lock.yaml`, not `package-lock.json`.
52 
53### Suggested Action
54Check for `pnpm-lock.yaml` or `pnpm-workspace.yaml` before assuming npm.
55Use `pnpm install` for this project.
56 
57### Metadata
58- Source: error
59- Related Files: pnpm-lock.yaml, pnpm-workspace.yaml
60- Tags: package-manager, pnpm, setup
61 
62### Resolution
63- **Resolved**: 2025-01-15T14:30:00Z
64- **Commit/PR**: N/A - knowledge update
65- **Notes**: Added to CLAUDE.md for future reference
66 
67---
68```
69 
70## Learning: Promoted to CLAUDE.md
71 
72```markdown
73## [LRN-20250115-003] best_practice
74 
75**Logged**: 2025-01-15T16:00:00Z
76**Priority**: high
77**Status**: promoted
78**Promoted**: CLAUDE.md
79**Area**: backend
80 
81### Summary
82API responses must include correlation ID from request headers
83 
84### Details
85All API responses should echo back the X-Correlation-ID header from 
86the request. This is required for distributed tracing. Responses 
87without this header break the observability pipeline.
88 
89### Suggested Action
90Always include correlation ID passthrough in API handlers.
91 
92### Metadata
93- Source: user_feedback
94- Related Files: src/middleware/correlation.ts
95- Tags: api, observability, tracing
96 
97---
98```
99 
100## Learning: Promoted to AGENTS.md
101 
102```markdown
103## [LRN-20250116-001] best_practice
104 
105**Logged**: 2025-01-16T09:00:00Z
106**Priority**: high
107**Status**: promoted
108**Promoted**: AGENTS.md
109**Area**: backend
110 
111### Summary
112Must regenerate API client after OpenAPI spec changes
113 
114### Details
115When modifying API endpoints, the TypeScript client must be regenerated.
116Forgetting this causes type mismatches that only appear at runtime.
117The generate script also runs validation.
118 
119### Suggested Action
120Add to agent workflow: after any API changes, run `pnpm run generate:api`.
121 
122### Metadata
123- Source: error
124- Related Files: openapi.yaml, src/client/api.ts
125- Tags: api, codegen, typescript
126 
127---
128```
129 
130## Error Entry
131 
132```markdown
133## [ERR-20250115-A3F] docker_build
134 
135**Logged**: 2025-01-15T09:15:00Z
136**Priority**: high
137**Status**: pending
138**Area**: infra
139 
140### Summary
141Docker build fails on M1 Mac due to platform mismatch
142 
143### Error
144```
145error: failed to solve: python:3.11-slim: no match for platform linux/arm64
146```
147 
148### Context
149- Command: `docker build -t myapp .`
150- Dockerfile uses `FROM python:3.11-slim`
151- Running on Apple Silicon (M1/M2)
152 
153### Suggested Fix
154Add platform flag: `docker build --platform linux/amd64 -t myapp .`
155Or update Dockerfile: `FROM --platform=linux/amd64 python:3.11-slim`
156 
157### Metadata
158- Reproducible: yes
159- Related Files: Dockerfile
160 
161---
162```
163 
164## Error Entry: Recurring Issue
165 
166```markdown
167## [ERR-20250120-B2C] api_timeout
168 
169**Logged**: 2025-01-20T11:30:00Z
170**Priority**: critical
171**Status**: pending
172**Area**: backend
173 
174### Summary
175Third-party API timeout during request processing
176 
177### Error
178```
179TimeoutError: Request to api.example.com timed out after 30000ms
180```
181 
182### Context
183- Command: POST /api/process
184- Timeout set to 30s
185- Occurs during peak hours (lunch, evening)
186 
187### Suggested Fix
188Implement retry with exponential backoff. Consider circuit breaker pattern.
189 
190### Metadata
191- Reproducible: yes (during peak hours)
192- Related Files: src/services/api-client.ts
193- See Also: ERR-20250115-X1Y, ERR-20250118-Z3W
194 
195---
196```
197 
198## Feature Request
199 
200```markdown
201## [FEAT-20250115-001] export_to_csv
202 
203**Logged**: 2025-01-15T16:45:00Z
204**Priority**: medium
205**Status**: pending
206**Area**: backend
207 
208### Requested Capability
209Export analysis results to CSV format
210 
211### User Context
212User runs weekly reports and needs to share results with non-technical 
213stakeholders in Excel. Currently copies output manually.
214 
215### Complexity Estimate
216simple
217 
218### Suggested Implementation
219Add `--output csv` flag to the analyze command. Use standard csv module.
220Could extend existing `--output json` pattern.
221 
222### Metadata
223- Frequency: recurring
224- Related Features: analyze command, json output
225 
226---
227```
228 
229## Feature Request: Resolved
230 
231```markdown
232## [FEAT-20250110-002] dark_mode
233 
234**Logged**: 2025-01-10T14:00:00Z
235**Priority**: low
236**Status**: resolved
237**Area**: frontend
238 
239### Requested Capability
240Dark mode support for the dashboard
241 
242### User Context
243User works late hours and finds the bright interface straining.
244Several other users have mentioned this informally.
245 
246### Complexity Estimate
247medium
248 
249### Suggested Implementation
250Use CSS variables for colors. Add toggle in user settings.
251Consider system preference detection.
252 
253### Metadata
254- Frequency: recurring
255- Related Features: user settings, theme system
256 
257### Resolution
258- **Resolved**: 2025-01-18T16:00:00Z
259- **Commit/PR**: #142
260- **Notes**: Implemented with system preference detection and manual toggle
261 
262---
263```
264 
265## Learning: Promoted to Skill
266 
267```markdown
268## [LRN-20250118-001] best_practice
269 
270**Logged**: 2025-01-18T11:00:00Z
271**Priority**: high
272**Status**: promoted_to_skill
273**Skill-Path**: skills/docker-m1-fixes
274**Area**: infra
275 
276### Summary
277Docker build fails on Apple Silicon due to platform mismatch
278 
279### Details
280When building Docker images on M1/M2 Macs, the build fails because
281the base image doesn't have an ARM64 variant. This is a common issue
282that affects many developers.
283 
284### Suggested Action
285Add `--platform linux/amd64` to docker build command, or use
286`FROM --platform=linux/amd64` in Dockerfile.
287 
288### Metadata
289- Source: error
290- Related Files: Dockerfile
291- Tags: docker, arm64, m1, apple-silicon
292- See Also: ERR-20250115-A3F, ERR-20250117-B2D
293 
294---
295```
296 
297## Extracted Skill Example
298 
299When the above learning is extracted as a skill, it becomes:
300 
301**File**: `skills/docker-m1-fixes/SKILL.md`
302 
303```markdown
304---
305name: docker-m1-fixes
306description: "Fixes Docker build failures on Apple Silicon (M1/M2). Use when docker build fails with platform mismatch errors."
307---
308 
309# Docker M1 Fixes
310 
311Solutions for Docker build issues on Apple Silicon Macs.
312 
313## Quick Reference
314 
315| Error | Fix |
316|-------|-----|
317| `no match for platform linux/arm64` | Add `--platform linux/amd64` to build |
318| Image runs but crashes | Use emulation or find ARM-compatible base |
319 
320## The Problem
321 
322Many Docker base images don't have ARM64 variants. When building on
323Apple Silicon (M1/M2/M3), Docker attempts to pull ARM64 images by
324default, causing platform mismatch errors.
325 
326## Solutions
327 
328### Option 1: Build Flag (Recommended)
329 
330Add platform flag to your build command:
331 
332\`\`\`bash
333docker build --platform linux/amd64 -t myapp .
334\`\`\`
335 
336### Option 2: Dockerfile Modification
337 
338Specify platform in the FROM instruction:
339 
340\`\`\`dockerfile
341FROM --platform=linux/amd64 python:3.11-slim
342\`\`\`
343 
344### Option 3: Docker Compose
345 
346Add platform to your service:
347 
348\`\`\`yaml
349services:
350  app:
351    platform: linux/amd64
352    build: .
353\`\`\`
354 
355## Trade-offs
356 
357| Approach | Pros | Cons |
358|----------|------|------|
359| Build flag | No file changes | Must remember flag |
360| Dockerfile | Explicit, versioned | Affects all builds |
361| Compose | Convenient for dev | Requires compose |
362 
363## Performance Note
364 
365Running AMD64 images on ARM64 uses Rosetta 2 emulation. This works
366for development but may be slower. For production, find ARM-native
367alternatives when possible.
368 
369## Source
370 
371- Learning ID: LRN-20250118-001
372- Category: best_practice
373- Extraction Date: 2025-01-18
374```
375