diff --git a/skills/engineering/grill-with-docs/CONTEXT-FORMAT.md b/skills/engineering/grill-with-docs/CONTEXT-FORMAT.md index 0830255..eaf2a18 100644 --- a/skills/engineering/grill-with-docs/CONTEXT-FORMAT.md +++ b/skills/engineering/grill-with-docs/CONTEXT-FORMAT.md @@ -24,13 +24,10 @@ _Avoid_: Client, buyer, account ## Rules -- **Be opinionated.** When multiple words exist for the same concept, pick the best one and list the others as aliases to avoid. -- **Flag conflicts explicitly.** If a term is used ambiguously, call it out in "Flagged ambiguities" with a clear resolution. +- **Be opinionated.** When multiple words exist for the same concept, pick the best one and list the others under `_Avoid_`. - **Keep definitions tight.** One or two sentences max. Define what it IS, not what it does. -- **Show relationships.** Use bold term names and express cardinality where obvious. - **Only include terms specific to this project's context.** General programming concepts (timeouts, error types, utility patterns) don't belong even if the project uses them extensively. Before adding a term, ask: is this a concept unique to this context, or a general programming concept? Only the former belongs. - **Group terms under subheadings** when natural clusters emerge. If all terms belong to a single cohesive area, a flat list is fine. -- **Write an example dialogue.** A conversation between a dev and a domain expert that demonstrates how the terms interact naturally and clarifies boundaries between related concepts. ## Single vs multi-context repos 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 478212e..1694104 100644 --- a/skills/in-progress/teach/SKILL.md +++ b/skills/in-progress/teach/SKILL.md @@ -71,6 +71,14 @@ Each lesson should contain a reminder to ask followup questions to the agent. Th Skills should be taught through interactive lessons. There are several tools at your disposal: +Lessons should be littered with citations - links to external resources to back up any claim made. + +Lessons should be as interactive as possible, with "try this" callouts to let the user try the knowledge. + +Once the user has read the knowledge, allow them to ask questions about it. Answer their questions directly, and amend the lesson if needed (or produce another one). At this point, you can amend the glossary if it appears clear they understand a term. + +There are several tools at your disposal: + - Interactive lessons, using quizzes and light in-browser tasks - Lessons which guide the user through a list of real-world steps to take (for instance, yoga poses) - In-agent quizzes, where you ask the user scenario-based questions about what they've learned