The Treehouse Problem

A story about why teams need consistent communication

Imagine you are building a treehouse with your friends. Sarah is in charge of the ladder, Marcus is building the walls, and you are working on the roof. Every day you need to tell each other what you did, what you decided, and what questions you still have.

Now imagine you each write updates on sticky notes. Sarah writes in cursive, Marcus draws pictures, and you use abbreviations only you understand. Pretty soon, nobody knows what is happening. The treehouse project falls apart.

📝

Sarah's cursive

Hard to read

🎨

Marcus's drawings

Open to interpretation

🔤

Your abbreviations

Only you understand

The Solution

Engineering teams have the same problem. ETMF fixes this by providing a standard format for team updates, like how a recipe always lists ingredients before instructions.

What is ETMF?

Engineering Team Messaging Format (ETMF) is a specification that defines how engineering teams should structure their project updates. When everyone uses the same format:

Tools can parse it

Automated systems can read and organize updates

Teams can find info

Everyone knows exactly where to look

Nothing gets lost

Important details have a defined home

History is readable

Updates from six months ago are just as clear

Message Structure

Raw Message
Frontmatter

Metadata like the label on a jar

Body

The actual content inside the jar

The frontmatter starts and ends with three dashes (---). It contains structured data in YAML format. The body is everything after the closing dashes, written in Markdown.

Version 1.0.0

A Complete Example

Here is what a real ETMF message looks like. Notice how the frontmatter contains metadata, and the body has clear sections for different types of information.

weekly-update.etmf
---
etmf: 1.0.0
project: user-authentication-system
team: platform-security
author: jamie.chen@company.com
date: 2026-09-08
update_type: weekly
priority: normal
tags:
  - security
  - api
  - q3-milestone
---

## Summary

This week we finished the password reset flow and started 
work on two-factor authentication.

## Progress

### Completed
- Password reset emails now send within 5 seconds
- Added rate limiting: max 3 reset requests per hour
- Fixed bug where special characters broke the reset link

### In Progress
- Two-factor authentication using authenticator apps
- SMS backup codes for users without smartphones

### Blocked
- Cannot test SMS until we get Twilio API credentials

## Decisions

### Decision 1: Use Time-Based OTP for 2FA
- **What**: Using TOTP instead of HOTP
- **Why**: Codes expire after 30 seconds, more secure
- **Decided by**: Security review board
- **Date**: 2026-09-05
- **Reversible**: Yes, but would require app updates

## Deferred

1. **Passwordless login** - Out of scope for Q3
2. **Biometric auth** - Needs hardware research first
Schema Reference

Frontmatter Fields

The frontmatter contains metadata about your message. Some fields are required, others are optional. Here is the complete reference:

Required Fields

etmf
Required
string

Specification version (e.g., '1.0.0')

project
Required
string

Project identifier in kebab-case (e.g., 'user-auth-system')

author
Required
string

Email of the author (e.g., 'jamie@company.com')

date
Required
string

ISO 8601 date (e.g., '2026-09-08')

Optional Fields

team
string

Team identifier (e.g., 'platform-security')

update_type
enum

Type: daily, weekly, milestone, incident, decision, general

priority
enum

Priority: critical, high, normal, low

tags
array

Searchable labels for categorization

reply_to
string

ID of parent message for threading

expires
string

Date when this update becomes stale

Content Structure

Body Sections

The body uses Markdown formatting with specific sections. Use what you need, skip what you do not.

Summary

One or two sentences explaining the main point. If someone only reads this, they should understand what happened.

Progress

What got done (Completed), what's in progress (In Progress), and what's stuck (Blocked).

Decisions

Important choices the team made. Include what, why, who decided, when, and if it's reversible.

Deferred

Work the team identified and chose to push further down the road, so the idea is not forgotten.

Other Optional Sections

Context
Questions
Risks
Links
Next Week
Metrics
Shoutouts
For Tool Developers

Validation Rules

Tools that consume ETMF messages should validate them. Here is how to classify a message as valid, warning, or invalid:

VALID

  • • Frontmatter contains all required fields
  • • etmf version is recognized
  • • date is valid ISO 8601
  • • update_type and priority are known values (if present)

WARNING

  • • No Summary section in body
  • • No Progress or Decisions section
  • • Unknown fields in frontmatter (preserve them)

INVALID

  • • No frontmatter found
  • • Frontmatter YAML is malformed
  • • Missing required fields (etmf, project, author, date)
Migration Example

Before and After

Here is what a typical email looks like before and after adopting ETMF:

Before: Unstructured Email

Subject: Auth update

Hey team,

Finished the password stuff. Starting 2FA tomorrow.

Marcus made a call on using TOTP.

- Jamie

  • • No structure for tools to parse
  • • Decision details missing
  • • Hard to search later

After: ETMF Format

---
etmf: 1.0.0
project: user-auth
author: jamie@co.com
date: 2026-09-08
---

## Summary
Finished password reset.
Starting 2FA tomorrow.

## Decisions
### Use TOTP for 2FA
- **Decided by**: Marcus
  • • Tools can parse and index
  • • Decisions are documented
  • • Easy to search and filter

Key takeaways

1

Frontmatter is your label

Put metadata at the top so tools and people can quickly understand what the message is about.

2

Sections create consistency

Summary, Progress, Decisions, and Deferred give every update the same structure.

3

Versioning enables evolution

The etmf field lets old messages stay valid while the spec improves.

4

Start simple, add as needed

A quick update might only need Summary. A milestone might use every section.

Get Started

Ready to try ETMF? Start with your next weekly update. Use just the required frontmatter fields and a Summary section. Add more structure as your team finds it helpful.

Minimal ETMF Message
---
etmf: 1.0.0
project: your-project-name
author: your.email@company.com
date: 2026-09-08
---

## Summary

Your one or two sentence update goes here.

Remember

ETMF is designed to be simple enough for humans to write by hand, and structured enough for machines to parse automatically. Start simple, add complexity only when you need it.

Questions I get asked

Do I have to use every section?

No! Use what makes sense. A quick daily update might only have Summary and Progress. A big milestone might have everything.

Can I add my own sections?

Yes! The spec defines recommended sections, but you can add custom ones. Just use ## headers. Unknown fields in frontmatter are preserved, not discarded.

Why not just use Jira, Slack, or Notion?

ETMF is not a replacement for those tools. It is a format those tools can import, export, and understand. Your Jira bot could generate ETMF updates. Your Slack messages could follow ETMF structure.