1  ---
  2  title: 'Template Implementation'
  3  category: 'archive'
  4  last_verified: '2026-02-15'
  5  related_files:
  6    - 'src/utils/spintax.js'
  7    - 'tests/spintax.test.js'
  8    - 'scripts/test-spintax.js'
  9  tags: ['template', 'implementation', 'testing', 'database', 'api', 'ai', 'llm', 'email']
 10  status: 'archived'
 11  ---
 12  
 13  # Spintax Template Implementation Summary
 14  
 15  ## What Was Done
 16  
 17  Loaded Paul James and Dad's proven email templates and converted them to a **spintax-based template system** for generating unique, natural-sounding proposals at scale.
 18  
 19  ## Key Decisions
 20  
 21  ### 1. Template Variables: Square Brackets `[kwd]`
 22  
 23  **Why square brackets instead of curly braces?**
 24  
 25  - **Curly braces `{}`**: Reserved for spintax variations `{option1|option2}`
 26  - **Square brackets `[]`**: Used for template placeholders `[kwd]`, `[firstname]`
 27  - **Clear separation**: Prevents parsing conflicts and makes templates more readable
 28  - **Industry alignment**: Email service providers often use square brackets for merge tags
 29  
 30  **Standard comparison:**
 31  
 32  - Mustache/Handlebars: `{{variable}}` (industry standard)
 33  - Our choice: `[variable]` (clearer for spintax context)
 34  
 35  ### 2. Email Formatting: Blank Lines Between Paragraphs
 36  
 37  **Research confirms (2026 email best practices):**
 38  
 39  - ✅ **Blank lines improve conversion rates**
 40  - ✅ **Short paragraphs (2 sentences max)** enhance mobile readability
 41  - ✅ **Scannable formatting** reduces bounce rates
 42  - ✅ **White space** improves comprehension and engagement
 43  
 44  **Sources:**
 45  
 46  - [GMass Email Copywriting Guide](https://www.gmass.co/blog/email-copywriting/)
 47  - [Moosend Email Copywriting](https://moosend.com/blog/email-copywriting/)
 48  - [CleverTap Best Practices](https://clevertap.com/blog/email-copywriting/)
 49  
 50  All templates now include proper paragraph spacing with `\n\n`.
 51  
 52  ### 3. Quality Improvements
 53  
 54  **Fixed issues during conversion:**
 55  
 56  1. **Removed "lookers"** - awkward word → replaced with "customers"
 57  2. **Standardized grade notation** - "grade of C-" → "C-" or "C-minus"
 58  3. **Removed "a third"** - not equivalent to "20-40%" → removed
 59  4. **Fixed "not unusual"** - tone mismatch → removed
 60  5. **Standardized capitalization** - "Home Page Audits" → "Homepage Audits"
 61  6. **Fixed typo** - "didnt" → "didn't"
 62  7. **Removed duplicate "change"** - subject line had redundant wording
 63  8. **Fixed tense inconsistency** - "made/kept" → consistent "kept"
 64  9. **Improved competitor phrasing** - "finish up hiring" → "end up hiring"
 65  
 66  ## Templates Created
 67  
 68  ### Email Templates (6)
 69  
 70  1. **email_pauljames_01** - C-minus score, problem-solution (1,728 variations)
 71  2. **email_dad_01** - Quick breakdown offer, casual (512 variations)
 72  3. **email_dad_02** - Homepage audit focus, helpful (144 variations)
 73  4. **email_dad_03** - Conversion optimization, friendly (1,152 variations)
 74  5. **email_dad_04** - Professional value-focused (1,152 variations)
 75  6. **email_dad_05** - Direct problem-focused (12 variations)
 76  
 77  ### SMS Templates (1)
 78  
 79  1. **sms_pauljames_01** - Quick homepage review, casual (18 variations)
 80  
 81  **Total unique combinations: 4,718 emails + 18 SMS = 4,736 unique messages**
 82  
 83  ## Subject Line Consolidation
 84  
 85  Converted 40+ subject lines from `sendcheckit.com` into **6 spintax patterns**:
 86  
 87  ```
 88  1. {is your [kwd] site doing its job|does your [kwd] site...}?
 89  2. {what|this} {one|1} {homepage fix|change}...?
 90  3. {what if {one|1} homepage {fix|change} kept searchers longer...}?
 91  4. {how to keep more visitors on your homepage}?
 92  5. {does your [kwd] {site|web site} {make customers call you|trigger phone calls}}?
 93  6. {sorry, your [kwd] site isn't as good as it could be|is your [kwd] site losing you work}
 94  ```
 95  
 96  These 6 patterns generate **100+ unique subject lines** per keyword.
 97  
 98  ## Usage
 99  
100  ### CLI Tool
101  
102  ```bash
103  # List all templates
104  node scripts/test-spintax.js --list
105  
106  # Test a template
107  node scripts/test-spintax.js email_pauljames_01 --count 10 --kwd plumbing --firstname Alice
108  
109  # Validate spintax syntax
110  node scripts/test-spintax.js email_dad_03 --validate
111  
112  # Test all templates
113  node scripts/test-spintax.js --all --kwd electrician
114  ```
115  
116  ### In Code
117  
118  ```javascript
119  import { loadAndSpinTemplate } from './src/utils/spintax.js';
120  
121  // Load and spin a template
122  const proposal = await loadAndSpinTemplate('email_pauljames_01', {
123    kwd: 'plumbing',
124    firstname: 'Alice',
125  });
126  
127  console.log(proposal.subject);
128  // "is your plumbing site doing its job?"
129  
130  console.log(proposal.body);
131  // "Hey Alice!\n\nI was looking at your website earlier..."
132  ```
133  
134  ### Manual Spintax
135  
136  ```javascript
137  import { spin, generateVariations } from './src/utils/spintax.js';
138  
139  // Generate one variation
140  const text = spin('{Hello|Hi|Hey} [firstname]!');
141  // Then replace [firstname] with actual name
142  
143  // Generate multiple unique variations
144  const variations = generateVariations('{Hello|Hi|Hey} world!', 10);
145  // ["Hello world!", "Hi world!", "Hey world!"]
146  ```
147  
148  ## Testing
149  
150  All 23 unit tests pass ✅
151  
152  ```bash
153  npm test tests/spintax.test.js
154  ```
155  
156  **Tests cover:**
157  
158  - Spintax parsing (simple, nested, edge cases)
159  - Variation generation (uniqueness, limits)
160  - Validation (syntax errors, deep nesting)
161  - Real template integrity
162  
163  ## Next Steps
164  
165  ### Phase 1: Manual Template Selection (Now)
166  
167  - Developer chooses template per campaign
168  - Track conversion rates by template_id
169  
170  ### Phase 2: A/B Testing
171  
172  - Randomly assign templates to outreaches
173  - Measure performance by template
174  
175  ### Phase 3: Adaptive Selection
176  
177  - ML model selects best template per prospect
178  - Based on: industry, score, location, contact method
179  
180  ### Phase 4: Hybrid Approach
181  
182  - Templates for proven patterns (fast, cheap, consistent)
183  - LLM for edge cases and deep personalization
184  - Best of both worlds
185  
186  ## Database Schema Addition
187  
188  Add `template_id` to outreaches table:
189  
190  ```sql
191  ALTER TABLE outreaches ADD COLUMN template_id TEXT;
192  ```
193  
194  Then track performance:
195  
196  ```sql
197  SELECT
198    template_id,
199    COUNT(*) as sent,
200    SUM(CASE WHEN replied = 1 THEN 1 ELSE 0 END) as replies,
201    ROUND(SUM(CASE WHEN replied = 1 THEN 1 ELSE 0 END) * 100.0 / COUNT(*), 2) as conversion_rate
202  FROM outreaches
203  WHERE template_id IS NOT NULL
204  GROUP BY template_id
205  ORDER BY conversion_rate DESC;
206  ```
207  
208  ## Files Created
209  
210  1. `/data/templates/email-templates.json` - Template definitions
211  2. `/src/utils/spintax.js` - Spintax parser and utilities
212  3. `/tests/spintax.test.js` - Unit tests (23 tests)
213  4. `/scripts/test-spintax.js` - CLI tool for testing templates
214  5. `/docs/SPINTAX-TEMPLATES.md` - Complete documentation
215  6. `/docs/TEMPLATE-IMPLEMENTATION.md` - This summary
216  
217  ## Advantages Over LLM Generation
218  
219  **Templates:**
220  
221  - ✅ **Fast**: No API calls (instant generation)
222  - ✅ **Cheap**: Zero LLM cost
223  - ✅ **Proven**: Battle-tested by Paul James & Dad
224  - ✅ **Consistent**: Same voice and quality every time
225  - ✅ **Scalable**: Generate 1000s of unique variations
226  - ✅ **Predictable**: No hallucinations or tone drift
227  
228  **LLM:**
229  
230  - ✅ **Personalized**: Deep customization per prospect
231  - ✅ **Adaptive**: Can adjust to any business type
232  - ❌ **Slow**: API latency (2-5 seconds)
233  - ❌ **Expensive**: $0.001-0.01 per proposal
234  - ❌ **Variable**: Quality inconsistency
235  
236  **Best Strategy: Hybrid**
237  
238  - Use templates for 80% of prospects (standard cases)
239  - Use LLM for 20% (high-value, complex, or edge cases)
240  - Massive cost savings + maintained quality
241  
242  ## Example Output
243  
244  ```
245  Subject: is your plumbing site doing its job?
246  
247  Hey Alice!
248  
249  I was looking at your website earlier and noticed your homepage offer score is about a C (don't worry — most local businesses are in that range).
250  
251  Nothing is "broken," but you're likely missing out on at least 20-40% more leads just from the way your offer and call-to-action are structured above the fold.
252  
253  I do Local Offer Fix Audits that break this down and show exactly what to change for fast lead increases.
254  
255  It's a simple one-time service — takes me about 24 hours — and the audit is yours to keep.
256  
257  Want me to send over what I found?
258  ```
259  
260  **Stats for this template:**
261  
262  - 2 subject variations × 864 body variations = **1,728 unique emails**
263  - All read naturally with consistent voice
264  - Zero LLM cost