feat(.ai): memory and session retro skill to self-document

- adds session-retrospective skill to capture lessons after work or user
corrections
- adds memory directory with initial testing lessons

Author: marissahuysentruyt

.ai/README.md

@@ -243,6 +243,13 @@ Skills are used on-demand. When a task matches a skill’s purpose, the agent re
 - Use when: Explaining how code works, teaching about the codebase, or when the user asks “how does this work?”
 - Approach: Analogy → diagram → step-by-step walkthrough → highlight gotchas
 
+#### Session retrospective
+
+- **purpose**: Document lessons learned after completing work, especially when the user corrected planning documents or implementation; maintains persistent lesson files in `.ai/memory/` that future agents read at session start
+- **How to invoke**: Say "document what you learned", "add to lessons", "remember this", or "run a retrospective". Also triggered when the user corrects your work or you encounter a surprising constraint.
+- Use when: User corrects your work, you hit a non-obvious tool limitation, or at session end after substantial work
+- Provides: Workflow for capturing lessons, format guidelines, naming convention (`<descriptor>-lessons.md` in `.ai/memory/`)
+
 #### Session handoff
 
 - **purpose**: Create handoff documents so another agent (or a later session) can continue work with full context

.ai/memory/agnostic-lessons.md

@@ -0,0 +1,48 @@
+# Lessons learned
+
+Accumulated lessons from working sessions on this project. Grouped by category. Update in place — do not append chronologically.
+
+---
+
+## File operations
+
+- **Edit tool requires a prior read**: The Edit tool fails with "file not read yet" if the file wasn't read in the current conversation, even if you wrote it in the same session. Read every file you plan to edit before starting work.
+- **Parallel edits can fail with "modified since read"**: When editing multiple files in the same batch, if one edit changes the file order or content, subsequent edits in the same pass may fail. Re-read the file and retry individually.
+
+---
+
+## Path resolution
+
+- **`2nd-gen/packages/swc/AGENTS.md` is 3 levels deep**: Relative paths from this file need `../../../` to reach the repo root — not `../../`. Wrong: `../../linters/foo.js`. Correct: `../../../linters/foo.js`.
+- **Symlink removal with `rm`**: `rm` on a symlink removes only the pointer, not the target directory or files. Safe to use when cleaning up a symlink.
+- **Git stores symlinks as text blobs**: Staged symlinks appear as the raw target path string in the index, not the resolved content. This is why Cursor shows "Apply Manually" on staged symlink files — it reads the index, not the filesystem.
+
+---
+
+## Project structure
+
+- **Root `package.json` has `"type": "module"`**: All `.js` scripts in this repo use ESM `import`/`export` syntax. Write new scripts with `import`, not `require`.
+- **`linters/` is at the repo root**: The `stylelint-property-order.js` and ESLint plugin live at `linters/`, not inside `2nd-gen/` or `1st-gen/`.
+- **`.ai/memory/` is the persistent lessons store**: Lessons and cross-session notes belong here, not in session-handoff documents or code comments.
+
+---
+
+## Component patterns
+
+- **`.internal.stories.ts` files don't need `migrated` tag**: Files named `*.internal.stories.ts` (e.g. `icon.internal.stories.ts`) are dev-only and are exempt from the `tags: ['migrated']` requirement on the meta object.
+- **`utility` is a valid meta tag**: The `typography` component uses `tags: ['migrated', 'utility']` on its meta — `utility` is a legitimate tag alongside `migrated`.
+
+---
+
+## Agent tooling
+
+- **Claude Code does not auto-discover `SKILL.md` files**: Skills must be explicitly loaded via `AGENTS.md` context or manual invocation. There is no automatic glob-based discovery.
+- **Per-file symlinks allow different extensions**: `.cursor/rules/*.mdc` can symlink to `.ai/rules/*.md` — this lets Cursor find its expected `.mdc` format while the canonical source stays as `.md`.
+- **Cursor reads the git index for staged symlinks**: At commit time Cursor sees the symlink path string, not the resolved content, so rules appear as "Apply Manually". At runtime on the filesystem, symlinks resolve correctly.
+
+---
+
+## CI / build
+
+- **`yarn lint:ai` runs the AI tooling validator**: `node .ai/scripts/validate.js` checks story tags, AGENTS.md paths, and config schema. Run it locally before pushing with `yarn lint:ai`.
+- **Validator found a real broken link on first run**: The `2nd-gen/packages/swc/AGENTS.md` path to `stylelint-property-order.js` was genuinely wrong — the CI check is worth running even on mature files.

.ai/memory/css-styling-lessons.md

@@ -0,0 +1,23 @@
+# CSS Styling Lessons
+
+## Component patterns
+
+**CSS selector syntax — class vs. attribute:** `:not([.swc-Badge--no-label])` uses attribute selector syntax on a class name and always evaluates false; the correct form is `:not(.swc-Badge--no-label)`. When writing negation or `:has()` selectors, use `.class` for BEM modifiers, never `[.class]`.
+
+**Check that every custom property is actually consumed:** Setting `--swc-badge-padding-inline-start` in a `:has()` rule is a silent no-op if the base rule uses `padding-inline` shorthand — the property is never read. Before flagging a missing override as a bug, trace the full consumption path from where the property is set to where it is used.
+
+**Prefer `padding-inline` shorthand when both edges share the same value:** Splitting into `padding-inline-start`/`padding-inline-end` forces every size override block to set two properties instead of one. Keep the shorthand and use a single override hook (`--swc-badge-padding-inline`) that size blocks can update in one line; asymmetric start-edge logic can override `--swc-badge-padding-inline-start` in the fallback chain.
+
+**Fallback chains can propagate size overrides without duplicating properties:** `padding-inline-start: calc(var(--swc-badge-padding-inline-start, var(--swc-badge-padding-inline, token(...))))` means size overrides only need to set `--swc-badge-padding-inline` and both edges stay in sync, while a `:has()` rule can still override the start edge independently via `--swc-badge-padding-inline-start`.
+
+**Fix proposals must account for all variant states:** A fix that adds a property to size override blocks may break the icon state if that same property is already being set to a different value by a `:has()` rule. Think through the full set of states (no icon, with icon, icon-only) before proposing a change.
+
+## CI / build
+
+**commitlint in this project enforces lowercase subjects:** The `subject-case` rule forbids sentence-case, start-case, pascal-case, and upper-case. Commit subjects must start with a lowercase letter — `fix(badge): correct fallbacks...` not `fix(badge): Correct fallbacks...`.
+
+**Stylelint/prettier rewrites files substantially after commits:** The linter hook may revert manual splits back to shorthands, change default scale tokens, or remove entire CSS patterns. Always re-read the file after a commit before writing memory or validation docs — the on-disk state may differ significantly from what was written.
+
+## File operations
+
+**Update memory/validation docs after linter runs:** If a linter rewrites a component CSS file, any memory files or validation docs written before the lint run may describe a state that no longer exists. Re-read the source file and correct the docs in the same session before context is lost.

.ai/skills/session-retrospective/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: session-retrospective
+description: Document lessons learned after completing work, especially when the user corrected planning documents or implementation. Creates and maintains a persistent lessons file in .ai/memory/ that future agents read at session start.
+---
+
+# Session retrospective
+
+## Mindset
+
+You are a continuous improvement engineer. Every correction the user makes is signal, not noise. Capture it while the context is fresh — a two-sentence lesson now prevents hours of repeated mistakes in every future session.
+
+## When to use
+
+**Triggered by:**
+
+- User corrects your work — wrong path, wrong assumption, wrong approach
+- User says "document what you learned", "add to lessons", or "remember this"
+- You encounter a tool limitation, surprising behavior, or non-obvious constraint
+- End of a session where substantial work was done and corrections were made
+
+**Proactively suggest** when the user corrects the same type of mistake more than once in a session.
+
+## When NOT to use
+
+- Trivial typo fixes with no future relevance
+- Corrections that are specific to a one-off task and won't recur
+- Preserving project state for continuing work — use `session-handoff` for that
+
+---
+
+## Workflow
+
+### 1. Identify what to capture
+
+For each correction or surprise, ask: **what would have prevented this mistake?**
+
+| What happened                   | What to document                                    |
+| ------------------------------- | --------------------------------------------------- |
+| Wrong file path                 | The correct path and why the wrong one seemed right |
+| Wrong tool usage                | The correct usage and the constraint                |
+| Misunderstood project structure | Where things actually live                          |
+| Tool limitation hit             | What the tool can't do and the workaround           |
+| Assumption that didn't hold     | The actual rule or constraint                       |
+
+Skip corrections that are one-offs or already obvious from the error message.
+
+### 2. Check existing lessons first
+
+Read `.ai/memory/lessons.md` before writing. Update an existing lesson if the new information adds nuance or corrects it. Never create a duplicate entry.
+
+### 3. Write to `.ai/memory/lessons.md`
+
+Group lessons by **category**, not by date. Categories:
+
+- **File operations** — tool behavior, read-before-edit, parallel edit failures
+- **Path resolution** — relative vs absolute, directory depth, symlinks
+- **Project structure** — where things actually live vs where they seem to be
+- **Tool limitations** — what tools can/can't do, workarounds
+- **CI / build** — what passes/fails, why, which scripts exist
+- **Component patterns** — SWC-specific conventions (tags, stories structure, etc.)
+- **Agent tooling** — `.ai/` rules, `AGENTS.md`, skills behavior, config
+
+Add new categories when none of the above fit.
+
+### 4. Format
+
+Each lesson is **one or two sentences**:
+
+1. **Bold subject** — the trigger condition or context
+2. Plain sentence — what to do (or not do)
+
+**Good:**
+
+> **Edit tool requires a prior read**: The Edit tool fails with "file not read yet" if the file wasn't read in the current conversation. Read all files you plan to edit before starting work.
+
+**Bad:**
+
+> We had an issue with editing files.
+
+Lessons should be actionable. A future agent reading them should know exactly what to do differently.
+
+### 5. Keep it scannable
+
+- Max 1–2 sentences per lesson
+- Update existing lessons rather than appending duplicates
+- If a lesson turns out to be wrong, remove or correct it — stale lessons cause the same problems they were meant to prevent
+- Keep the total file under ~100 lines; if it grows past that, consolidate or remove stale entries
+
+---
+
+## Output location
+
+**`.ai/memory/<descriptor>-lessons.md`** — co-located with agent tooling, readable by all agents regardless of tool. Use a descriptor that reflects the theme of the lessons (e.g. `agnostic-lessons.md` for tool-agnostic AI setup work, `migration-lessons.md` for migration-specific patterns). Create a new file when lessons belong to a clearly distinct topic rather than appending to an existing one.
+
+---
+
+## Checklist
+
+- [ ] Lessons are in `.ai/memory/<descriptor>-lessons.md`, not in a session-specific file
+- [ ] Each lesson is in the correct category
+- [ ] Each lesson is 1–2 sentences and actionable
+- [ ] No duplicates — existing entries were checked and updated if needed
+- [ ] Stale or incorrect lessons were removed or corrected
+
+---
+
+## Quality gate
+
+A retrospective is complete when:
+
+> Every significant correction from the session is captured as an actionable lesson in the correct category; no duplicates exist; lessons are scannable in under 60 seconds.