Project Teacher
Generate a detailed explanation of the current project or task, focusing on the "why" and "how" to help the user learn.
Usage
When triggered, generate a markdown file containing the learning resource.
1. Check for Existing Documents (Synchronization)
Before generating a new file, search the output directory (default: learning/) for existing documents related to the current project.
- If a match is found: Ask the user: *"I found an existing learning doc '[Filename]'. Do you want to update it or create a new snapshot?"*
- If User chooses Update:
1. Rename: Updates the suffix date to today's date (e.g., API_Layout - 2024-03-25.md) to reflect freshness. 2. Metadata: Update the last and commit fields in the frontmatter. 3. Content: Rewrite sections that are outdated, but preserve valuable historical context if it still applies. 4. Log: Add a line to a ## Version history section at the bottom (create one if missing).
- If User chooses New / No match found: Create a new file.
2. Output Location
- Check for user preference: If the user specified a location (e.g., "save to my vault"), use that.
- Obsidian / External Vaults: If saving to an external Obsidian vault, first check its root or .cursor/ / .claude/ folders for applicable context files. These files often contain specific instructions for how to save and format notes in that system. Delegate to those instructions if they exist.
- Default Location: If no location is specified, use a directory named
learning/in the project root.
- Create the learning/ directory if it doesn't exist. - CRITICAL: Check if learning/ is in .gitignore. If not, add it to .gitignore to ensure these personal documents are not committed to shared repositories.
- File Naming: Name the file
[Descriptive title] - [YYYY-MM-DD].md.
- Structure: [Topic or Component] - [Date].md. The leading part should be semantic and descriptive of *what* is being explained. - Examples: - Authentication system walkthrough - 2024-03-25.md - Recipe parser logic - 2024-03-25.md - Project Teacher overview - 2024-03-25.md
3. File Structure & Metadata Header
Use YAML frontmatter for machine-readable status, and a callout for human context.
---
last: [YYYY-MM-DD]
commit: [Current Git Commit Hash or "N/A"]
tags: [project-teacher, learning, ...]
---
# [Descriptive title in sentence case]
> [!NOTE]
> **Context**: [Brief description, e.g., "Updated after migration to v2"]
> _This document reflects the system state at the time of the last update._
## Code index
* [MainController.ts](path/to/MainController.ts) - Handles the core logic for...
* [UserAuth.ts](path/to/UserAuth.ts) - Manages session state.
* [api/endpoints/](path/to/api/endpoints/) - API route definitions.
## 1. Project overview
[Explain the whole project in plain language as an expert tutor. What did we just build?]
## 2. Architecture and logic
[Use ASCII diagrams or Mermaid charts here to visualize how data flows or how components interact.]
## 3. Key technical decisions
[Explain "why" technical decisions were made.]
### Trade-offs and alternatives
[Explicitly mention what alternatives were considered and why they were rejected. e.g., "Considered using Redux, but opted for React Context because..."]
---
## Version history
* **[YYYY-MM-DD]**: [Brief note on what changed, e.g. "Initial creation"]
* **[YYYY-MM-DD]**: [e.g. "Updated diagram to reflect new caching layer"]
## Reflection questions
* [Question 1 asking about a specific architectural choice]
* [Question 2 asking about a potential edge case]
* [Question 3 challenging the user to explain a complex part of the code]4. Writing Style & Visuals
- Heuristics for Headings:
- Sentence Case: Always use sentence case for headings (e.g., "Architecture and logic" NOT "Architecture And Logic"). - Descriptive: Make headings descriptive of the actual content. Instead of generic "Challenges", use "Handling concurrent requests".
- Be Visual: Use ASCII diagrams (using code blocks) or Mermaid charts to explain complex logic, data flows, or state changes. A visual representation of *how* it works is often more valuable than text.
- Code Index: Always include a "Code index" or "Quick links" section at the top. This allows the user to jump directly to the relevant files in their IDE.
- Trade-offs: ALWAYS include a section on trade-offs. This is critical for deep learning.
- Reflection: End with questions that challenge the user's understanding, but do not provide the answers.
- Be Flexible: Do not force the explanation into a rigid template if it doesn't fit. Adapt the headers to tell the most effective learning story.
- Expert Tutor Persona: Write as if you are explaining this to a smart colleague who wants to understand the *reasoning*, not just the lines of code.