Updates

obsidian-vault/SKILL.md

@@ -0,0 +1,54 @@
+# Obsidian Vault
+
+## Vault location
+
+`/mnt/d/Obsidian Vault/AI Research/`
+
+Mostly flat at root level.
+
+## Naming conventions
+
+- **Index notes**: aggregate related topics (e.g., `Ralph Wiggum Index.md`, `Skills Index.md`, `RAG Index.md`)
+- **Title case** for all note names
+- No folders for organization - use links and index notes instead
+
+## Linking
+
+- Use Obsidian `[[wikilinks]]` syntax: `[[Note Title]]`
+- Notes link to dependencies/related notes at the bottom
+- Index notes are just lists of `[[wikilinks]]`
+
+## Workflows
+
+### Search for notes
+
+```bash
+# Search by filename
+find "/mnt/d/Obsidian Vault/AI Research/" -name "*.md" | grep -i "keyword"
+
+# Search by content
+grep -rl "keyword" "/mnt/d/Obsidian Vault/AI Research/" --include="*.md"
+```
+
+Or use Grep/Glob tools directly on the vault path.
+
+### Create a new note
+
+1. Use **Title Case** for filename
+2. Write content as a unit of learning (per vault rules)
+3. Add `[[wikilinks]]` to related notes at the bottom
+4. If part of a numbered sequence, use the hierarchical numbering scheme
+
+### Find related notes
+
+Search for `[[Note Title]]` across the vault to find backlinks:
+
+```bash
+grep -rl "\\[\\[Note Title\\]\\]" "/mnt/d/Obsidian Vault/AI Research/"
+```
+
+### Find index notes
+
+```bash
+find "/mnt/d/Obsidian Vault/AI Research/" -name "*Index*"
+```

prd-to-issues/SKILL.md

@@ -0,0 +1,94 @@
+# PRD to Issues
+
+Break a PRD into independently-grabbable GitHub issues using vertical slices (tracer bullets).
+
+## Process
+
+### 1. Locate the PRD
+
+Ask the user for the PRD GitHub issue number (or URL). Fetch it with `gh issue view <number>`. Read and internalize the full PRD content (with all comments).
+
+### 2. Explore the codebase
+
+Read the key modules and integration layers referenced in the PRD. Identify:
+
+- The distinct integration layers the feature touches (e.g. DB/schema, API/backend, UI, tests, config)
+- Existing patterns for similar features
+- Natural seams where work can be parallelized
+
+### 3. Draft vertical slices
+
+Break the PRD into **tracer bullet** issues. Each issue is a thin vertical slice that cuts through ALL integration layers end-to-end, NOT a horizontal slice of one layer.
+
+<vertical-slice-rules>
+- Each slice delivers a narrow but COMPLETE path through every layer (schema, API, UI, tests)
+- A completed slice is demoable or verifiable on its own
+- Prefer many thin slices over few thick ones
+- The first slice should be the simplest possible end-to-end path (the "hello world" tracer bullet)
+- Later slices add breadth: edge cases, additional user stories, polish
+</vertical-slice-rules>
+
+### 4. Quiz the user
+
+Present the proposed breakdown as a numbered list. For each slice, show:
+
+- **Title**: short descriptive name
+- **Layers touched**: which integration layers this slice cuts through
+- **Blocked by**: which other slices (if any) must complete first
+- **User stories covered**: which user stories from the PRD this addresses
+
+Ask the user:
+
+- Does the granularity feel right? (too coarse / too fine)
+- Are the dependency relationships correct?
+- Should any slices be merged or split further?
+- Is the ordering right for the first tracer bullet?
+- Are there any slices missing?
+
+Iterate until the user approves the breakdown.
+
+### 5. Create the GitHub issues
+
+For each approved slice, create a GitHub issue using `gh issue create`. Use the issue body template below.
+
+Create issues in dependency order (blockers first) so you can reference real issue numbers in the "Blocked by" field.
+
+<issue-template>
+## Parent PRD
+
+#<prd-issue-number>
+
+## What to build
+
+A concise description of this vertical slice. Describe the end-to-end behavior, not layer-by-layer implementation. Reference specific sections of the parent PRD rather than duplicating content.
+
+## Acceptance criteria
+
+- [ ] Criterion 1
+- [ ] Criterion 2
+- [ ] Criterion 3
+
+## Blocked by
+
+- Blocked by #<issue-number> (if any)
+
+Or "None - can start immediately" if no blockers.
+
+## User stories addressed
+
+Reference by number from the parent PRD:
+
+- User story 3
+- User story 7
+  </issue-template>
+
+After creating all issues, print a summary table:
+
+```
+| # | Title | Blocked by | Status |
+|---|-------|-----------|--------|
+| 42 | Basic widget creation | None | Ready |
+| 43 | Widget listing | #42 | Blocked |
+```
+
+Do NOT close or modify the parent PRD issue.

scaffold-exercises/SKILL.md

@@ -0,0 +1,101 @@
+# Scaffold Exercises
+
+Create exercise directory structures that pass `pnpm ai-hero-cli internal lint`.
+
+## Directory naming
+
+- **Sections**: `XX-section-name/` inside `exercises/` (e.g., `01-retrieval-skill-building`)
+- **Exercises**: `XX.YY-exercise-name/` inside a section (e.g., `01.03-retrieval-with-bm25`)
+- Section number = `XX`, exercise number = `XX.YY`
+- Names are dash-case (lowercase, hyphens)
+
+## Exercise variants
+
+Each exercise needs at least one of these subfolders:
+
+- `problem/` - student workspace with TODOs
+- `solution/` - reference implementation
+- `explainer/` - conceptual material, no TODOs
+
+When stubbing, default to `explainer/` unless the plan specifies otherwise.
+
+## Required files
+
+Each subfolder (`problem/`, `solution/`, `explainer/`) needs a `readme.md` that:
+
+- Is **not empty** (must have real content, even a single title line works)
+- Has no broken links
+
+When stubbing, create a minimal readme with a title and a description:
+
+```md
+# Exercise Title
+
+Description here
+```
+
+If the subfolder has code, it also needs a `main.ts` (>1 line). But for stubs, a readme-only exercise is fine.
+
+## Workflow
+
+1. **Parse the plan** - extract section names, exercise names, and variant types
+2. **Create directories** - `mkdir -p` for each path
+3. **Create stub readmes** - one `readme.md` per variant folder with a title
+4. **Run lint** - `pnpm ai-hero-cli internal lint` to validate
+5. **Fix any errors** - iterate until lint passes
+
+## Lint rules summary
+
+The linter (`pnpm ai-hero-cli internal lint`) checks:
+
+- Each exercise has subfolders (`problem/`, `solution/`, `explainer/`)
+- At least one of `problem/`, `explainer/`, or `explainer.1/` exists
+- `readme.md` exists and is non-empty in the primary subfolder
+- No `.gitkeep` files
+- No `speaker-notes.md` files
+- No broken links in readmes
+- No `pnpm run exercise` commands in readmes
+- `main.ts` required per subfolder unless it's readme-only
+
+## Moving/renaming exercises
+
+When renumbering or moving exercises:
+
+1. Use `git mv` (not `mv`) to rename directories - preserves git history
+2. Update the numeric prefix to maintain order
+3. Re-run lint after moves
+
+Example:
+
+```bash
+git mv exercises/01-retrieval/01.03-embeddings exercises/01-retrieval/01.04-embeddings
+```
+
+## Example: stubbing from a plan
+
+Given a plan like:
+
+```
+Section 05: Memory Skill Building
+- 05.01 Introduction to Memory
+- 05.02 Short-term Memory (explainer + problem + solution)
+- 05.03 Long-term Memory
+```
+
+Create:
+
+```bash
+mkdir -p exercises/05-memory-skill-building/05.01-introduction-to-memory/explainer
+mkdir -p exercises/05-memory-skill-building/05.02-short-term-memory/{explainer,problem,solution}
+mkdir -p exercises/05-memory-skill-building/05.03-long-term-memory/explainer
+```
+
+Then create readme stubs:
+
+```
+exercises/05-memory-skill-building/05.01-introduction-to-memory/explainer/readme.md -> "# Introduction to Memory"
+exercises/05-memory-skill-building/05.02-short-term-memory/explainer/readme.md -> "# Short-term Memory"
+exercises/05-memory-skill-building/05.02-short-term-memory/problem/readme.md -> "# Short-term Memory"
+exercises/05-memory-skill-building/05.02-short-term-memory/solution/readme.md -> "# Short-term Memory"
+exercises/05-memory-skill-building/05.03-long-term-memory/explainer/readme.md -> "# Long-term Memory"
+```

write-a-prd/SKILL.md

@@ -1,27 +1,18 @@
----
-name: write-a-prd
-description: Use this skill when writing a PRD for a feature.
----
-
 This skill will be invoked when the user wants to create a PRD. You should go through the steps below. You may skip steps if you don't consider them necessary.
 
 1. Ask the user for a long, detailed description of the problem they want to solve and any potential ideas for solutions.
 
 2. Explore the repo to verify their assertions and understand the current state of the codebase.
 
-3. Ask whether they have considered other options, and present other options to them.
+3. Interview the user relentlessly about every aspect of this plan until you reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one.
 
-4. Interview the user about the implementation. Be extremely detailed and thorough.
+4. 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.
-
-5. Hammer out the exact scope of the implementation. Work out what you plan to build and what you DON'T plan to build as part of this PRD.
-
-6. 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.
 
 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.
 
-7. Once you have a complete understanding of the problem and solution, use the template below to write the PRD. The PRD should be submitted as a GitHub issue.
+5. Once you have a complete understanding of the problem and solution, use the template below to write the PRD. The PRD should be submitted as a GitHub issue.
 
 <prd-template>
 
@@ -45,14 +36,6 @@ A LONG, numbered list of user stories. Each user story should be in the format o
 
 This list of user stories should be extremely extensive and cover all aspects of the feature.
 
-## 'Polishing' Requirements
-
-Once the user stories are complete, we will end up with a working, but not refined, feature or application. After the work is complete, we should enter a polishing phase.
-
-This should be a list of checks that we want to make at the end of the work to polish and refine the work done for maximum user enjoyment and experience.
-
-They should not meaningfully extend the work but instead ensure harmony of all created elements and ensure any errors are properly handled and make things delightful and beautiful.
-
 ## Implementation Decisions
 
 A list of implementation decisions that were made. This can include: