From aaf2453fbdfe7a15c07f11d861224f34ab4b53cb Mon Sep 17 00:00:00 2001 From: Matt Pocock Date: Sun, 31 May 2026 10:08:36 +0100 Subject: [PATCH] Refine teaching skill documentation to enhance clarity and interactivity of explainers --- skills/engineering/to-prd/SKILL.md | 6 ++---- skills/in-progress/teach/SKILL.md | 4 ++++ 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/skills/engineering/to-prd/SKILL.md b/skills/engineering/to-prd/SKILL.md index 47a01d4..ee758fd 100644 --- a/skills/engineering/to-prd/SKILL.md +++ b/skills/engineering/to-prd/SKILL.md @@ -11,11 +11,9 @@ The issue tracker and triage label vocabulary should have been provided to you 1. Explore the repo to understand the current state of the codebase, if you haven't already. Use the project's domain glossary vocabulary throughout the PRD, and respect any ADRs in the area you're touching. -2. Sketch out the major modules you will need to build or modify to complete the implementation. Actively look for opportunities to extract deep modules that can be tested in isolation. +2. Sketch out the seams at which you're going to test the feature. Existing seams should be preferred to new ones. Use the highest seam possible. If new seams are needed, propose them at the highest point you can. -A deep module (as opposed to a shallow module) is one which encapsulates a lot of functionality in a simple, testable interface which rarely changes. - -Check with the user that these modules match their expectations. Check with the user which modules they want tests written for. +Check with the user that these seams match their expectations. 3. Write the PRD using the template below, then publish it to the project issue tracker. Apply the `ready-for-agent` triage label - no need for additional triage. diff --git a/skills/in-progress/teach/SKILL.md b/skills/in-progress/teach/SKILL.md index 0bd3633..d683bbd 100644 --- a/skills/in-progress/teach/SKILL.md +++ b/skills/in-progress/teach/SKILL.md @@ -60,6 +60,10 @@ Knowledge and skills usually need to be taught as a 1-2 punch. You teach the kno Knowledge should first be gathered from trusted resources, then taught to the user via HTML explainers. These explainers should be beautiful, adhere to the glossary, and be saved to the local file system where they can be reviewed later. +Explainers should be littered with citations - links to external resources to back up any claim made. + +Explainers should be as interactive as possible, with "try this" callouts to let the user try the knowledge. + You should make opening the HTML explainer as easy as possible for the user, ideally with a CLI command they can run. Once the user has read the knowledge, allow them to ask questions about it. Answer their questions directly, and amend the explainer if needed (or produce another one).