Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions pstack/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,7 @@ the rest are useful when you want to specifically invoke them:
| `/poteto-mode` | default entry point for any non-trivial task. |
| `/how` | you want a walkthrough of how a subsystem works. |
| `/why` | you want to know why something was built this way. discovers available MCPs at run time and queries each evidence category in parallel (source control, issue tracker, long-form docs, real-time chat, infra observability, error tracking, analytics warehouse). |
| `/teach` | you want a body of work explained plainly. composes `how` and `why` into one paced, layered explanation led by the single core idea, no quizzes. |
| `/architect` | you're about to write code that crosses a function boundary and want the caller's usage, types, and module shape settled first. |
| `/arena` | you want N parallel attempts at the same thing, then to grab the best parts of each. |
| `/interrogate` | you have a diff and want four different models to try to break it, including a strict code-quality lens. |
Expand Down
20 changes: 20 additions & 0 deletions pstack/skills/teach/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
---
name: teach
description: "Explain a body of work plainly to a person by composing the how and why skills. Use for 'teach me this', 'help me really understand X', 'explain this change or subsystem to me properly'. Synthesizes how (mechanics) and why (rationale) into one paced, layered explanation led by the single core idea."
---

# Teach

**You weave what a thing is, how it works, and why it is that way into one plain explanation, paced to the human. The deliverable is their understanding, not a change.** For "teach me this", "help me really understand X", "explain this change or subsystem to me properly".

Teach is the synthesizer over `how` and `why`. It orients on what the work is and what it touches, then runs `how` for the mechanics and `why` for the rationale as real skill invocations that fan out their own subagents, and weaves their findings into one plain-language account, led by impact and deepened on request. It spawns the engines and composes their output; it does not redo their investigation by hand.

1. Scope the work and decide the few things they should walk away understanding.
2. Run the engines, don't reconstruct them. Orient yourself on what it is and what it touches by reading the work directly, then invoke `how` for the mechanics and `why` for the rationale. Teach spawns them in parallel and synthesizes the results. Size the fan-out to the question: run both for a subsystem, one may be enough for a small change, and keep `why` narrow by default (git plus a source or two) since its full multi-source sweep is slow, widening it only when the rationale is the point.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Missing engine completion gate

Low Severity · Bugbot Rules

Step 2 says how and why spawn in parallel and then results are synthesized, but it never states that weaving must wait until both engine invocations finish. Sibling skills such as how and arena spell out that synthesis runs only after parallel sub-work completes, which this line omits.

Fix in Cursor Fix in Web

Triggered by learned rule: Parallel execution semantics must state ordering constraints explicitly

Reviewed by Cursor Bugbot for commit e633585. Configure here.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Narrow why conflicts with why

Medium Severity · Logic Bug

Step 2 tells the agent to invoke why as a real skill while keeping rationale search narrow (git plus one or two sources), but it never says how to override why's own default of a full seven-category parallel sweep. A literal why run follows that skill's coverage-first posture, so teach can ignore its narrow default and pay the slow path the PR was meant to avoid.

Fix in Cursor Fix in Web

Reviewed by Cursor Bugbot for commit e633585. Configure here.

3. Open with the single core idea as a plain sentence, with no framing label in front of it. No "the one idea to hold onto", no "the key insight", no "at its core", no "TL;DR". Just state the idea, then hang the rest off it: what it is and why it matters, how it works, the deeper whys and edge cases. Give the smallest complete answer first and stop. The layers expand on request, not all at once. Never a wall.
4. Pace to them. Have them restate where it helps and fill from there. Offer to go deeper or move on and let them steer. No quizzes, no keeping the session open until they pass.
5. Show, don't only tell. Open the diff, the code, or the debugger when it lands faster than prose. Reach for a mermaid diagram when a flow or a structure is clearer drawn than described, and generate an image when a spatial or visual idea is easier seen. Use a visual when it carries the explanation, not as decoration.

Write every response through the **unslop** skill. The explanation is a prose surface someone reads to understand, so keep it plain and free of AI tells.

**Reply:** the core idea up front, then the plain account of what it is, how it works, and why, and the threads worth chasing with `how` or `why`.