Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/xxyoudeadpunkxx/signal-rail/llms.txt

Use this file to discover all available pages before exploring further.

Not every strong idea is a decision. Not every convincing line is a decision. 04_decision_log.txt is not a brainstorming file, an elegant backlog, or a record of what seems likely to be true. It collects only the choices that have already won against a real alternative and that the project is already treating as real. If you cannot write what it won against, you probably are not in 04 yet.

​
What it is

04_decision_log.txt keeps the record of decisions already taken. It collects choices the project is already treating as real — lines that have beaten a real alternative, that are already in effect, and for which you can state what they touch, why they won, and what risk opens if they are wrong. It is not for promising hypotheses. It is not for preferences. It is not for lines the project might adopt. It is for what the project has already chosen.

​
The test: is it really a decision?

Before recording an entry in 04_decision_log.txt, apply all three tests:
  1. Has it already won against a real alternative? A decision without a won against is usually not a decision — it is a preference or an intention. If you cannot name what it beat, do not write it here.
  2. Is the project already treating it as true? The project’s current work, live state, or structure should already reflect this choice. If it is only a future intention, it belongs in 05_latent_ideas.txt.
  3. Can you state what it touches, why it won, and what risk opens if it’s wrong? A decision is only strong if you can read its consequences. If one of these cannot be closed without invention, the entry is probably not ready yet.

​
D-xx entry structure

Each decision entry uses the following fields. If a field cannot be closed without invention, the entry is not ready. 
- id: D-xx
- date:
- state:
- decision:
- won against:
- touches:
- links to:
- external reference:
- impact:
- why:
- risk if wrong:
- reopening trigger:
FieldPurpose
idStable identifier. Never reused, even if a decision is removed or archived.
dateWhen the decision was taken or formally recorded.
stateHow closed or reopened the decision currently is.
decisionThe live sentence of the choice — not the long story.
won againstThe real alternative it beat. The absence of this field is a warning sign.
touchesWhich parts of the project this decision moves or constrains.
links toSources or nodes that help explain it. Cross-file IDs stay as references here; they do not become new local IDs.
external referenceUseful files or references outside the canonical set. Provide context but carry no canonical authority by default.
impactWhat truly changes because of this decision.
whyWhy it won — not just what it is.
risk if wrongThe cost or distortion if the decision was premature.
reopening triggerWhat would have to happen to reopen it seriously.

​
Possible states

StateMeaning
freezeVery difficult to reopen — the closest a decision gets to a constant
strong but openIt has won, but can still be refined
in reworkIt exists, but its shape is not yet closed
reopenedIt used to be live, but is now under revision

​
Entries zone

New decision entries must be inserted only inside the --- ENTRIES START --- and --- ENTRIES END --- marker zone. Writing outside this zone breaks the entries contract.[TEMPLATE ONLY] in the entries zone is scaffold only. It does not count as a live decision entry. Never treat the template block as an existing decision.
Add new blocks while keeping numbering stable. Never reuse an ID even if one decision is removed or archived.

​
What does NOT go here

  • Preferences — a preference is not enough to make a decision; it does not belong here
  • Promising hypotheses → 05_latent_ideas.txt — they matter but have not won yet
  • Strong ideas that have not yet won → 05_latent_ideas.txt — not decisions yet
  • Lines not yet truly in the work — a decision should already be influencing the project
  • Premature anticipation — using 04 to showcase future directions is an error

​
Key rule

If you cannot write won against, you are usually not in 04 yet.
This is the single most important routing test for this file. The won against field forces the question: what real alternative did this beat? If no real alternative exists, there was no choice — only a preference, a hypothesis, or an intention.

​
Typical errors

  • Using 04 as an elegant backlog — recording strong-looking ideas that have not actually won
  • Recording something as a decision when it is only convincing latent material — that belongs in 05_latent_ideas.txt
  • Skipping won against — this field is what makes a decision traceable; losing it loses the true perimeter of the choice
  • Treating an AI suggestion or strong preference as if it were already a decision — AI recommendations are not decisions; neither are preferences, even deeply held ones
  • Using 04 to anticipate a line that has not really entered the work yet — recording premature intentions corrupts the log

Build docs developers (and LLMs) love

Get started for freeTalk to us