shadowgraph_record_decision
Record a decision with its chosen option, assumptions, evidence, and rejected alternatives, including rules for when to reconsider. Preserves the reasoning behind choices for later review.
Instructions
Record one decision: chosen option, assumptions, evidence, and rejected alternatives with reopenWhen rules. Use shadowgraph_record_attempt for something tried, shadowgraph_record_fact for an observation, shadowgraph_remember for a note. Appends a decision and a journal entry; without idempotencyKey each call adds another and commits a revision.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| goal | No | What the decision is meant to achieve. Searchable content. | |
| actor | No | Who performed this write, such as an agent or person name. Stored for audit; never used to grant trust. | |
| title | Yes | Short name of the decision. Required, non-empty, and searchable content. | |
| chosen | Yes | The option actually chosen. Required, non-empty, and searchable content. | |
| client | No | Which client software performed this write, such as the host application name. | |
| project | No | Project namespace. Defaults to "default"; an empty string is rejected. | |
| evidence | No | Supporting evidence. Counted as declared evidence in the confidence basis, but never re-checked. | |
| sessionId | No | Caller-owned identifier that groups related writes in the audit trail. | |
| confidence | No | Starting confidence, 0-1. Defaults to 0.5. Later outcomes and evidence move it from this baseline; it is a degree of belief, never a verification status. | |
| assumptions | No | What the decision takes for granted. Record each as a fact too if it should be able to reopen the decision. | |
| sourceClass | No | Claimed origin, never proof: agent_claimed (the default), tool_observed, human_confirmed, or production_verified. It weights confidence only. An unrecognised label downgrades to agent_claimed, kept verbatim in sourceRaw. | |
| alternatives | No | Options considered and rejected. Alternatives belong to the decision and have no separate write API; they are what shadowgraph_review reconsiders. | |
| idempotencyKey | No | Retry key scoped by project and operation: reuse it so a retry returns the first result instead of writing a duplicate. Without it every call creates a new entity. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Stable entity identifier. | |
| goal | No | What the decision was trying to achieve. | |
| kind | Yes | Entity kind: decision, attempt, memory, fact, relation, review, or alternative. | |
| actor | No | Who performed the write. | |
| title | No | Short name of the decision. | |
| chosen | No | The option that was chosen. | |
| client | No | Which client performed the write. | |
| status | No | Lifecycle state. Legacy records may carry a value this build does not recognise; shadowgraph_validate reports those. | |
| outcome | No | The recorded outcome, or null until one is recorded. | |
| project | No | Project namespace; records imported from a schema that predates projects may carry null. | |
| evidence | No | Normalised evidence entries: source, type, sourceClass, confidence, observedAt, detail. | |
| createdAt | No | ISO 8601 creation time. | |
| migration | No | Present only on migrated records; records the legacy value a field was mapped from. | |
| sessionId | No | Session identifier recorded with the write. | |
| sourceRaw | No | The original origin label when it differed from sourceClass. Audit only; never evidence. | |
| updatedAt | No | ISO 8601 time of the last change. | |
| confidence | No | Auditable confidence: initial, current (0-1), policy, a history entry per move, and a basis summarising the contributions it was folded from. Legacy records may lack basis. | |
| supersedes | No | Identifiers of decisions this one replaced. | |
| assumptions | No | Assumptions the decision rests on. Searchable content. | |
| reviewAfter | No | ISO 8601 instant after which shadowgraph_maintain marks this decision stale. | |
| sourceClass | No | Claimed origin class recorded with the write. A claim, never proof. | |
| alternatives | No | Rejected alternatives, each with id, label, reasonRejected, status, and the reopenWhen rules that make it reconsiderable. | |
| supersededBy | No | Identifier of the decision that replaced this one. | |
| schemaVersion | No | Storage schema version this entity was written under. A value above the build’s own version is preserved rather than downgraded. | |
| failedAttempts | No | Attempt identifiers or notes attached to this decision. |