mrdulasolutions/devlearn/devlearn-teach-while-coding

DevLearn: Teach While Coding

Iron law

Teach without blocking ship. Complete the user's task first. Lessons are additive unless they explicitly pause.

Shared doctrine

• Skill structure guide → ../shared/skill-skeleton.md
• Platform paths (Cursor, Codex, OpenCode…) → ../shared/agent-compatibility.md
• Voice → ../shared/voice.md
• Viber block → ../shared/lesson-block.md
• Seasoned block → ../shared/decision-block.md
• Depth + persona → ../shared/depth-levels.md
• Rubric → ../shared/lesson-rubric.md
• Session recap → ../shared/session-recap.md
• Visual diagrams → ../shared/visual-flow.md
• Footer → ../shared/completion-protocol.md
• Teach/skip rules → reference.md

Phase 0: Config & session memory

Parse DEVLEARN.md:

Session opener: If progress: true and .devlearn/progress.md exists, use opener from session-recap.md (skip if "just ship" or seasoned quiet mode).

Autodetect persona: See depth-levels.md. Override with "explain like PR review" → seasoned.

Phase 0b: Before big changes

If before_big_changes: true and plan touches >5 files or architecture shift:

1. Pause before editing
2. Offer /devlearn-before-you-ship — plain-English plan in 5 bullets
3. Proceed when user confirms or says "just ship"

Phase 1: Do the work

Execute normally. Small logical change sets. Match stack from package.json when teaching (React/Next skills for framework code).

Phase 2: Emit block (when teaching ON)

After substantive batch, apply rubric then emit:

Seasoned whitelist: Only emit if change tags a seasoned_lessons_on category OR user asked for explanation.

Viber sections

What changed → Why → How (file:line) → Term → Try it (curious+)

Seasoned sections

Decision → Alternatives → Risk & verify → Anchor (if non-obvious)

Append row to .devlearn/decisions.md when decisions: true and choice is non-obvious.

Progress & glossary

• glossary: true → update DEVLEARN_GLOSSARY.md or .devlearn/glossary.md
• progress: true → append concept to .devlearn/progress.md; refresh Last session

Create .devlearn/ from repo templates if missing.

Phase 2b: Lifecycle hooks (DEVLEARN.md lifecycle)

See ../shared/ship-lifecycle.md.

Phase 3: Handoffs

Overrides

STOP checkpoint

"I don't understand" → stop edits; one term; one question (what / why / where in code).

All 21 skills (handoff index)

Install or refresh: ./install.sh --verify from DevLearn repo.

Additional resources

• Teach/skip rules → reference.md
• Onboard → devlearn-onboard
• Session end → devlearn-recap
• Plan big changes → devlearn-before-you-ship
• Lesson QA → devlearn-lesson-review