nweii/project-teacher

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

1. 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.
2. 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.
3. 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.