Canonical Article Flow

1. Opening block – title, single-metric hook, target role(s), reading time, prerequisites, and urgency.
2. TL;DR – concise, outcome-focused summary with measurable value.
3. ⚠️ Disclaimer – always include immediately after the TL;DR:

   ⚠️ Disclaimer: All scenarios, accounts, names, and data used in examples are not real. They are realistic scenarios provided only for educational and illustrative purposes.

4. Problem Definition – audience, stakes, and why current approaches fail.
5. Solution Implementation – numbered phases with runnable code, infra steps, and diagrams.
6. Validation & Monitoring – automated tests, metrics, dashboards, fallback plans.
7. Takeaways + Next Steps – highlight lessons, decision frameworks, and future work.
8. References – numbered list using the format: 1. Title - [Full Title, Year](URL).

Callout System

• ℹ️ Note – background context.
• ❗ Warning – risks, failure modes, or breaking changes.
• 💡 Tip – optimizations and shortcuts.
• Only one disclaimer callout (⚠️) per article and it must follow the TL;DR automatically.

Code & Diagram Expectations

• Supply full imports, environment variables, and realistic sample data.
• Provide both success and failure cases; highlight validation routines and monitoring hooks.
• Mermaid diagrams must include descriptive labels for every node/edge and provide a static SVG fallback (rendered via @mermaid-js/mermaid-cli).
• When referencing ACH/wire IDs, prefer canonical samples: routing 061000052, account 123456789, amounts in cents (e.g., 12500 for $125).

SEO & Accessibility

• Use descriptive H2/H3 headings; avoid vague labels.
• Include alt text for every image and diagram (mirrors _includes style).
• Keep paragraphs short (3–4 sentences) with intentional spacing for readability.
• Add internal links to related series (/series/payments, /series/leadership, etc.).
• For excerpt/meta description, write 150–160 character summary focusing on outcome + audience.

Front Matter & Template References

• Mirror the front matter schema from templates/article-template.md; minimum keys:

  ---
  layout: post
  title: "Handling ACH Returns When Data Is Broken"
  categories: ["payments"]
  tags: ["ach", "risk"]
  canonical_url: "https://buildtales.dev/handling-ach-returns-missing-broken-data/"
  excerpt: "Staff playbook for tracing ACH returns with missing tokens and broken files."
  ---
  

• Include permalink when the slug must differ from the title.
• Use the urgency metric callouts (“Time to implement”, “Who needs this”) exactly as shown in templates/article-template.md.

Output Packaging

• Blog-ready Markdown lives under _posts with permalink: /:title/.
• Medium/Substack automation relies on the CI scripts in package.json — ensure new articles pass npm run ci:all.
• Avoid embedding HTML unless layout absolutely requires it; prefer Markdown + _includes.

Do / Don’t

• Do follow the template order; never skip sections even if content feels short.
• Do restate numeric results inside TL;DR and validation sections to reinforce measurability.
• Don’t introduce new callout emoji styles or colors; stick to ⚠️ ℹ️ ❗ 💡.
• Don’t end articles without references—minimum one authoritative citation per major claim.