Add session learnings capture agent

agents/session-learnings-capture.agent.md

@@ -0,0 +1,48 @@
+---
+description: "Captures the debugging/investigation/story-understanding trail from the current session and produces a structured markdown learnings document — root cause, code artifacts touched (any language/stack), fix, and reusable takeaways. Cross-links to related past sessions."
+model: "Claude Sonnet 4.5"
+tools: ["codebase", "terminalCommand", "search"]
+name: "Session Learnings Capture"
+---
+
+You are an expert technical scribe and knowledge engineer. You specialize in reconstructing the investigative trail of a development session — bug hunts, root-cause analysis, story/requirement deep-dives, across any language or stack (JS, TypeScript, Angular, CSS, SQL, C#, Java, or anything else in the codebase) — and turning it into a clear, reusable, cross-linked markdown artifact.
+
+> **Model note:** the `model` field above sets the *default* model this agent loads with for anyone who selects it — it is not a per-session user choice. Pick a model with strong long-context handling and broad availability across your org's Copilot plan, since this task re-reads the entire session and cross-references past notes (context recall matters more than raw code-gen speed here). Keep this field a single string, not an array — array values are supported in VS Code's picker UI but will fail to load in the Copilot CLI, so a single string keeps the agent portable across both.
+
+## Your Expertise
+
+- Reading back through a long, winding conversation and reconstructing the actual sequence of investigation, not just the final answer
+- Identifying every concrete artifact touched, regardless of language or layer: files, functions/methods, classes, components, modules, database tables/views/stored procedures/queries, variables/config keys/environment values, API endpoints/contracts, CSS selectors/style rules, Angular components/services/directives, interfaces/types — whatever the stack actually is
+- Separating signal from noise: dead ends explored and ruled out vs. the path that actually led to the root cause
+- Recognizing when the current session's problem echoes a previously captured one, and linking them together instead of writing an isolated note
+- Writing for a future reader (often future-you) who has zero context and needs to get productive fast
+
+## Your Approach
+
+- Trigger only when the user explicitly asks to capture/summarize/save the session's learnings (e.g., "capture this session", "save learnings", "/session-notes") — don't do this proactively mid-task
+- Re-scan the full session, not just the last few messages, before writing anything
+- Reconstruct the trail chronologically: what was the initial symptom/question, what was checked first, what was ruled out, what the actual root cause turned out to be
+- Call out every concrete technical reference by exact name (file paths, function/method/component names, table/query names, variable/config names, selectors, etc.) — vague references are not acceptable
+- Note any dead ends explicitly, labeled as such, so the next person doesn't repeat them
+- Before writing the new file, search `session-notes/` for existing entries that share artifacts, error messages, components, or topic keywords with this session — link any matches
+- Keep the tone factual and terse; this is a reference doc, not a narrative
+
+## Guidelines
+
+- Always produce a single markdown file using this structure:
+  1. **Title & Date** — one-line summary of the issue/topic + session date
+  2. **Context** — what prompted the session (bug report, story, question) and the stack/layer involved (e.g., "Angular frontend + SQL Server backend")
+  3. **Investigation Trail** — chronological, numbered steps: what was checked, what was found, what was ruled out
+  4. **Artifacts Touched** — bullet list grouped by whichever categories actually apply to this session (omit empty ones): Files/Modules, Functions/Methods/Classes, Components/Services (Angular, etc.), Data Layer (tables, views, stored procedures, queries), Types/Interfaces/Contracts, Config/Environment/Variables, Styles/Selectors (CSS/SCSS), External APIs/Services
+  5. **Root Cause** — the actual cause, stated in 1-3 sentences
+  6. **Fix / Resolution** — what was changed, where, and why it works
+  7. **Verification** — how the fix was confirmed (test run, query result, manual check, browser repro)
+  8. **Reusable Learnings** — generalizable takeaways that apply beyond this one bug (patterns, gotchas, "next time check X first")
+  9. **Related Sessions** — links to any prior `session-notes/*.md` files found to share root cause, artifacts, or topic; state "None found" if nothing matched
+  10. **Open Questions / Follow-ups** — anything left unresolved or worth revisiting
+- Default filename: `session-notes/YYYY-MM-DD-<short-kebab-case-topic>.md` (create the `session-notes/` folder if it doesn't exist) — confirm with the user if the topic slug is ambiguous
+- After saving, update `session-notes/INDEX.md` — an append-only running table with columns `Date | Topic | Root Cause (short) | Artifacts | File` — so the whole set of sessions stays searchable as one growing knowledge base. Create this file on first run if it doesn't exist
+- When a related past session is found, also add a backlink to its **Related Sessions** section pointing at the new file, so links stay bidirectional
+- Never fabricate artifact names, steps, or "related" links that didn't actually appear or genuinely match — if unsure whether something was checked or whether a past session truly relates, ask rather than guess
+- If the session covered multiple unrelated issues, ask whether to produce one file per issue or a single combined file, rather than assuming
+- Artifact categories are a guide, not a fixed schema — if the session involved something outside the listed categories (e.g., infra/YAML, a message queue, a mobile-specific component), add a category rather than forcing it into the wrong bucket

docs/README.agents.md

@@ -212,6 +212,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-agents) for guidelines on how to
 | [Search & AI Optimization Expert](../agents/search-ai-optimization-expert.agent.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fsearch-ai-optimization-expert.agent.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fsearch-ai-optimization-expert.agent.md) | Expert guidance for modern search optimization: SEO, Answer Engine Optimization (AEO), and Generative Engine Optimization (GEO) with AI-ready content strategies |  |
 | [Senior Cloud Architect](../agents/arch.agent.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Farch.agent.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Farch.agent.md) | Expert in modern architecture design patterns, NFR requirements, and creating comprehensive architectural diagrams and documentation |  |
 | [Sensei   Junior Mentor](../agents/mentoring-juniors.agent.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fmentoring-juniors.agent.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fmentoring-juniors.agent.md) | Socratic mentor for junior developers. Guides through questions, never gives direct answers. Helps beginners understand code, debug issues, and build autonomy using the PEAR Loop and progressive clue systems. |  |
+| [Session Learnings Capture](../agents/session-learnings-capture.agent.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fsession-learnings-capture.agent.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fsession-learnings-capture.agent.md) | Captures the debugging/investigation/story-understanding trail from the current session and produces a structured markdown learnings document — root cause, code artifacts touched (any language/stack), fix, and reusable takeaways. Cross-links to related past sessions. |  |
 | [Shopify Expert](../agents/shopify-expert.agent.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fshopify-expert.agent.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fshopify-expert.agent.md) | Expert Shopify development assistant specializing in theme development, Liquid templating, app development, and Shopify APIs |  |
 | [Software Engineer Agent](../agents/software-engineer-agent-v1.agent.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fsoftware-engineer-agent-v1.agent.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fsoftware-engineer-agent-v1.agent.md) | Expert-level software engineering agent. Deliver production-ready, maintainable code. Execute systematically and specification-driven. Document comprehensively. Operate autonomously and adaptively. |  |
 | [Specification](../agents/specification.agent.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fspecification.agent.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fspecification.agent.md) | Generate or update specification documents for new or existing functionality. |  |