diff --git a/agents/session-learnings-capture.agent.md b/agents/session-learnings-capture.agent.md new file mode 100644 index 0000000000..7ef2b5a8f0 --- /dev/null +++ b/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-.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 diff --git a/docs/README.agents.md b/docs/README.agents.md index 608834918f..94ed1da337 100644 --- a/docs/README.agents.md +++ b/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)
[![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)
[![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)
[![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)
[![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)
[![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)
[![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)
[![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)
[![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)
[![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)
[![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)
[![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)
[![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)
[![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)
[![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. | |