spec-kit-learn

A Spec Kit extension that generates educational guides from AI-assisted implementations and enhances spec clarifications with mentoring context — designed to help early-career engineers build senior-level engineering judgment.

What it does

This extension adds two commands:

Command	Description
/speckit.learn.review	Generates a learn.md guide explaining the technical decisions, patterns, and concepts applied during implementation
/speckit.learn.clarify	Enhanced /speckit.clarify that includes "Why this matters" context, pros/cons analysis, and recommended options for each clarification

/speckit.learn.review — Learn from what was built

After running /speckit.implement, this command analyzes the completed work and produces a concise learn.md that covers:

• Key Decisions — what was chosen, why, what alternatives existed, and when you'd choose differently
• Concepts to Know — design patterns, framework conventions, and data patterns used in the implementation
• Architecture Overview — how the feature's code is organized and why
• Glossary — domain-specific or framework-specific terms worth knowing

The guide is written in a mentoring tone — direct, practical, and focused on building transferable judgment rather than narrating code.

/speckit.learn.clarify — Clarify with context

A drop-in enhancement for /speckit.clarify that adds:

• "Why this matters" block before each question — explains the risk of leaving it unresolved and what downstream decision it unlocks
• Pros/Cons table for multiple-choice options — quick signal on tradeoffs
• Recommended option with reasoning — so you learn what an experienced engineer would pick and why
• Mentoring tone throughout — connects each explanation to real consequences

Requirements

• Spec Kit >= 0.1.0

No external MCP servers or tools are required — this extension works entirely with Spec Kit's core artifacts.

Installation

From the community catalog

specify extension add learn

Or install from the repository directly:

specify extension add learn --from https://github.com/imviancagrace/spec-kit-learn/archive/refs/tags/v1.0.0.zip

From a local clone

git clone https://github.com/imviancagrace/spec-kit-learn.git
cd /path/to/your-speckit-project
specify extension add --dev /path/to/spec-kit-learn

After installation, verify:

specify extension list

# Should show:
#  ✓ Learning Extension (v1.0.0)
#     Generate educational guides from implementations and enhance clarifications with mentoring context
#     Commands: 2 | Hooks: 1 | Status: Enabled

Usage

Generating a learning guide

After completing implementation, run:

/speckit.learn.review

Optionally scope to a specific phase, ticket, or topic:

/speckit.learn.review Phase 3
/speckit.learn.review PROJ-456
/speckit.learn.review state management

This will:

• Load all spec artifacts (spec, plan, tasks, research, data model, contracts)
• Analyze completed tasks and referenced source files
• Prioritize content by educational value
• Write learn.md to your feature directory

Clarifying with learning context

Before planning, run:

/speckit.learn.clarify

This works like /speckit.clarify but each question includes:

• Why the clarification matters (risk and downstream impact)
• A recommended answer with reasoning
• Pros/cons for each option

Hook: after_implement

When enabled, the extension prompts you to generate a learning guide automatically after /speckit.implement completes.

Artifacts

learn.md

Created by /speckit.learn.review in your feature directory. Structured as:

# What I Learned: [Feature Name]

**Feature**: Browse filing guides by state
**Generated**: 2026-03-03
**Scope**: Full feature
**Implementation status**: 18/18 tasks completed

---

## Key Decisions
### 1. Client-Side Filtering Instead of Server-Side
...

## Concepts to Know
### Smart vs Presentational Components
...

## Architecture Overview
...

## Glossary
| Term | Meaning |
|------|---------|
| ...  | ...     |

License

MIT