safeword 0.7.6 → 0.7.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "safeword",
-  "version": "0.7.6",
+  "version": "0.7.7",
   "description": "CLI for setting up and managing safeword development environments",
   "type": "module",
   "bin": {

package/templates/SAFEWORD.md

@@ -306,3 +306,14 @@ When markdown lint reports MD040 (missing language), choose:
 - Integration struggle between tools
 
 **Before extracting:** Check `.safeword/learnings/` for existing similar learnings—update, don't duplicate.
+
+---
+
+## Always Remember
+
+1. **Clarity → Simplicity → Correctness** (in that order)
+2. **Test what you can test**—never ask user to verify
+3. **RED → GREEN → REFACTOR**—never skip steps
+4. **Commit after each GREEN phase**
+5. **Read the matching guide** when a trigger fires
+6. **End every response** with: `{"proposedChanges": bool, "madeChanges": bool, "askedQuestion": bool}`

package/templates/guides/architecture-guide.md

@@ -413,11 +413,9 @@ export default defineConfig([
 
 ---
 
-## Key Takeaway
+## Key Takeaways
 
-**One comprehensive architecture document per project** > many scattered ADR files:
-
-✅ Full context in one place
-✅ Living document (update in place)
-✅ LLMs consume entire architecture at once
-✅ Sequential decision trees prevent ambiguity
+- One Architecture Doc per project—not scattered ADRs
+- Every decision needs: What / Why / Trade-off / Alternatives
+- Update when adding: technology, schema, or project-wide pattern
+- Living document—update in place with version/status tracking

package/templates/guides/cli-reference.md

@@ -33,3 +33,11 @@ Common flags:
 - `-y, --yes` - Skip confirmations (setup, reset)
 - `-v, --verbose` - Show detailed output (diff)
 - `-q, --quiet` - Suppress output (sync)
+
+---
+
+## Key Takeaways
+
+- Always use `@latest` for setup/check/upgrade/diff to get current CLI
+- Run `sync` after adding/removing frameworks to update linting plugins
+- Use `diff` before `upgrade` to preview changes

package/templates/guides/code-philosophy.md

@@ -196,3 +196,12 @@ Before completing any work, verify:
 # ❌ Bad: "misc fixes"
 # ✅ Good: "fix: login button not responding to clicks"
 ```
+
+---
+
+## Key Takeaways
+
+- Clarity → Simplicity → Correctness (in that order)
+- Delete unused code—no "just in case" abstractions
+- Commit often with descriptive messages
+- Verify library versions before using APIs (training data is stale)

package/templates/guides/context-files-guide.md

@@ -455,3 +455,12 @@ Before committing:
 - Bloated files cost more tokens and introduce noise
 - Keep under 50KB for optimal performance (though no hard limit)
 - Use imports to modularize instead of monolithic files
+
+---
+
+## Key Takeaways
+
+- Keep context files under 200 lines—use imports to modularize
+- Short declarative bullets, not narrative paragraphs
+- Update immediately when architecture changes (stale docs = confusion)
+- Put critical rules at the END of documents (recency bias)

package/templates/guides/data-architecture-guide.md

@@ -198,3 +198,12 @@ Before finalizing data architecture doc:
 - [ ] Migration strategy covers both additive and breaking changes
 - [ ] Version and status match codebase (verify with git/deployment)
 - [ ] Cross-referenced from root ARCHITECTURE.md or SAFEWORD.md (link exists)
+
+---
+
+## Key Takeaways
+
+- Data quality, governance, accessibility are core principles
+- Every entity needs: attributes, types, relationships, constraints
+- Performance targets use concrete numbers (e.g., <100ms, not "fast")
+- Migration strategy covers both additive and breaking changes

package/templates/guides/design-doc-guide.md

@@ -1,5 +1,17 @@
 # Design Doc Guide for Claude Code
 
+## Escalation Check
+
+**STOP if ANY apply—use `architecture-guide.md` first:**
+
+- [ ] Need to choose a technology or library
+- [ ] Need to design a data model or schema
+- [ ] Pattern will affect 2+ features
+
+Then return here.
+
+---
+
 ## How to Fill Out Design Doc
 
 **Template:** `@.safeword/templates/design-doc-template.md`
@@ -169,3 +181,12 @@ Before saving, verify:
 **Important:** Design docs are instructions that LLMs read and follow.
 
 **See:** `@.safeword/guides/llm-guide.md` for comprehensive framework on writing clear, actionable documentation that LLMs can reliably follow.
+
+---
+
+## Key Takeaways
+
+- Escalate to Architecture Doc if: new tech, new schema, or pattern affects 2+ features
+- Reference user stories and test definitions—don't duplicate them
+- Every decision needs: what, why, trade-off
+- ~121 lines target (concise, LLM-optimized)

package/templates/guides/development-workflow.md

@@ -616,3 +616,12 @@ npm run test:e2e # E2E tests only
 
 1. **Global** (`~/.claude/development-workflow.md`) - Universal methodology (test type selection, TDD workflow)
 2. **Project** (`tests/SAFEWORD.md`) - Specific stack, commands, patterns
+
+---
+
+## Key Takeaways
+
+- RED → GREEN → REFACTOR (never skip steps)
+- Choose test type by answering questions IN ORDER (unit → integration → E2E)
+- Never use arbitrary timeouts—poll until condition is met
+- Test behavior, not implementation details

package/templates/guides/learning-extraction.md

@@ -550,3 +550,12 @@ This is a **living process** - iterate and refine based on what works.
 - Refactor when multiple learnings cover similar topics (consolidate)
 - Split when learning file >200 lines (focus on single concept)
 - Update SAFEWORD.md references when learnings move or merge
+
+---
+
+## Key Takeaways
+
+- Extract after 5+ debug cycles or 3+ approaches tried
+- Check existing learnings first—update, don't duplicate
+- One concept per file, under 200 lines
+- Extract immediately while fresh (don't defer to "later")

package/templates/guides/llm-guide.md

@@ -259,6 +259,44 @@ When LLMs hit dead ends, provide concrete next steps.
    - Login form → Dashboard → E2E test (multi-page)"
 ```
 
+### 14. Position-Aware Writing (Recency Bias)
+
+LLMs retain information at the **beginning and end** of context better than the middle. Structure documents accordingly.
+
+```markdown
+❌ BAD - Critical rules buried in middle:
+
+# Guide
+
+## Background (100 lines)
+
+## Details (200 lines)
+
+## Critical Rules (10 lines) ← forgotten
+
+## Appendix (50 lines)
+
+✅ GOOD - Critical rules at end:
+
+# Guide
+
+## Background (100 lines)
+
+## Details (200 lines)
+
+## Appendix (50 lines)
+
+## Key Takeaways (10 lines) ← retained
+```
+
+**Application:**
+
+- CLAUDE.md / SAFEWORD.md: Put "Always Remember" section last
+- Guides: End with "Key Takeaways" section
+- Templates: Put most important sections at top OR bottom, not middle
+
+**Research basis:** "Lost in the middle" phenomenon—models show <40% recall for middle content vs >80% for beginning/end content.
+
 ---
 
 ## Anti-Patterns
@@ -267,6 +305,7 @@ When LLMs hit dead ends, provide concrete next steps.
 ❌ **Undefined jargon** - "Technical debt", "code smell" need definitions
 ❌ **Competing guidance** - Multiple decision frameworks that contradict each other
 ❌ **Outdated references** - Remove concepts, but forget to update all mentions
+❌ **Critical info in the middle** - Most important rules buried between background and appendix
 
 ---
 
@@ -283,6 +322,7 @@ Before saving/committing LLM-consumable documentation:
 - [ ] Tie-breaking rules provided
 - [ ] Complex decisions (3+ branches) have lookup tables
 - [ ] Dead-end paths have re-evaluation steps with examples
+- [ ] Critical rules positioned at END of document (recency bias)
 
 ---
 
@@ -310,3 +350,12 @@ Edge cases:
 - React components with React Testing Library → Integration (not E2E, no real browser)
 - Non-deterministic functions (Date.now()) → Unit test with mocked time
 ```
+
+---
+
+## Key Takeaways
+
+- Decision trees: sequential, MECE, with tie-breakers
+- Every rule needs concrete examples (good vs bad)
+- Define all terms explicitly—assume nothing is obvious
+- Put critical rules at the END of documents (recency bias)

package/templates/guides/tdd-best-practices.md

@@ -613,4 +613,12 @@ Before writing a story, verify it passes all six criteria:
 - **Unit:** Single function/module logic (fast, cheap, low-level confidence)
 
 **Ratio guidance:** 70% unit, 20% integration, 10% E2E (adjust based on project)
-````
+
+---
+
+## Key Takeaways
+
+- RED → GREEN → REFACTOR (commit after each GREEN)
+- Test behavior, not implementation details
+- One assertion per test; test names describe behavior
+- User stories pass INVEST checklist before writing tests

package/templates/guides/test-definitions-guide.md

@@ -332,4 +332,12 @@ npm run test:e2e -- tests/feature-name.spec.ts --grep "specific test name"
 - Concrete examples over abstract rules
 - Edge cases must be explicit
 - Actionable over vague language
-````
+
+---
+
+## Key Takeaways
+
+- Map each user story acceptance criterion to specific tests
+- Include tests for technical constraints (performance, security, etc.)
+- Test behavior, not implementation details
+- Every skipped test needs documented rationale

package/templates/guides/user-story-guide.md

@@ -254,3 +254,12 @@ Save specs as: `.safeword/planning/specs/feature-[slug].md`
 
 - `user-story-1.md` ← Not descriptive
 - `STORY_CAMPAIGN_SWITCHING_FINAL_v2.md` ← Bloated
+
+---
+
+## Key Takeaways
+
+- INVEST checklist: Independent, Negotiable, Valuable, Estimable, Small, Testable
+- "As a [role], I want [action], so that [value]"—always include the "so that"
+- 1-3 acceptance criteria per story; split if >3
+- Include technical constraints (performance, security, etc.) when relevant

package/templates/guides/zombie-process-cleanup.md

@@ -217,3 +217,12 @@ ps aux | grep "/Users/alex/projects/my-project"
 ✅ **DO:** Filter by project directory with `$(pwd)`
 ✅ **DO:** Create project-specific cleanup scripts
 ✅ **DO:** Clean up before AND after development sessions
+
+---
+
+## Key Takeaways
+
+- Use port-based cleanup, not `killall node` (affects all projects)
+- Filter by project directory: `pkill -f "playwright.*$(pwd)"`
+- Clean up before AND after development sessions
+- Create project-specific `scripts/cleanup.sh` for consistent cleanup