record_decision
Record an architectural decision with context, alternatives, and tags. Optionally lock it with do_not_revert to ensure future AI sessions respect it or get alerted on conflicting edits.
Instructions
Record one architectural decision. Set do_not_revert=true to lock it across sessions and IDEs. Returns {decision_id, session_id}. To change it later use supersede_decision (preserves the audit trail) or set_decision_flag (toggle do_not_revert / tags).
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | Optional list of tag strings (e.g. ["security", "auth"]). Surfaces in list_decisions / list_tags filters. | |
| force | No | If true, skip the implicit `check_conflict` duplicate/conflict warning step. Use when you've already reviewed a conflict and want to record anyway. | |
| symbol | No | Optional function/class name within file_path to scope the decision to (e.g. "login"). With do_not_revert, the lock then blocks only edits INSIDE that symbol; edits elsewhere in the file warn instead. Requires file_path. | |
| context | No | Free prose: why this won, what it depended on, what evidence backed it. Surfaced verbatim when a locked decision blocks an edit — this is what the next agent reads instead of guessing. | |
| decision | Yes | The decision itself (1 sentence is fine) | |
| file_path | No | Optional file/path the decision pertains to | |
| session_id | No | Optional session id to attach to (auto-generated if omitted) | |
| do_not_revert | No | If true, mark the decision as protected — future sessions will see do_not_revert=true and must NOT propose changes that conflict without surfacing this decision to the user first. Default false. | |
| would_re_examine_if | No | The condition that should trigger reconsidering this (e.g. "if the payload exceeds 1 MB" or "if we add a second write path"). Especially valuable with do_not_revert — it turns a one-way ratchet into a lock with a stated release condition. | |
| alternatives_considered | No | The strongest options you REJECTED, one per entry (e.g. ["polling — simpler but 3s worst-case latency", "webhooks — needs a public endpoint"]). Surfaces the losers so a future session can weigh whether to revisit instead of re-deriving them. |