Give the Line the Context the Repo Cannot

Linear's first attempt at automatic bug fixing pointed a coding agent at every bug that arrived. It did not work. The agent could read the code, but it could not see what an engineer at Linear knows the moment a bug lands: whether the failing job is a known flake, which team answers for it, what a correct fix has to leave alone. Linear's own write-up says the agent lacked the context to fix bugs in one shot, and that for messy failure types the fix came out right only about one third of the time (Linear, self-reported and anecdotal, observed 2026-10-28). The failure was easy to miss, because every attempt still produced a plausible pull request, and each one cost a reviewer a read. Now point the same agent at your billing service. The diff is tidy and the tests pass. Nothing in the repository says the service faces customers, that three other systems parse its output, or that finance must sign off on any change to rounding. Decide now: who tells the line those facts, where do they live, and which gate reads them before a human is asked to approve?

This lesson gives you factory/context-map.md - each context fact the line needs, where it lives, who keeps it fresh and which gate reads it. It serves the Wrap stage of the course loop: after the line has owners, versions and identities, it also gets the facts about the world around the code, so its gates can route approval instead of guessing.

What is actually going on

A repository describes code. A gate decision often depends on something else: the code's place in the organization. Who owns the service. How much of the business sits on it. Which other systems break if its behavior shifts. Whether a named human must approve. What the ticket said a correct result looks like. None of those can be computed from a diff and a checked-out tree, so an agent that cannot ask a colleague has two options: stop, or fill the gap with a guess. A fact the line cannot read is a fact the line will guess. The guess then looks like any other decision, because the pull request carries no mark saying "tier assumed."

Three company write-ups show the same gap from three sides. Cloudflare reports that its first agents made plausible but wrong changes because they lacked local context: test commands, conventions and areas that were off limits (Cloudflare, first-party, observed 2026-10-28). Its answer was to expose its Backstage catalog, with 2,055 services and 375 teams, to agents as ownership and dependency lookups, and to generate a context file per repository from that catalog, opened as a merge request so the owning team reviews what the agent will be told (Cloudflare, first-party, observed 2026-10-28). Atlassian's reviewer agent pulls acceptance criteria from the Jira work item linked to the pull request, so the review checks against the ticket and not against its own taste (Atlassian, vendor product blog, observed 2026-10-28). And Atlassian's engineers had already found that tickets short on detail, or ones that only link to a chat thread, rarely came back finished (Atlassian engineering, observed 2026-10-28).

This is not the same problem as Lesson 9. Readiness asks whether the repo can be worked on at all: can the agent build it, is the default branch green. The context map asks whether the line knows where this particular change sits. A repo can score gold on readiness and still have no field anywhere that says its tier. The ticket side of this map extends the task template from Agent Fleets, lesson 2, and the reasoning that context is architecture and that grounding data needs an owner is in AI Solutions Architect, lessons 5 and 6. Harness Engineering, lecture 17, covers the single-agent side of the same problem.

The diagram shows where each kind of fact lives and which gate consumes it.

Every gate on the right reads from the map and not from the model's memory of the repo. The map is the one place where a missing fact is visible, because an empty cell is a row someone can see.

The rule and its condition

Use a context-map entry when a gate's decision depends on a fact that cannot be computed from the diff and the checked-out tree. Otherwise leave the fact in the repo, in the instruction file or the README, where it is versioned with the code. Every entry needs four things: a home outside anyone's memory, a keeper, a stale-after rule, and a default for when the fact is missing.

The condition is observable in your own history. Take the last three times a human overrode or tightened an agent's pull request, and write down what the human knew that the line did not. Each answer is a candidate row.

Two defaults matter more than the rows. A missing or stale fact fails closed: the change takes the strictest path, not the most convenient one. And a fact that decides who approves must be read from the base branch or the catalog, never from a file the pull request itself can edit; Lesson 6 covers why.

The second half of the rule is the confidence gate. Linear's flow makes the agent show that it understands the problem before it attempts a fix, and when it cannot fix the bug it still posts what it found (Linear, observed 2026-10-28). Several branches depend on what the map returns, so a tree is clearer than a sentence.

Three exits lead to a human or a returned ticket, and only one leads to a fix. The cost of the gate is the share of bugs that end in a diagnosis instead of a pull request, and that is the point of it.

Worked case

Illustrative composite. A marketplace's payments team owns invoice-service. Its line receives about 14 bug tickets a week, a modeled figure. Three systems parse its output: the tax export, payouts and the customer invoice. Finance must approve any change under src/rounding/. The line already has risk lanes (Lesson 7), an identity ledger (Lesson 12) and a passing readiness score (Lesson 9).

Three designs are on the table for how the line learns what the repo cannot tell it.

Design A: repo only. The agent gets the code, the tests and the instruction file. This is the shape of Linear's first attempt.

Design B: copy the facts into the instruction file. Someone writes the owner, the tier and the consumers into the file at the repository root. The agent reads it with everything else.

Design C: a context map. Each fact stays at its source, the map names the source, the keeper and the gate, and a missing or stale fact sends the change to the strictest path.

Decide now: which design, and what is the first thing that breaks in the one you reject?

Design A fails the way the opening failed. A one-line rounding tweak looks tiny to an agent that cannot see the consumers, so it lands in the low-risk lane and reaches payouts with the same scrutiny as a typo fix. Design B looks like the fix and rots in the dullest way. The facts now exist twice, in the catalog and in the file, and nobody's job is to notice when they diverge. After a reorg moves the service to another team, the file keeps naming the old one, and approval routes to people who no longer answer for the code. Worse, the file sits in the repository the agent can edit.

Design C is the one you build. The cost is front-loaded: someone has to open the catalog and find every service with no owner or no tier, and that first sweep is where the surprises are. Here is the entry for this service.

Now run two tickets through it. The first reports a cent off in tax-inclusive totals. The ticket states its acceptance criteria, the map is fresh, the diagnosis reproduces the bug in src/rounding/, so the line opens a PR. Tier 1 plus the finance path rule means the owner team and finance both approve, and the person who filed the ticket is excluded from either. The second reports a typo in an email template. The same map is read, but the matching path carries no extra sign-off, so the change takes the ordinary tier-1 approval and nothing more.

The rejected designs cost the same thing in different currencies. Design A costs a rounding bug in payouts. Design B costs a week of misrouted approvals before anyone sees the old team name. Design C costs one sweep of the catalog and a recurring job for the keepers.

Faded case

Skip to the open case if this is familiar. Same service, same map, one gap. The row for "Downstream consumers" says its keeper is each consumer team, and its stale-after cell is blank. Eight weeks ago a new reporting job began reading the invoice output. The reporting team never touched the catalog entry, so the map still lists three consumers. A bug fix to the invoice format arrives today. Write the freshness rule for this row, and say what the task gate should do with a change whose map row has aged past it.

Open case

You run a line for refund-service, and it has a lane for small bug fixes. Today a reviewer carries three facts in their head that the line cannot see. The service is customer-facing and its owning team changed last month. Refunds above a certain amount need finance approval. And a new ticket, "Fix refund bug", has no acceptance criteria, only a link to a chat thread. For each fact, say where it should live, who keeps it, which gate reads it and what that gate does when the fact is missing. The quiz grades your placement.

Where this breaks

Nobody has outcome data for a context layer. The evidence here is mechanism: Cloudflare, Linear and Atlassian describe what they built and why, and Cloudflare's own report ties its rise in merge requests to adoption without a control group (Cloudflare, first-party, observed 2026-10-28). Backstage documents an ownership kind for skills, rules and MCP servers, but the example is an alpha API version and no adopter is named (Backstage docs, observed 2026-10-28). Vendors also sell "context lakes" with token-saving claims; no source this course could verify backs those figures, so none are printed here.

Success stories are narrow. Atlassian's vulnerability-fix pipeline reports that almost all of its agent pull requests merged on the first run, but that is one team, in a vendor blog, on one repeatable job, with the denominator undefined (Atlassian, self-reported, observed 2026-10-28). It shows what a well-specified job with clear done conditions can do, not what a map does for messy bugs.

Block's Builderbot picks up tickets from Linear or Jira on top of a company-wide code and service context layer, yet its post names no approval or merge gate, so it cannot tell you how a map routes a human (Block, self-reported, observed 2026-10-28).

Last, a wrong fact routes confidently. A stale tier sends the line down the cheaper path with a straight face, which is why the freshness rule is half the deliverable. And a confidence gate that asks the model how sure it is only measures the model's opinion of itself; the diagnosis must carry a reproduction a script can check.

Key Takeaways

• Treat any gate decision you cannot compute from the diff as a fact that needs a home.
• A fact the line cannot read is a fact the line will guess.
• Record keeper, stale-after rule and fail-closed default for every context fact, not only its location.
• Read approval-deciding facts from the base branch or catalog, never from the pull request.
• Require a reproduced diagnosis before any fix, and post it even when you cannot fix.
• Return thin tickets without an attempt, because a stated acceptance criterion is a context fact too.

What You Have Now

factory/context-map.md - each context fact the line needs, where it lives, who keeps it fresh and which gate reads it. It sits beside factory/registry.md from Lesson 11 and factory/identity-ledger.md from Lesson 12: the registry says which skills and agents exist, the ledger says who stands behind each one, and this map says what the line must know about the service it is changing. The risk lanes from Lesson 7 and the review gate from Lesson 4 now have a source for their tier and owner inputs. It serves the Wrap stage of the course loop, and the scoreboard in Lesson 14 is what will tell you whether it helped.

Further Reading

• Linear, "Linear Agent bug fix": the first attempt on all bugs, the narrowing to recurring shapes, and the confidence gate that leaves a diagnosis.
• Linear, "How we use Linear Agent at Linear": the monitor, triage and review flow around the bug fixer.
• Cloudflare, "The Cloudflare internal AI engineering stack": catalog-fed context files that the owning team reviews, and the early failure that motivated them.
• Atlassian, "How we cut PR cycle time with AI code reviews": acceptance criteria pulled from the linked work item into review.
• Atlassian, "Vulnerability fixes with agentic pipelines": a recorded outcome for every ticket and a stop-with-report exit.
• Backstage documentation, AI in the catalog: the open catalog model for skills, rules and MCP servers with owner and lifecycle.

Exercises

1. Mine your overrides. List the last three times a human tightened or rejected an agent's pull request. For each, write the one fact the human knew that the line could not read.
2. Build the map for one service. Write six rows with all five columns filled: fact, where it lives, keeper, stale-after, gate. Mark every row whose home today is a person's memory.
3. Break your own map. Pick the row you trust least and age it past its stale-after date. Trace what each gate does, and change the fail-closed cell until the strictest path is what happens.

Check your understanding