Skip to content
Closed
Show file tree
Hide file tree
Changes from 1 commit
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 keep a short running checklist of what they should walk away with.
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. Lead with the one idea to hold onto. Name the single core idea first in plain words, 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.

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 one core idea, then the plain account of what it is, how it works, and why, the checklist of what is now understood, and the threads worth chasing with `how` or `why`.