When I look at internal GitHub Discussions and docs with my manager hat on, I keep hitting the same pattern: the engineering discussion is rich and well-argued, but I still can’t quickly tell what this product is actually going to do next quarter, or when other teams will be affected. The root cause isn’t poor writing on the engineers’ side. It’s that writers (engineers in the thread) and readers (managers, execs, peer-team leads) need information at fundamentally different levels of detail.

For a while now, I’ve been leaving variations of the same comment to engineers on my team: “Just leave the context somewhere in the GitHub repo. With that, I can use AI to summarize at whatever granularity I need and make decisions. You don’t need to write a polished manager-facing version separately. Flow or stock, either form is fine, just leave what you currently know in the repo.”

This post generalizes that ask from the manager side. I’ll point at concrete tools like Claude Code and Codex as examples, but the names are illustrative. The substance is the workflow: as long as context lives in the repo, the manager-facing summarization can be absorbed by AI.

What a Manager Actually Wants to Read Is Decision-Grade, Not Implementation-Grade

Engineering discussions tend toward depth: implementation alternatives, tradeoffs, past context, edge cases. That depth is healthy, and I want it to keep being written at full density. Compressing it would sacrifice decision quality. That’s the baseline assumption on the manager side too.

When a manager, exec, or peer-team lead reads the same Discussion or Issue, the questions are coarser:

• By when, how far, do we expect to get?
• Does this affect another team’s schedule?
• Do we need additional headcount, budget, or executive judgment?
• If the risk materializes, what breaks, and how badly?

Those answers are almost never written explicitly in the thread. They can be reconstructed by reading carefully, but a manager watching multiple products simultaneously can’t realistically grind through the daily volume of Discussions as primary sources.

Asking engineers to write a separate “translated for managers” doc on top of the technical discussion is, from my side, a waste of their cycles. The gap between detailed engineering discussions and decision-making should be absorbed by AI on top of context that already lives in the repo, not by additional writer load.

The One Thing I Ask of Engineers — Leave the Context in the Repo

The single ask I have from engineers is simple: leave the context somewhere in the GitHub repo.

“Context” here isn’t restricted to a particular form. Flow information or stock information, either form is welcome.

• Confirmed information belongs as stock information, committed to in-repo docs (README, docs/, ADR, etc.)
• Unconfirmed but current thinking belongs as flow information, dumped into a Discussion or Issue, however messy

What I need is “the context in your head is visible somewhere in the repo.” With that, I can throw questions at AI like “what’s likely to happen next quarter,” “where are the risks,” or “which other teams are affected,” and pull answers at the granularity I need.

It also helps to be explicit about what I’m not asking for:

• A separately-authored “executive summary” document
• Weekly status slides reformulating the progress
• A Markdown report repackaging one Issue’s discussion

If context is in the repo, all of these can be absorbed by AI. I don’t want engineers to spend their finite hours on them.

Distinguishing Flow Information and Stock Information

Flow and stock are familiar concepts in engineering communities, but worth restating. When leaving context in the repo, the only thing the writer needs to ask is “is this flow or stock?” and pick the venue accordingly.

Flow Information — Snapshots in Time

• Venue: Discussions, Issues
• Style: messy is fine, leave the thought stream raw, close aggressively once resolved
• Examples: “this week’s interim conclusion,” “my current understanding,” “tentative direction as of today”

Content along the lines of “this is my decision as of today, but it might change tomorrow” or “this is my current understanding, which might be rewritten next week” can be dumped into a Discussion or Issue messily. No need to polish. Leaving the thought stream raw actually helps when someone retraces the reasoning later. As a writer, the default mode is “write freely, close aggressively.”

Stock Information — Information That Persists

• Venue: committed to in-repo docs (README, docs/, ADR, and similar)
• Style: organized, meaningful at a granularity that holds up six months later
• Examples: the roadmap, design rationale, API specs, operational guidelines

Stock information is the kind of content “a teammate joining six months from now should still be able to read and follow.” Concretely, that maps to README, docs/, ADR (Architectural Decision Records), and other in-repo documentation that’s committed alongside the code.

The writer only needs to ask “is this flow or stock?” and pick the venue. That alone makes Discussions and Issues a comfortable place to write loosely, and the repo a place that holds up to long-term reference.

On the manager side, flow information is something I’ll let AI sweep up later, so engineers can leave it raw. For stock information, I don’t lean solely on AI summaries; I read the primary source as a matter of policy.

Prompts I Actually Run on the Manager Side

It probably helps engineers calibrate the right level of writing if they know what kind of summarization the manager side is running. A few prompts I use regularly.

Example 1: AWS Cost Optimization — Savings Plans for Fargate and Reserved Instances for RDS

When the team reviews infrastructure costs and considers shifting compute like Fargate from Fargate On-Demand pricing to Savings Plans, and shifting RDS to Reserved Instances on AWS, that’s squarely a manager-level decision. It involves a one- or three-year commitment, financial risk if the commitment goes unused, and a tradeoff between peak-time flexibility (On-Demand) and discount depth (SP/RI). There’s financial judgment in there that engineers can’t and shouldn’t make alone.

If the current Fargate / RDS usage and the team’s infrastructure direction are in the repo (docs/ or Discussion, flow or stock), I ask AI:

Read the attached usage log and infrastructure-direction memo. Compare Compute Savings Plans applied to Fargate against Reserved Instances for RDS (1- or 3-year term, with upfront-payment options). For each option, roughly compare: expected discount rate, commitment period, flexibility tradeoffs, and fit with the current usage pattern. End with three items I should verify with other teams before deciding.

The comparison won’t be perfectly accurate, but it surfaces the points I actually need to settle in a decision meeting (one-year vs three-year commitment, how much of Fargate’s variable load to lock under Compute SP, what upfront ratio to pick for RDS RI). As long as engineers have left “current usage” and “expected workload changes ahead” as context in the repo, a manager-level reader can sketch the decision framework with AI assistance. If neither usage nor direction lives in the repo, AI can only return generic advice, and I end up bouncing follow-up questions back to the engineers on the ground.

Example 2: Catching Up on a Product Whose Documentation Is Thin

For onboarding into a product I haven’t been close to, or one whose docs are thin, I lean on AI to reconstruct the last 90 days.

Read the past 90 days of PRs, Discussions, and Issues in this repo. Group the in-flight themes into three to five categories. For each, summarize: who is currently driving it, what the next milestone is, and any blockers.

The key observation here, and the direct reason I keep asking engineers for “just leave the context”: if any context exists in the repo (flow or stock), AI weights it heavily in its reconstruction. If neither flow nor stock has been written down, AI falls back to inference, and my verification cost on the manager side balloons. That’s why “please leave the context in the repo” is the one ask I keep repeating.

Example 3: Summarizing a Long Thread

Summarizing long Discussions is squarely in AI’s strengths:

Read this entire thread. Bullet, in five lines or fewer, what’s important for a decision-maker. Tag items requiring a decision with “[needs decision]”.

The writer keeps the discussion thick. The reader controls granularity on their own side. A division of labor that makes both sides happier.

Make “Approximate Is Fine” an Explicit Org Norm

The single most important enabler is the manager side explicitly declaring “approximate is fine” and “flow or stock in the repo is enough” as policy, not as a private opinion.

What writers dislike most is being asked to write provisional information as if it were finalized. A culture where management expects “give me the accurate version once” slows engineers down with the pressure of producing a polished document.

If the manager explicitly states “leave unconfirmed thinking as flow in Discussions or Issues; commit confirmed content to docs/ or README in the repo; the rest is absorbed by AI on my side,” engineers can write down “what I currently know” without anxiety.

This declaration helps both sides. Engineers’ psychological load drops, and the manager benefits too: a half-finished signal that arrives early reduces decision latency more than a polished doc that arrives late.

Closing — To the Engineers on My Team

To wrap up, the manager-side ask for engineers in this organization:

• Leave the context in the GitHub repo. Flow information or stock information, either form is welcome
• Unconfirmed information goes into Discussions or Issues as flow. Write freely, close aggressively. No need to polish
• Confirmed information goes into README, docs/, or ADR as stock. Aim for granularity that’s still meaningful to a teammate joining six months later
• You don’t need to produce manager-facing summary docs. With context in the repo, the manager side will absorb the summarization with AI
• Trust “approximate is fine.” You don’t have to write provisional things as if they were finalized

As long as the basic precondition (context in the repo) is met, the era is shifting from “the writer absorbs the granularity gap” to “AI on the reader side absorbs it.” That guarantees more time for engineers to focus on what only they can do: deep thinking, implementation, and technical debate.

That’s all from the gemba, working as a manager building AI-aided workflows inside a fully-remote engineering organization.

References

• Claude Code
• OpenAI Codex