Each README is written for a human audience, explaining:
- What the skill does (not what format it follows)
- What benefit the user gets from installing it
- Quick setup and usage patterns
- When to load/trigger the skill
- What scripts, references, and templates it ships
data-scientist already had a README — left unchanged.
48 READMEs added across all skill and bundle directories.
Adapted from obra/superpowers (Jesse Vincent, MIT) and expanded with
real-world debugging patterns from production use. Core additions:
Phase 1 sub-steps for common failure modes:
- Schema/environment divergence (test vs production schema diffing)
- Exception type specificity (sibling exception traps in Pyhton)
- Progressive characterization grid (isolate retrieval failures variable by variable)
- Dependency source detection (editable dev forks causing schema drift)
- Systematic web research protocol (structured search before guessing)
- macOS sandboxed app debugging (containers, XPC, TCC, iCloud sync)
- Trace data flow upstream from the symptom
Key heuristics:
- Rule of Three: 3+ failed fixes = question the architecture
- Red Flags table: 12 rationalizations to catch yourself making
- Investigation Flow: keep pushing, don't break momentum to ask questions
Includes two worked example references (dev fork detection, macOS Books.app).
Signed-off-by: Jasper <magnus@groktop.us>
Magnus Hedemark