Software Should Teach While It Works

From the WALDHORN.AI Build Archive
Build date: May 25, 2026

A contract-review system can tell someone that a clause is dangerous, assign it a severity, and describe what could go wrong. That may be enough to make the person cautious.

It does not necessarily make them understand the contract any better.

That distinction has been bothering me.

If WALDHORN.AI tells a musician that something deserves attention, the product should not require them to leave, search the term somewhere else, read three articles, and come back before the warning becomes meaningful.

So this morning I added a Clause Library inside the workspace.

The first version contains 55 music-contract clauses.

The more important part is what each one tries to teach.

A label without an explanation creates dependence

Legal language creates a strange information imbalance.

A person can understand every word in a sentence and still have no idea what the sentence does to them.

"Cross-collateralization" is an obvious example of a difficult term, but the problem is larger than terminology. Plenty of clauses are written in ordinary English. The consequences become visible only when you understand the structure around them.

Software can make this worse if it reduces everything to a color.

Red.

Yellow.

Green.

Those labels are useful shortcuts. I use them in Review because somebody reading a long agreement needs a way to understand where attention should go first.

But a color without reasoning easily becomes another form of authority.

The machine says red.

Why?

If the answer is essentially "because the machine says so," the interface may be simpler, but the user has learned nothing.

I do not want that relationship.

Fifty-five clauses, written for somebody who did not go to law school

The Clause Library starts with 55 clauses across seven broad areas of a music agreement.

The entries are searchable and browsable, but I did not want them to read like a legal dictionary.

A dictionary tells you what a term means.

That is only the first question.

For each clause, I wanted the product to help answer several others.

What does this mean in plain English?

Why does it matter?

What should make someone cautious?

What can a more balanced version look like?

What might somebody ask for in a negotiation?

What other provisions should be read alongside it?

Those questions produce a very different kind of reference material.

A definition explains a word.

Context explains a decision.

The examples need contrast

One part of the library pairs different versions of clause language.

The point is not to hand somebody magic language to copy into every agreement. Contract provisions do not work independently of the documents around them, and changing one sentence can change another part of the deal.

The examples are there to make differences visible.

A person can read one formulation and then another and begin to notice what moved: an approval became consultation, a limitation disappeared, discretion became broader, a right acquired a condition, or an obligation stopped being mutual.

That kind of comparison teaches something that a risk label cannot.

It gives the user a pattern to recognize the next time the wording changes.

I think that matters because most people working in music do not encounter a clause once.

They encounter variations of the same ideas throughout a career.

The useful product is not only the one that helps with today's agreement.

It should make tomorrow's agreement slightly less unfamiliar.

The explanation belongs near the work

There is an easy way to solve the education problem badly.

Build a help center.

Fill it with articles.

Put a question-mark icon somewhere in the navigation.

Technically, the information exists.

The user still has to stop what they are doing and go hunting for it.

I wanted the Clause Library to feel like part of the workspace rather than documentation for the workspace. It sits alongside the actual contract tools, uses the same language of risk, and lets somebody move between related concepts without starting a new research session somewhere else.

That is a product decision more than a content decision.

When someone encounters an unfamiliar concept while working on a contract, curiosity has a very short half-life.

If the explanation is available now, they may read it.

If understanding requires opening another site, translating legal terminology into a search query, deciding which result to trust, and then reconstructing the original context, a lot of people will simply continue without understanding it.

I would probably do the same.

Software should reduce that distance.

Teaching is different from simplifying

Plain English has its own failure mode.

It can become so plain that it stops being accurate.

A legal clause is often complicated because the underlying relationship is complicated. Replacing the terminology with a friendly sentence does not remove that complexity.

Sometimes it only hides it.

So the goal of the library is not to pretend every clause can be reduced to a slogan.

Plain English should give someone an entrance.

Then the risk guidance, examples, negotiation context, and related clauses can show why the subject is more complicated than the first sentence suggests.

That is a balance I am still working through.

Make the explanation too technical and the library becomes another legal reference manual that the intended user will avoid.

Make it too simple and the product creates false confidence.

I would rather leave a little complexity visible than explain something incorrectly for the sake of elegance.

Risk should come with a reason

The library uses the same basic red, yellow, and green language that appears elsewhere in the product.

But here the color is not supposed to be the conclusion.

It is an entrance into the explanation.

A red flag should answer why someone might want to push back.

A yellow flag should show what deserves attention rather than implying that the provision is automatically bad.

A more favorable formulation should help demonstrate what changed and why the difference matters.

This is important because contracts are not collections of universally good and universally bad sentences.

Context matters.

Economics matter.

Tradeoffs matter.

A provision can be restrictive and still be part of a deal somebody consciously decides is worth taking.

The product should make the tradeoff visible without pretending to make the decision for them.

The purpose of an explanation is not to replace judgment. It is to give the user more judgment of their own.

The product should leave the user different

I have been thinking about an idea from John Dewey while building this.

In My Pedagogic Creed, he describes education as "a process of living and not a preparation for future living."

I like that distinction far outside the classroom.

Learning inside software is often treated as preparation. Read the documentation first. Watch the tutorial. Learn the vocabulary. Then come back and perform the actual task.

That order feels backwards for a product like this.

The contract is already in front of the person.

The question is already real.

The consequence may already matter.

That is exactly when explanation has value.

I do not want somebody to study contract terminology for six weeks before WALDHORN.AI becomes useful. I want using WALDHORN.AI to gradually make the terminology less foreign.

The work and the learning can happen together.

Not everything needs to be generated

There is something else I like about the Clause Library.

When someone searches for a clause and opens an explanation, the system does not need to invent a new answer for that person.

The material already exists.

The meaning, context, risk guidance, examples, and connections between related terms can be deliberately written and reviewed rather than regenerated from scratch every time somebody asks the same basic question.

That makes the experience immediate and consistent.

There are plenty of places in WALDHORN.AI where interpretation matters and a model is useful.

A stable explanation of a known concept is a different problem.

I am trying not to confuse the two.

The library is inside the product, but it is still a library

There is one limitation I can already see.

The information is now much closer to the work, but the user still has to go looking for it.

They encounter something unfamiliar, open the Clause Library, search for the concept, and read the explanation.

That is better than sending them outside the product.

It is not the shortest possible distance between confusion and understanding.

I am not going to solve that today.

For now I want the library itself to be useful, searchable, readable on a phone, and deep enough that someone can follow one concept into the related ones around it.

The more interesting question can wait:

How much of this teaching should eventually appear exactly where the user needs it?

Understanding is part of the product

The Clause Library does not generate a contract.

It does not review one.

It does not perform a transaction.

If I measured the product only by tasks completed, it would be easy to classify this as secondary.

I do not think it is.

Contracts create leverage partly through information asymmetry. One party may have seen the same structure fifty times. The other may be encountering it for the first time while being asked to make a consequential decision.

Software cannot erase that asymmetry completely.

It can refuse to make it worse.

If WALDHORN.AI tells someone that a provision matters, I want the product to make understanding that provision easier at the same moment.

A useful system should not only complete work on behalf of the person using it.

Sometimes it should leave that person more capable than when they opened it.