retrospective

name: retrospective description: Post-task "lessons learned" review. Evaluates what worked, what didn't, and proposes updates to instruction and skill files to continuously improve AI-assisted development workflows. argument-hint: 'optional task summary'

Retrospective — Continuous Improvement of Instructions & Skills

After completing a significant task (feature, bugfix, refactor, investigation), run this retrospective to capture lessons learned and improve the knowledge base for future tasks.

When to trigger: After any task that involved non-trivial problem-solving, debugging, or where the agent had to course-correct. Skip the retrospective only when all of these apply: the change touched a single file, was a single logical edit (typo, comment, formatting, or a one-line code change), required no debugging, introduced no new convention, and the agent never needed to course-correct.

Step 1: Reflect on the Task

Review the conversation and task execution. Answer these questions:

Step 2: Classify the Lesson

Quick routing summary

Use this table first. If the lesson clearly matches one row, skip straight to the listed substep. Use the detailed substeps (2a–2e) only when the answer is not obvious.

Then walk through the substeps below in order to confirm the routing and pick the exact target file.

2a. Should we fix this instead of documenting it?

If a lesson boils down to "this is unnecessarily hard/confusing," consider whether the root cause can be eliminated. Ask:

• Is this complexity essential, or is it an accident of the current design?
• Would a rename, a better default, or a small refactor make the lesson unnecessary?
• Would a future contributor hit the same wall?

If the answer is "we can fix it" → create a GitHub issue instead of (or in addition to) documenting the workaround. Tag it with the relevant area (grid, plugins, docs, dx). A library should be bulletproof and easy to use — documenting sharp edges is a fallback, not the goal.

2b. Does this belong in the code itself?

The most discoverable place for knowledge is right where someone will be reading or editing. Prefer inline placement when the lesson is tied to a specific function, type, or code block:

Rule of thumb by file type:

If someone would need to leave the file to understand the code, the comment is missing. If the information is useful to consumers (not just maintainers), make it JSDoc.

2c. Does this update the mental model (knowledge files)?

Before routing to instructions or skills, ask: "Is this about how the system works (descriptive) rather than how to work in the system (prescriptive)?"

Route to .github/knowledge/ if the lesson describes:

• How subsystems connect or communicate (data flow, state ownership)
• Why something is designed the way it is (design rationale, trade-offs)
• An invariant that must hold (and would save debugging time if known)
• A known tension or pressure point between subsystems
• An end-to-end operation trace (what happens when X occurs)

Use the structured notation when adding to knowledge files:

• OWNS: — state or responsibility the subsystem holds
• READS FROM: / WRITES TO: — data flow edges
• INVARIANT: — things that must always be true
• FLOW: — operation sequences (use indented pseudocode)
• TENSION: — trade-offs and pressure points
• DECIDED: — design choices with rationale

2d. Route to the right instruction or skill file

For lessons that are cross-cutting (span multiple files, not tied to one code location) or procedural:

Before choosing a target, scan the full list of instruction files in .github/instructions/, knowledge files in .github/knowledge/, and skill files in .github/skills/. The right home is whichever file a future agent would have loaded when it needed the lesson. Grid-pitfalls is appropriate only for gotchas specific to the grid's DOM/render behavior — most lessons belong elsewhere.

2e. New file or update existing?

• Update existing if the lesson fits an existing instruction, knowledge, or skill topic
• Create new instruction file if there's no home for it AND it applies to a specific file glob pattern
• Create new knowledge file if it describes a new subsystem or domain not yet covered
• Create new skill only if it's a multi-step workflow that will be repeated
• Skip if the lesson is too niche or one-off to be useful again

Step 3: Draft the Update

For instruction files (.instructions.md)

Instruction files are always loaded when working on matching files. Keep them:

• Concise — bullet points, not paragraphs
• Actionable — "Do X" not "X is a thing"
• Correct — verify the advice actually works before writing it down

Format:

---
applyTo: '<glob-pattern>'
---

# Title

- **Rule name**: Brief actionable rule
- **Rule name**: Brief actionable rule

For skill files (SKILL.md)

Skills are loaded on demand and can be longer. They should contain:

• Step-by-step workflows
• Code templates and scaffolding
• Reference tables
• Verification criteria

Skill-private scripts — keep the skill self-contained:

• If a script is used only by one skill (not by Nx, CI, Vite, or the build), place it inside the skill folder (e.g. .github/skills/<name>/analyze-trace.mjs) and reference it by that path. The skill carries everything it needs; no hunting for a script that lives elsewhere or has been gitignored.
• If a script is shared infrastructure — invoked by CI, an Nx target, Vite, or the build — it stays in tools/ (or libs/*/scripts/) and the skill references it. Do NOT copy it into the skill folder; a second copy will drift. Example: tools/build-size-report.ts is run by ci.yml, so bundle-check/release-prep reference it rather than vendoring it.
• Prefer zero-dependency Node/Bun scripts for skill-private tooling so the skill works on a fresh checkout without extra installs.

Format:

---
name: skill-name
description: One-line description for matching against user requests.
argument-hint: <required-arg> [optional-arg]
---

# Title

## Step 1: ...

## Step 2: ...

For the main copilot-instructions.md

Only update this file for:

• Changes to the project overview or monorepo structure
• New instruction files, knowledge files, or skills being added (update the reference tables)
• New external dependencies or version bumps
• Changes to core constraints (bundle budget, etc.)

Keep it as a navigation hub, not a knowledge dump.

Step 4: Evaluate Context Window Impact

Before adding content, consider the cost:

Rules of thumb:

• If a rule applies to specific files → instruction file (auto-applied)
• If it's a procedure → skill file (loaded on demand)
• If it describes how the system works → knowledge file (loaded at task start)
• If it's project-level orientation → main file (always loaded)
• When in doubt, prefer instruction file over main file

Step 5: Apply and Verify

1. Make the edit to the appropriate file(s)
2. Update reference tables in copilot-instructions.md if you added/renamed files
3. Verify consistency — does the new content contradict anything existing?
4. Remove outdated content — if the lesson replaces old advice, delete the old advice
5. No duplication — each piece of information lives in exactly one place. If it's in a knowledge file, do not also add it to pitfalls/instructions. If moving information from one file to another, delete it from the source.

Step 5b: Condense pass on touched knowledge files (MANDATORY)

If you wrote to any .github/knowledge/*.md file in this task — including a tiny one-bullet append — you MUST do a condense pass before finishing. Skipping this step is what causes knowledge files to drift into changelog prose and lose their value as agent memory. The "I just added one line" case is exactly when drift happens, because nobody re-reads the surrounding context.

For each knowledge file you touched, re-read the whole file end-to-end and apply the style rules from copilot-instructions.md → "Knowledge file style — keep them dense or they stop working". Concretely:

1. Re-read the entire file (not just the section you edited). You cannot spot drift by looking at the diff.
2. Fold, don't stack. If your new entry restates or extends an existing DECIDED / INVARIANT / TENSION, rewrite that entry in place. Do not leave both the old and new versions side by side.
3. Strip prose. Kill adjectives, transitions, "we will…", narrative tone, and explanations of obvious mechanics. Keep proper nouns (file paths, function/class names, PR/issue numbers, MUST/MUST NOT rules) — they are the navigation targets.
4. Collapse enumerations into tables. Any list of ≥4 parallel items (plugins, features, hooks, bindings, options) belongs in a markdown table, not stacked bullets.
5. Delete dead history. "We tried X, then Y, then Z" is git's job. Keep the conclusion; drop the path that got there. Exception: a single "RULED OUT:" line for alternatives that look obvious but don't work.
6. Check the size budget. Run wc -l .github/knowledge/<file>.md. Soft cap: ≤200 lines. Hard cap: 250 lines.
   • If you're still under 200 after condensing → done.
   • If 200–250 → condense harder before finishing.
   • If >250 or condensing isn't enough → evaluate a split (Step 5c).
7. Sanity-scan headings. Each ## name heading should still have at least one of OWNS: / READS FROM: / WRITES TO: / INVARIANT: / FLOW: / TENSION: / DECIDED:. If a heading has degenerated into a prose dump with no structured markers, restructure it.

End-state check: ask yourself, "If I started a new session tomorrow and loaded only this file, could I rebuild the mental model of this domain in under a minute?" If no, condense more.

Step 5c: Evaluate splitting (when a file outgrows its domain)

A knowledge file should cover one mental model. Split when any of these are true:

• File is >250 lines after a serious condense pass.
• The file has grown to cover two clearly separable subdomains (e.g. adapters.md describing React, Vue, and Angular bridging in detail).
• A future agent loading the file for question X would have to skip past >50% of the file that is irrelevant to X.
• Two top-level sections share almost no related: cross-references with each other.

How to split:

1. Identify the seam. Pick the natural boundary (per-framework, per-subsystem, per-lifecycle-phase). Avoid splits that force readers to load both files together for every task.
2. Create the new file with the same frontmatter schema. Add related: [original-file, ...] to both sides.
3. Move, don't copy. Cut the section from the original; paste into the new file. Update any cross-references in other knowledge / instruction / skill files.
4. Update copilot-instructions.md → Knowledge Reference table with the new file and a one-line domain description.
5. Re-run the condense pass (Step 5b) on both halves — splits often expose redundancy that was hidden when the content was interleaved.

If you can't justify a split cleanly, condense harder instead. Splitting prematurely fragments the mental model and forces multi-file loads for single questions.

Step 6: Summarize for the User

Present the retrospective findings as a brief report:

### Retrospective: [Task Name]

**Lessons captured:**
- ✅ Updated `<file>`: <what changed>
- ✅ Created `<file>`: <why>
- ⏭️ Skipped: <lesson that wasn't worth documenting and why>

**Knowledge condense pass:** (only if Step 5b ran)
- `<knowledge-file>`: <lines before> → <lines after>, <split? yes/no, why>

**No updates needed** (if nothing was worth capturing)

Anti-Patterns

• Don't document what you can fix — If the gotcha exists because of accidental complexity, file an issue to fix it. A workaround comment is a last resort, not a first instinct
• Don't hide code-specific knowledge in instruction files — If a lesson is tied to a specific function or type, put it in a comment or JSDoc at that location. Instruction files are for cross-cutting concerns
• Don't default to grid-pitfalls — Pitfalls is just one target. Most lessons belong in architecture, API, testing, CSS, TypeScript conventions, or workflow instructions. Ask "where would a future agent need this?" and route accordingly
• Don't document one-off quirks that will never recur
• Don't bloat the main file — always ask "can this live in an instruction or skill instead?"
• Don't duplicate — if the advice exists elsewhere, add a cross-reference, not a copy
• Don't speculate — only document things that were actually verified during the task
• Don't create a skill for a single-step action — that's just an instruction bullet point
• Don't skip the condense pass — every knowledge-file write, no matter how small, triggers Step 5b. Drift compounds silently; one un-condensed append turns into ten
• Don't split prematurely — a 180-line cohesive knowledge file is better than two 90-line files that always load together. Split only at a real seam (see Step 5c)