For over 50 years, software engineering has been asking the same question:
How do you make thousands of engineering decisions feel like they came from the same mind?
We’ve thrown everything at it:
- Documentation
- Coding standards
- Architecture diagrams
- ADRs
- Confluence
- Onboarding sessions
- Code reviews
- Pair programming
Every one of them exists, at least partly, for the same reason:
To preserve engineering knowledge.
And yet, every engineer joining an established codebase still asks the same questions:
- “Why is it built this way?”
- “Where should this go?”
- “Is this pattern intentional or just legacy?”
We blamed documentation.
I don’t think documentation was ever the real problem.
We Built a Library for a Decision Problem
For decades, we’ve treated engineering knowledge like a library.
Someone discovers something important.
They write it down.
The next engineer is expected to know where to find it, recognize that it’s relevant, stop what they’re doing, read it, and correctly apply it.
It sounds absurd when you say it out loud.
Yet that’s exactly how most organizations operate.
Knowledge is passive.
It waits to be discovered.
But software engineering doesn’t happen while reading documentation.
It happens while making decisions.
Should this live here?
Should this service own that responsibility?
Should I introduce another abstraction?
Can I bypass this layer?
Those decisions happen in seconds.
The documentation explaining why often lives somewhere else.
Or nowhere at all.
What Wayfinder Actually Changes
I recently came across Matt Pocock’s Wayfinder skill.
At first glance, it looks like another planning workflow for coding agents.
You give it a large piece of work—something too big for a single agent session—and it creates a shared map on the repository’s issue tracker.
But the map is not made of implementation tasks.
It is made of decision tickets.
Each ticket exists to resolve a question:
- What should own this responsibility?
- Which boundary should remain stable?
- What trade-off are we actually accepting?
- What needs to be true before implementation begins?
The map records what has been decided, what remains uncertain, and which questions are now ready to be explored.
A new session doesn’t need to reconstruct the entire journey from scratch.
It reads the map at low resolution, finds the current frontier, and zooms into the decision that matters next.
That sounds like a better project-management system.
I don’t think that’s the important part.
Knowledge Stops Being an Archive
The important shift is that engineering knowledge no longer sits beside the work.
It begins to shape the path through the work.
A traditional document explains the architecture and hopes somebody remembers it.
Wayfinder turns architectural uncertainty into something the agent must encounter before moving forward.
The knowledge is still written down.
But it is no longer merely stored.
It is positioned directly in the path of execution.
Knowledge stops being an archive and becomes a route.
None of the individual ingredients are new.
We’ve had issue trackers.
We’ve had ADRs.
We’ve had dependency graphs and architecture documents.
What feels new is the relationship between them and the person—or agent—doing the work.
The system does not merely preserve what was decided.
It uses those decisions to determine what can happen next.
Senior Engineers Are Compressed Judgment
Think about what senior engineers actually contribute.
It’s easy to call it “experience.”
But experience is really compressed judgment.
It’s knowing that an abstraction exists because removing it caused production incidents three years ago.
It’s remembering why authentication cannot bypass a certain boundary.
It’s recognizing that two services look similar but have intentionally different responsibilities.
Most of this knowledge never appears in code.
It rarely appears in documentation.
It usually exists inside someone’s head.
And organizations quietly become dependent on those people.
When they leave, the code remains.
The judgment that shaped it disappears.
We’ve Always Tried to Transfer Judgment
For years, we’ve tried to transfer that judgment through process:
- Better documentation
- More reviews
- More onboarding
- More architecture meetings
- More approval gates
Those things help.
But they are fundamentally reactive.
Someone makes a decision.
Someone else explains why it was wrong.
The explanation may become a review comment.
Perhaps it becomes an ADR.
Perhaps it disappears into Slack.
Then the cycle repeats six months later.
Wayfinder suggests a different model.
What if engineering judgment didn’t always need to be transferred from one person to another?
What if it could simply be present when the next decision was made?
Not as a giant document.
Not as a list of commandments.
As navigable context attached to the work itself.
Agents Follow Context, Not Suggestions
I’ve written before that coding agents follow context, not suggestions.
A style guide sitting in a Markdown file is easy to ignore.
A lint error appearing during implementation is not.
Wayfinder applies a similar principle at a much larger scale.
An architectural decision sitting in Confluence is optional reading.
A decision ticket blocking the next part of the map is part of the operating environment.
That distinction matters.
The problem was never that we failed to write enough knowledge down.
The problem was that the knowledge remained disconnected from the moment it was needed.
Why AI Makes This More Important
This is also why discussions about AI replacing software engineers often miss the point.
Writing code was never the scarce resource.
Good judgment was.
Implementation is becoming cheaper every month.
Judgment isn’t.
If anything, it is becoming more valuable because somebody still has to decide:
- Which boundaries matter
- Which trade-offs are acceptable
- Which abstractions should remain stable
- Which risks are worth taking
- What “good” looks like in this particular system
Somebody still has to encode the principles that agents execute against.
The companies with the best AI outcomes won’t necessarily be the ones writing the cleverest prompts.
They’ll be the ones that have spent years developing good engineering judgment—and know how to capture it.
Every architectural principle.
Every hard-earned trade-off.
Every “we learned this the hard way.”
Every decision that previously disappeared when a staff engineer left the company.
Those decisions stop being tribal knowledge.
They become part of the system itself.
The Accidentally Important Part
Wayfinder does not magically solve institutional memory.
It cannot capture every unspoken assumption inside a senior engineer’s head.
It does not eliminate documentation, architecture reviews, or human judgment.
But I think it exposes the shape of the solution.
For decades, we preserved engineering knowledge as something people could read.
Now we can preserve it as something agents and engineers must navigate.
That is a much bigger shift than it first appears.
Maybe that’s what excited me so much about Wayfinder.
Not because it’s another AI feature.
But because it hints at a future where software architecture isn’t merely a collection of documents.
It is executable knowledge.
And if that’s true, Matt Pocock didn’t just create a better way to plan work with coding agents.
I think he accidentally pointed at the next evolution of software engineering.
Top comments (0)