Story decisions evaporate faster than code decisions. The reasoning behind a character's age, a meeting scene's tone, a timeline ordering, a rejected plot thread — it lives in brainstorm sessions that get compacted, in conversations that end, in the author's head between writing sessions. A month later, the question resurfaces: "why did we make the character 8 instead of 10?" and the reasoning is gone. Worse, a writer agent drafts a scene that contradicts a decision nobody recorded.

Record decisions while the reasoning is fresh — in the moment the choice is made, not retroactively. A decision captured from memory after a long brainstorm flattens the nuance: alternatives blur together, constraints lose specificity, reasoning becomes post-hoc justification.

Every decision entry answers three questions: what was decided, why it was chosen, and what else was considered.

Decisions are written inline with the artifacts they relate to in . Not in a separate decisions file. Not in a master log.

A character age decision lives in the relevant character file in , annotated where the age is stated. A timeline ordering decision lives in , annotated at the event sequence. A world mechanics decision lives in , annotated at the relevant system description.

This keeps decisions co-located with the facts they govern. When the writer loads a character file, they see not just the current state but why it's that way. When the continuity-checker flags a timeline issue, the reasoning for the ordering is right there.

Character is 8 years old at story start.
<!-- decision: Age set to 8. Considered 6 (too young for agency in early arcs)
     and 10 (too old for the vulnerability dynamic with the mentor). 8 balances
     competence with dependence. Session: p142, 2025-03-15 -->

Use HTML comments for decision annotations — they're invisible in rendered markdown but preserved in source. Include a session reference so the full discussion can be recovered via if needed.

Record a decision when someone could reasonably make a different choice and the reasoning isn't obvious from the story itself. The test: would a writer agent need this context to draft a scene correctly?

Especially important when:

Skip decisions that follow directly from established canon or project conventions. If the story has already established that a character can't battle yet, a scene brief that avoids combat isn't a decision worth recording — it's a constraint.

The story-orchestrator and knowledge-orchestrator record decisions in real time as brainstorming narrows options and direction crystallizes. This is the high-quality path — decisions captured in the moment retain their full context.

After a brainstorm session where options were explored and the author chose a direction: immediately dispatch the session-miner to extract decisions and write them inline to . Don't wait — the session context is richest right after the conversation.

When decisions weren't captured in the moment (they often aren't), the session-miner can extract them from past session transcripts using . This recovers what would otherwise be lost, but the quality is lower — compacted sessions may have lost nuance, and the miner is reconstructing reasoning rather than recording it.

Use retroactive mining when:

The session-miner reads transcripts and writes decision annotations inline to the relevant entries, tagged with the source session for traceability.