added base examples and drills

README.md

@@ -1,3 +1,43 @@
 # refactor-kata
 
-These are various practice drills for practicing refactoring. Using "Working With Legacy Code" by Feathers and "Refactoring" by Fowler
+Practice drills for refactoring, especially with ideas from *Working Effectively with Legacy Code* by Michael Feathers and *Refactoring* by Martin Fowler.
+
+## Repository layout
+
+- `kata/<example-name>/original/`
+  - the frozen messy starting point
+  - copy from here when creating a new drill scenario
+- `kata/<example-name>/scenarios/<scenario-name>/code/`
+  - the working copy for a specific drill attempt
+- `kata/<example-name>/scenarios/<scenario-name>/drill-prompt.md`
+  - instructions and success conditions for that drill
+- `kata/<example-name>/scenarios/<scenario-name>/notes.md`
+  - notes on seams found, tests added, techniques used, and lessons learned
+- `notes/`
+  - cross-kata notes and recurring patterns
+
+## Intended workflow
+
+1. Start with code in `original/`.
+2. Copy that code into a scenario's `code/` folder.
+3. Do the refactor only inside that scenario copy.
+4. Record what you observed and learned in `notes.md`.
+5. Reset by making a fresh scenario from `original/`.
+
+## Current starter kata
+
+- `kata/example-seam-drill/`
+  - a placeholder kata for practicing:
+    - characterization tests
+    - breaking one dependency with a seam
+    - extracting one pure decision from mixed logic
+
+## Goal
+
+The point is not to build a production app. The point is to practice:
+
+- finding seams in messy code
+- adding characterization tests safely
+- making small reviewable refactors
+- separating decisions from mechanics
+- gradually moving code toward stronger boundaries