robotaitai/project-bedrock/decision-recording

Decision Recording

Persists the rationale for architectural and design choices so future agents do not re-litigate settled questions.

When to record a decision

Record when any of these occur:

• A technology, framework, or pattern is chosen over alternatives
• A structural constraint is adopted (e.g., "no ORM", "raw SQL only")
• A previous decision is reversed or superseded
• The user says "remember why we chose X" or "note that we decided not to do Y"

Do NOT record:

• Tactical choices (variable names, minor refactors, formatting)
• Facts that are obvious from reading the code
• Speculative decisions not yet confirmed

Step 1 -- Create the decision file

SLUG="<short-hyphenated-title>"
DATE=$(date +%Y-%m-%d)
FILE="agent-knowledge/Memory/decisions/${DATE}-${SLUG}.md"

Copy from templates/memory/decision.template.md. Preserve YAML frontmatter.

Step 2 -- Fill in the template

Required fields -- keep each one short:

Optional:

• Superseded by: link to the reversal decision if this one is no longer active

Step 3 -- Link from the relevant branch note

In the relevant branch note under Memory/, add or update the Decisions section:

## Decisions
-[2025-01-15-use-raw-sql.md](decisions/2025-01-15-use-raw-sql.md) -- chose raw SQL over ORM

One line per decision. Keep descriptions under 10 words.

Step 4 -- Update decisions/decisions.md

Prepend a line in agent-knowledge/Memory/decisions/decisions.md:

-[2025-01-15-use-raw-sql.md](2025-01-15-use-raw-sql.md) -- chose raw SQL over ORM

Newest first. If the decision reverses an earlier one, add [reverses YYYY-MM-DD-slug].

Step 5 -- Update Memory/MEMORY.md if the root summary changed

Keep the root note short. Only update it if the project-level decision summary changed.

Reversing a decision

1. Add Status: reversed to the original decision file
2. Add Superseded by: [new-decision.md](new-decision.md) to the original
3. Create a new decision file for the replacement
4. Update decisions/decisions.md: mark the old entry as ~~reversed~~
5. Update the branch note's Decisions section to link the new one

Format reference

---
note_type: decision
status: active
date: 2025-01-15
---
 
# Decision: use-raw-sql
 
## What
Use raw parameterized SQL instead of an ORM for all database access.
 
## Why
Need full control over query shape; ORM abstraction adds complexity without benefit
given the team's SQL proficiency.
 
## Alternatives considered
-**Prisma**: rejected -- too much magic, migration model doesn't fit
-**Drizzle**: rejected -- adds a dependency and type layer we don't need yet
 
## Consequences
-All DB access goes through raw SQL + pgtyped-generated types
-No model layer; query files live in packages/server/src/queries/
-New contributors must know SQL