Content Production Workflow

1. Research – validate regulatory references, confirm API limits, gather metrics.
2. Outline – progressive complexity: fundamentals → architecture → operations.
3. Draft – pair Cursor with .cursorrules + scoped rule file; keep tokens lean by referencing only needed sections.
4. Technical Review – cross-check code, diagrams, compliance claims.
5. Compliance & UX Review – confirm accessibility, alt text, and regulatory accuracy.
6. Publish – run npm run ci:all (diagrams, GitHub URLs, compiled markdown, snippets) before merging.

Automation References

• Scripts live in package.json. Key commands:
  • npm run ci:render → tools/render-mermaid.mjs
  • npm run ci:github-urls → tools/generate-github-urls.mjs
  • npm run ci:build → tools/compile-markdown.mjs
  • npm run ci:snippets → tools/generate-snippets.mjs
• Follow SETUP_GUIDE.md for environment prerequisites (Node 20+, Medium tokens, Zapier hooks).
• Update ANALYTICS_GUIDE.md and IMAGE_GUIDE.md whenever automation requirements shift.

Testing & QA Checklist

• Contact form submits successfully (including reCAPTCHA and Formspree handoff).
• Series navigation links (_includes/series_nav.html) point to the right posts.
• Banner images load on desktop + mobile.
• Search index (search.json) works across major posts.
• Responsive layout verified via dev tools.
• Analytics events fire (GA4 debug view) for key user interactions.
• Social share buttons call the correct URLs with query parameters.
• Comments (Giscus) load without CSP issues.

JavaScript Standards

• Prevent default on all async form submissions; show loading states and inline errors.
• Wrap network calls with try/catch, log structured errors, and emit GA4 failure events.
• Lazy-load heavy assets where possible; use async/defer for third-party scripts.
• Provide fallback UI (e.g., contact via LinkedIn) when forms or tokens fail.

Netlify & Env Hygiene

• Document every required env var inside netlify.toml comments or README updates.
• Never print secrets in front-end logs; rely on Netlify functions for sensitive work (Formspree calls, reCAPTCHA validation).
• Keep the inject-env plugin up to date when adding new variables that must appear in built HTML.

Analytics & Monitoring

• Track: scroll depth milestones, CTA clicks, newsletter submissions, errors, contact form statuses, outbound link taps.
• Use descriptive GA4 event names (contact_submit_success, ach_diagram_expand, etc.).
• When publishing new features, add success metrics and instrumentation steps to the article itself so readers can reproduce.

Do / Don’t

• Do attach GA4 debug screenshots or metrics callouts when shipping new features; store them in ANALYTICS_GUIDE.md if reusable.
• Do treat npm run ci:all failures as blockers—include remediation steps in PR descriptions.
• Do add new checklist items whenever you create reusable automation (e.g., Substack exporter) so QA keeps pace.
• Don’t bypass diagram rendering; Mermaid blocks must always have SVG fallbacks before publishing.
• Don’t commit drafts that skip validation steps, even if they’re WIP—use unchecked boxes plus TODO comments to track work.
• Don’t rely on memory for env settings; update env.example whenever secrets/configuration changes.