---
description: Generate a learning log documenting what the user learned during this feature development
scripts:
  sh: scripts/bash/check-prerequisites.sh --json
  ps: scripts/powershell/check-prerequisites.ps1 -Json
---

# COMMAND: Learning Log - Record What You Learned

## CONTEXT

After completing a feature (or at any point during development), you should generate a learning log that documents:

- Technical terms the user learned
- Design decisions made
- Concepts to explore next
- Skills improved

This is a key differentiator of **Spec-Kit-CoLearn** - we don't just ship code, we help users understand what they built and learn along the way.

## YOUR ROLE

As the AI architect, you should:

1. Track concepts discussed during discovery, planning, and implementation
2. Identify technical terms the user may not have known before
3. Summarize trade-off decisions made
4. Suggest next concepts to explore
5. Generate a well-structured learning log file

## WHEN TO RUN

Run `/sp.learn` after:

- `/sp.implement` completes successfully
- User says "tasks approved" (before closing the feature)
- At any point the user wants to see what they've learned

## WORKFLOW

### Step 1: Identify Learned Terms

Review the conversation and identify technical terms the user learned:

- Authentication, Authorization, OAuth, JWT
- Multi-tenancy, Role-Based Access Control (RBAC)
- API design patterns, REST, GraphQL
- Database concepts: indexing, normalization, caching
- DevOps: CI/CD, containers, cloud services

### Step 2: Document Decisions

For each significant decision made, document:

- Options considered
- Trade-offs discussed
- Why the user chose the selected option

### Step 3: Suggest Next Steps

Based on what was learned, suggest related concepts to explore:

- If they learned authentication → next: OAuth flows, MFA
- If they learned basic API → next: pagination, rate limiting
- If they learned local storage → next: databases, cloud storage

### Step 4: Create the Learning Log File

Generate file: `specs/<feature>/learning-log.md`

Use this template:

```markdown
# Learning Log: [Feature Name]

**Feature:** [Feature Name]
**Date:** [YYYY-MM-DD]
**User:** [User Name]
**AI Tool:** [Claude Code / Codex / Gemini / etc.]

---

## Summary

[Brief summary of what was built and what was learned]

---

## Terms You Learned

| # | Term | Definition | Why It Matters |
|---|---|---|---|
| 1 | [term] | [simple definition in 1-2 sentences] | [relevance to this project] |
| 2 | [term] | [definition] | [importance] |
| 3 | [term] | [definition] | [importance] |
| 4 | [term] | [definition] | [importance] |
| 5 | [term] | [definition] | [importance] |

---

## Decisions You Made

### Decision 1: [Title]

**Options Considered:**

- Option A: [description] — pros / cons
- Option B: [description] — pros / cons ← **CHOSEN**
- Option C: [description] — pros / cons

**Why You Chose This:**
[User's reasoning in their own words or summary]

---

## Concepts to Explore Next

Based on what you learned, here are related concepts to deepen your understanding:

| # | Concept | Why It's Relevant | Resource |
|---|---|---|---|
| 1 | [concept] | [how it connects to what you learned] | [link to learn more] |
| 2 | [concept] | [relevance] | [link] |
| 3 | [concept] | [relevance] | [link] |

---

## Skills Improved

- [ ] [Skill 1: e.g., "Understanding API design"]
- [ ] [Skill 2: e.g., "Writing user stories"]
- [ ] [Skill 3: e.g., "Thinking about edge cases"]
- [ ] [Skill 4: e.g., "Making architectural decisions"]

---

## Reflections

### What went well:
[User's reflection on what worked well in the process]

### What was challenging:
[Challenges faced during development]

### What to do differently next time:
[Lessons for future projects]

---

## Next Steps

- [Next step for this feature]
- [Potential improvements]
- [Related features to add]

---

*Generated by Spec-Kit-CoLearn - AI Co-Learning Framework*
```

### Step 5: Update Glossary

Also add learned terms to the project glossary at `history/glossary.md`:

```markdown
## [Term Name]

**Category:** [Architecture / Security / Data / Performance / etc.]
**Definition:** [Simple definition]
**First Learned In:** [Feature name]
**Date:** [YYYY-MM-DD]
```

## EXAMPLE LEARNING LOG

Here's an example of what a learning log might contain for an authentication feature:

```markdown
# Learning Log: User Authentication

## Terms You Learned

| # | Term | Definition | Why It Matters |
|---|---|---|---|
| 1 | Authentication | Verifying who a user is (login) | Core security for any app |
| 2 | Authorization | Deciding what a user can do | Controls access to features |
| 3 | OAuth | Standard protocol for third-party login | Lets users log in with Google/GitHub |
| 4 | JWT | JSON Web Token - a secure way to transmit user identity | Replaces sessions for APIs |
| 5 | Password Hashing | One-way encryption of passwords | Protects passwords even if DB is breached |

## Decisions You Made

You chose Email/Password + Google OAuth because:
- Lower friction for users (no new password to remember)
- Industry standard for developer tools
- Google OAuth is well-documented

## Next Concepts to Explore

- Multi-Factor Authentication (MFA)
- Session management best practices
- Token refresh and rotation
```

## OUTPUT

1. Create `specs/<feature>/learning-log.md`
2. Update `history/glossary.md` with new terms
3. Present summary to user

## TONE

- Celebratory - acknowledge what the user learned
- Educational - explain why each term matters
- Forward-looking - suggest next steps
- Professional but warm
