pstack: add the teach skill (compose how + why into one explanation)

[poteto]

Summary

• Adds /teach, ported verbatim from the private version: plain-definition-first explanations that run how + why and weave the findings, conversation-not-lecture pacing, diagram-by-diagram build-up for anything with 3+ moving parts, unslop-clean prose. The private version had absorbed every iteration from the earlier closed port attempt (pstack: add the teach skill #127) plus newer rules (incremental diagrams, one-name-per-concept), so this supersedes that branch.
• README skills-table row for /teach.
• Scrub verified clean: no internal names, paths, or model slugs; its how/why/unslop references all resolve in pstack.
• No version bump: 0.11.1 just landed in pstack: add the teach skill; bump to 0.11.1 #152 and covers this addition.

Note: this commit was originally pushed to the #152 branch pre-merge, but the PR head never picked it up (github sync anomaly — the branch showed the commit, the PR object didn't). Re-landing it cleanly here.

---

Note

Low Risk
Documentation-only skill and README changes; no application runtime or security-sensitive code paths.

Overview
Adds a new /teach skill that turns “help me understand X” into one plain explanation by invoking how and why (in parallel when needed), blending their findings instead of re-investigating, and routing prose through unslop.

The skill defines teaching behavior end to end: lead with a short plain definition tied to the case at hand, keep a conversational pace (no lecture framing or quizzes), and build visuals incrementally (one new moving part per diagram or whiteboard-style image when there are three or more parts).

Documents /teach in the pstack README skills table with a one-line description of when to use it.

^{Reviewed by Cursor Bugbot for commit 643400f. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 2 potential issues.

Autofix Details

Bugbot Autofix prepared fixes for both issues found in the latest run.

• ✅ Fixed: Contradictory why skill scope
  • Changed teach to selectively reuse why research components without invoking its full seven-category contract.
• ✅ Fixed: Child skill output clash
  • Made teach consume only child-skill research passes while owning the final paced explanation.

Or push these changes by commenting:

@cursor push d8c5253d4f

Preview (d8c5253d4f)

diff --git a/pstack/skills/teach/SKILL.md b/pstack/skills/teach/SKILL.md
--- a/pstack/skills/teach/SKILL.md
+++ b/pstack/skills/teach/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: teach
-description: "Explain a body of work plainly so a person actually understands it. Runs the `how` and `why` skills and weaves what they find into one clear explanation. Use for 'teach me this', 'help me really understand X', 'explain this change or subsystem to me'."
+description: "Explain a body of work plainly so a person actually understands it. Reuses `how` explorers and selected `why` investigators, then weaves their findings into one clear explanation. Use for 'teach me this', 'help me really understand X', 'explain this change or subsystem to me'."
 disable-model-invocation: true
 ---
 
@@ -8,10 +8,10 @@
 
 **You explain what a thing is, how it works, and why it's built that way, in one plain account at the person's pace. The goal is that they understand it, not that you change anything.** For "teach me this", "help me really understand X", or "explain this change or subsystem to me".
 
-Teach sits on top of `how` and `why`. Get your bearings on what the work is and what it touches, then run `how` for how it works and `why` for why it's that way. Those are real skill invocations that do their own digging. Blend what they find into one plain explanation, lead with what matters to the person, and go deeper when they ask. Let those skills do the investigation. Don't redo it by hand.
+Teach reuses the research machinery from `how` and `why`, but owns the explanation. Do not invoke either skill end to end: their Present steps produce standalone reports that conflict with Teach's paced reply. Use `how` explorers for how the work operates and selected `why` investigators for why it is that way. Blend their findings into one plain explanation, lead with what matters to the person, and go deeper when they ask. Let those research passes do the investigation. Don't redo it by hand.
 
 1. Decide the few things they should walk away understanding. Choose them from why they're asking (about to change it, reviewing it, debugging it, new to it) and what they already know, both read from the conversation, not quizzed out of them. Skip what they plainly already know. Put the depth where their question is.
-2. Let `how` and `why` do the work, don't redo it. Read the code yourself to get oriented, then run `how` for how it works and `why` for why. Run them in parallel and combine the results. Match the size to the question: run both for a subsystem, maybe one is enough for a small change. Keep `why` narrow by default (git plus a source or two) since its full sweep is slow, and widen it only when the reasons are the point.
+2. Reuse the research pieces of `how` and `why`; do not run their synthesis, Present, or output-format steps. Read the code yourself to get oriented. For mechanics, use the `how` Step 2a explorer pattern, with one explorer for a narrow question and parallel explorers for a subsystem. For rationale, build the `why` Step 2 code anchor, then run source control plus one or two relevant Step 3 source investigators. This is selective reuse of its investigator playbooks, not a `why` invocation, so do not claim full seven-category coverage. Widen the rationale search only when the reasons are the point. Run mechanics and rationale research in parallel and combine their findings. A small change may need only one side.
 3. Start with a plain definition. Name the thing and say what it is in general terms, the way a senior engineer would say it out loud, with its common name if it has one. Then tie it to the case in front of you ("in X, we use this to ...") and build from there: how it works, the deeper reasons, the edge cases. Explain how it works, don't just name it. For each part, explain the idea so it clicks: the problem it solves and how it actually works. Walk through what happens as the person does the thing (opens a long chat, scrolls up) when that is what makes it land. Listing functions and constants is reference, not teaching. Don't print framing labels ("the one idea to hold onto", "the thing to walk away with", "the key insight", "at its core", "TL;DR"). Give the smallest complete answer first, a sentence or two, not a dense paragraph, then stop. Add layers when they ask. Never a wall of text.
 4. Keep it a conversation, not a lecture or a performance. Offer to go deeper or move on, and follow their lead. No quizzes. No pacing theater: don't print "Pause", don't ask them to say it back, don't announce "the sentence to nail", and don't flag a part as important or hard ("here is the part worth slowing down on", "this is the tricky part", "here is where it gets interesting"). Just say it. When you would pause, stop and let them respond. Running one-shot with no live human, deliver it cleanly and put any offer to go deeper at the end.
 5. Show, don't only tell, and build the picture up diagram by diagram. Open the diff, the code, or the debugger when that is the fastest way to land it. Draw when a picture lands faster than words. For anything with three or more moving parts, do not draw one diagram with all of them at once. Draw a short series instead, where each diagram redraws the last and adds a single part, so the reader watches the system assemble. That series is not a wall. It is the opposite of one, since each step is small and adds exactly one idea. A single all-at-once diagram, especially one saved for the end, is a reference, not teaching. Concretely, to teach a flow from A to B to C, draw it three times. First A to B. Then redraw and add C. Then redraw and add the return edge or the next piece. Three small growing diagrams beat one crowded diagram. Match the medium to the idea, and use both kinds when both help. A mermaid diagram fits a flow or structure where the labels carry the meaning. When the idea is spatial, like layout, overlap, scroll position, or a before and after, reach for the image-generation tool and draw it marker-on-whiteboard style with a few short labels, since image models garble long text. Generate that picture, don't settle for describing it in words. The build-up rule holds for generated images too. A single simple point needs no figure. A visual earns its place by teaching, not decorating.

_{You can send follow-ups to the cloud agent here.}

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Hedge and unslop clash
  • The teach skill now cuts only needless hedging and explicitly preserves why's confidence language during the unslop pass.

Or push these changes by commenting:

@cursor push 25ede3b999

Preview (25ede3b999)

diff --git a/pstack/skills/teach/SKILL.md b/pstack/skills/teach/SKILL.md
--- a/pstack/skills/teach/SKILL.md
+++ b/pstack/skills/teach/SKILL.md
@@ -16,6 +16,6 @@
 4. Keep it a conversation, not a lecture or a performance. Offer to go deeper or move on, and follow their lead. No quizzes. No pacing theater: don't print "Pause", don't ask them to say it back, don't announce "the sentence to nail", and don't flag a part as important or hard ("here is the part worth slowing down on", "this is the tricky part", "here is where it gets interesting"). Just say it. When you would pause, stop and let them respond. Running one-shot with no live human, deliver it cleanly and put any offer to go deeper at the end.
 5. Show, don't only tell, and build the picture up diagram by diagram. Open the diff, the code, or the debugger when that is the fastest way to land it. Draw when a picture lands faster than words. For anything with three or more moving parts, do not draw one diagram with all of them at once. Draw a short series instead, where each diagram redraws the last and adds a single part, so the reader watches the system assemble. That series is not a wall. It is the opposite of one, since each step is small and adds exactly one idea. A single all-at-once diagram, especially one saved for the end, is a reference, not teaching. Concretely, to teach a flow from A to B to C, draw it three times. First A to B. Then redraw and add C. Then redraw and add the return edge or the next piece. Three small growing diagrams beat one crowded diagram. Match the medium to the idea, and use both kinds when both help. A mermaid diagram fits a flow or structure where the labels carry the meaning. When the idea is spatial, like layout, overlap, scroll position, or a before and after, reach for the image-generation tool and draw it marker-on-whiteboard style with a few short labels, since image models garble long text. Generate that picture, don't settle for describing it in words. The build-up rule holds for generated images too. A single simple point needs no figure. A visual earns its place by teaching, not decorating.
 
-Write every response through the **unslop** skill, in plain spoken English, the way you'd explain it to a colleague. Be tight, not terse: cut filler and hedging, keep the part that makes it click. Padding is the enemy, not ideas. Don't list functions and constants like a changelog. State the concrete mechanism, not a metaphor, a framing, or a preview of what is coming. This is the target density: "Virtualization runs in two parts, one for rendering and one for loading from disk. When an item scrolls out past the buffer, both its DOM node and its in-memory data are evicted." Normal sentence case, not all-lowercase. No em dashes. Prefer periods over commas. Keep each sentence to one or two commas. If clauses pile up, split them into separate sentences. Give each concept one name and keep it, since switching between synonyms for the same thing (bubble, message, row) makes the reader re-derive that they are the same. Avoid mirror sentences ("A without B, or B without A") and tidy closers ("the rest follows", "it all falls out"). The words in these steps are directions to you, not labels to print. Don't echo the scaffolding as headers or stock phrases.
+Write every response through the **unslop** skill, in plain spoken English, the way you'd explain it to a colleague. Be tight, not terse: cut filler and needless hedging, but don't change `why`'s confidence language. Keep the part that makes it click. Padding is the enemy, not ideas. Don't list functions and constants like a changelog. State the concrete mechanism, not a metaphor, a framing, or a preview of what is coming. This is the target density: "Virtualization runs in two parts, one for rendering and one for loading from disk. When an item scrolls out past the buffer, both its DOM node and its in-memory data are evicted." Normal sentence case, not all-lowercase. No em dashes. Prefer periods over commas. Keep each sentence to one or two commas. If clauses pile up, split them into separate sentences. Give each concept one name and keep it, since switching between synonyms for the same thing (bubble, message, row) makes the reader re-derive that they are the same. Avoid mirror sentences ("A without B, or B without A") and tidy closers ("the rest follows", "it all falls out"). The words in these steps are directions to you, not labels to print. Don't echo the scaffolding as headers or stock phrases.
 
 **Reply:** the explanation itself, never a report about what you did or delivered. Lead with the main point, then the plain account of what it is, how it works, and why, and the threads worth chasing with `how` or `why`.

_{You can send follow-ups to the cloud agent here.}

^{Reviewed by Cursor Bugbot for commit 643400f. Configure here.}

[cursor]

Hedge and unslop clash

Medium Severity · Logic Bug

The new instruction to preserve why's confidence language conflicts with the unslop skill's directive to cut hedging. This can cause teach explanations to strip epistemic hedges, overstating certainty and presenting inferred rationale as settled fact.

 

^{Reviewed by Cursor Bugbot for commit 643400f. Configure here.}

[poteto]

Dismissing: unslop's rule 24 targets excessive hedging — stacked filler qualifiers ('could potentially possibly be argued that it might' → 'may') — not epistemic markers. why's calibrated hedges are single load-bearing words that survive rule 24 by its own example (compression keeps 'may'). The carve-out in teach makes the priority explicit precisely so a literal reader doesn't over-apply rule 24; the two rules compose (cut hedge stacking, keep hedge meaning), no conflict to fix.