Dear AI: Humans Still Have to Read This

The Return of TL;DR

Remember when we all complained about commit messages like fix stuff and JIRA tickets that just said "broken pls fix"? We wanted context. We begged for context. We wrote blog posts about the importance of context.

Well, congratulations. We got context.

We got so much context that I recently scrolled through a 1,800-word AI-generated pull request description — complete with architectural diagrams rendered in ASCII, a philosophical meditation on the nature of null values, and three "Considerations for Future Work" — only to discover the PR fixed a typo in a log statement.

The pendulum, as pendulums do, has swung. And now the humble TL;DR is creeping back into our tickets and PRs like a houseguest we thought we'd finally gotten rid of.

Here's the thing though: the context isn't the problem. The format is. We've been writing one document for two very different audiences — humans who need to make a decision in the next 30 seconds, and machines (increasingly, agents) who need structured, reliable data to act on later. It's time we stopped pretending those are the same job.

The Great Wall of Context: How We Got Here

Before AI got its hands on our developer tooling, documentation existed on a spectrum from "cryptic" to "nonexistent." Commits said things like wip and final_v2_actually_final. JIRA tickets were three-word haikus of despair. Tribal knowledge reigned supreme, and onboarding a new engineer felt like initiating them into a mystery cult.

Then the LLMs arrived, and they had opinions. Lots of them.

Suddenly every PR came with a preamble, a summary, a detailed breakdown, a testing strategy and a rollback plan. JIRA cards started reading like technical dissertations. Incident reports grew appendices. Everything was thorough. Everything was complete. Everything was exhausting.

The rich data itself is a feature, not a bug. Agents downstream need that structure. RAG pipelines love it. Changelog generators eat it up. But when you dump all of it into a single flat document meant for human eyes, you've optimized for neither audience. You've built a wall of text that humans skim and machines have to parse with regex and prayer.

Two Audiences, One Ticket: The Case for the Split

Here's the shift I feel we are headed towards: every AI-generated artifact should have two distinct sections — a human-readable summary and a machine-readable payload.

The human section answers three questions, fast:

• What changed?
• Why does it matter?
• Where should I look?

The machine section carries the freight:

• Structured metadata
• Cross-references to tickets, commits, and specs
• Context blocks tuned for embeddings and agent handoff
• Whatever your downstream automation actually consumes

What I'm suggesting is a structural shift in how we design these artifacts — treating them like API responses with a summary field and a data field.

The Pros: Why This Split Actually Helps

Faster human triage. Code reviewers can decide in seconds whether a PR needs a deep dive or a quick approval. Product managers can scan tickets without losing an afternoon.

Better downstream agent consumption. When your machine block is structured and predictable, RAG systems retrieve better, autonomous agents plan better, and changelog generators stop hallucinating features you didn't ship.

Cleaner audit trails. Compliance and security teams can point their tooling at the structured block and get consistent, parseable answers.

Reduced cognitive load. Nobody has to hold 1,800 words in their head to review a 20-line diff.

Easier onboarding. Juniors skim the summaries and learn the shape of the work. Seniors dive into the details when it matters. Everyone wins.

The Cons: More Stuff

Duplication risk. Two representations of the same information can drift apart. If your human summary says "refactored the auth module" and the machine block says "updated logging config," someone's going to have a bad day.

More template maintenance. Prompts get more complex. Templates need governance. Someone owns this now.

Schema sprawl. You'll have opinions about YAML vs. JSON vs. front matter, and so will everyone else.

Over-terse summaries. In an effort to be brief, the human section can lose the nuance that made rich context valuable in the first place. Brevity is a skill, and not everyone has it — including the AI you delegated it to.

Political overhead. Who owns the format? Platform? DevEx? The tech lead with the strongest opinions?

Examples in the Wild

Here's what this looks like in practice.

Before: The Word Wall

 1## Pull Request: Update User Authentication Flow
 2
 3This pull request introduces a series of changes to the user authentication
 4flow within the application. The primary motivation for these changes stems
 5from a need to improve the overall security posture of the authentication
 6system while simultaneously enhancing the user experience during login...
 7
 8[1,600 more words]
 9
10...and finally, we should consider in future iterations whether the token
11refresh interval should be made configurable per environment.

You've read this PR. You've written this PR. We've all done it.

After: The Split Format

 1## Summary
 2Fixes a race condition in token refresh that caused ~2% of users to be
 3logged out mid-session. Touches `auth/token.ts` and adds one integration test.
 4
 5**Risk:** Low. **Review focus:** `refreshToken()` retry logic.
 6
 7## Details
 8[The actual explanation, but scoped and scannable — maybe 200 words]
 9
10## Machine Context
11​```yaml
12change_type: bugfix
13affected_modules:
14  - auth/token
15  - auth/session
16related_tickets: [AUTH-1421, AUTH-1389]
17risk_level: low
18test_coverage_delta: +1.2%
19rollback_strategy: revert_safe
20agent_handoff:
21  followups:
22    - monitor_error_rate: auth.token.refresh
23    - notify: security-team
24​```

Same information. Radically different ergonomics.

A JIRA Card, Split

 1## What
 2Checkout page throws 500 when cart is empty and user applies a coupon.
 3
 4## Why it matters
 5Blocks ~40 users/day from completing purchase after removing items.
 6
 7## Where to start
 8`checkout/coupon-validator.ts`, line 87-ish.
 9
10<details>
11<summary>Machine Context</summary>
12
13​```yaml
14severity: P2
15customer_impact: 40_users_daily
16error_signature: "TypeError: cannot read 'total' of undefined"
17first_seen: 2024-11-03T14:22:00Z
18related_incidents: [INC-2201]
19​```
20</details>

Collapsible sections help here. Humans see the summary. Agents (and curious humans) expand the block.

An Incident Post-Mortem

Human summary drives the retrospective meeting. Machine block feeds the incident-analysis agent that builds trend reports across quarters. Same document. Two jobs. Zero conflict.

How to Improve the Process

1. Establish a team-wide template. Pick your sections and stick to them. Something like ## Summary, ## Details, ## Machine Context.

2. Use collapsible sections or fenced code blocks. The machine payload shouldn't visually compete with the human summary. Hide it, fold it, or fence it — but keep it out of the way of the eyes that need to move fast.

3. Standardize on a schema. YAML front matter, JSON blocks, whatever — just pick one. Document it. Version it. Treat it like an API contract, because that's what it is now.

4. Tune your prompts. Instruct the AI to produce two things, not one long thing. Give it explicit instructions about audience and length for each section. "Summarize in under 100 words for a human reviewer; then output structured metadata for downstream agents" beats "write a good PR description".

5. Lint the machine block. If it's structured, validate it. Schema validation in CI is cheap insurance against silent drift.

6. Review the summaries like you review code. Brevity is a skill. If the human summary is bloated, send it back. Treat it as part of the deliverable, not decoration.

7. Talk to your downstream consumers. If agents, dashboards, or automations are eating this data, find out what they actually need. Design the machine block for them, not for a hypothetical future use case.

The Great Wall of Context, Reconsidered

Here's why this matters now, and not in some hypothetical future:

Agentic workflows are eating the software development lifecycle. The tickets, PRs, and post-mortems you write today become the context, training data, and memory for the agents you'll deploy tomorrow. If those artifacts are word walls, your agents will be confused. If they're structured, your agents will be useful.

We're at an inflection point where the artifacts of software development are simultaneously human documentation and machine substrate. Pretending those are the same thing gives you the worst of both worlds: humans skimming past important details and agents hallucinating from unstructured prose.

A small structural investment now — a template, a schema, a habit — pays back enormously over the next few years as more of your workflow becomes agent-mediated.

Closing Thoughts

The goal here isn't less information. It's better-placed information. One document, two audiences. Humans get their summary. Machines get their payload. Nobody has to read a 1,800-word essay to approve a typo fix.

Got a template or format that's working for your team? I'd genuinely like to hear about it — this is one of those problems where the answer is going to emerge from practice, not theory.