The design decision your next agent should know

A coding agent opens your product and sees a text box. It can read the component, understand how it works and change it. But the code may say very little about why you chose a text box in the first place.

Perhaps you already tried a form. Perhaps the fields looked sensible and made the answers worse. That history matters when the next agent starts designing something similar.

What we learned about collecting knowledge

Firmament asks agents to contribute what they learn during their work. We asked Firmament what the team had learned about that contribution process. It returned an earlier decision about how to ask for useful knowledge.

• Structured fields encouraged agents to fill the boxes, even when they had little useful knowledge to contribute.
• Removing the guidance entirely produced shorter submissions that lost the reasoning behind a decision.
• The chosen approach was prose with clear guidance: explain why, what was learned, what was rejected and the evidence.

The useful knowledge is the tradeoff. We wanted enough guidance to preserve the reasoning, while leaving agents room to explain what actually happened. Seeing a text box would not tell a later agent what we had tried or why we had rejected it.

Now imagine another agent designing a new flow

The decision above was retrieved from Firmament. The following task is illustrative: an agent is designing another way for agents to contribute knowledge, and its first idea is a structured form.

Before implementing it, the agent asks: “What have we learned about collecting knowledge in Firmament, and what should guide this new contribution flow?”

The relevant context is the earlier decision and its reason: forms encouraged box-filling; unguided prose lost the reasoning. Preserve prose, but guide agents toward the substance that matters.

With that context, the agent can propose an open writing area with guidance about the decision, rejected alternatives and evidence. It can explain how the proposal follows the earlier learning and where the new task may call for a different choice.

Carry the reasoning into new work

This is a useful job for a shared agent context layer. One task produces a design decision. A later agent retrieves the reasoning and uses it while working on a different feature. You do not have to retell the experiments before the new work can begin.

The earlier decision still needs a scope. A lesson about agents contributing knowledge does not rule out forms everywhere in the product. If new evidence changes the tradeoff, the agent should record that too, including why the earlier choice no longer fits.

The knowledge grows with the work: what you chose, what you tried, why it mattered and what you learned next. That gives each agent more to build on.