Engineering decision records

When you work across repositories, decisions get scattered: why this architecture, why that dependency, what the migration plan was. They end up in Slack threads, PR comments and people's memory. In Intabula, each repository gets a collection of decision records, and the agent can read the actual code and history while writing them.

The setup

Create a collection per repository (decisions/backend, decisions/ios) and attach each repo as a read-only linked folder. On that path the agent gets git_log, git_show and git_diff, plus file reading and search. The folder boundary is checked against resolved real paths, so a symlink can't lead the agent outside it. Files matching the sensitive-file blocklist, such as .env, are refused or removed from git output. All of these tools are read-only.

Decision records from the actual commits

Ask "Write up why we switched the queue implementation, and check the actual diff" and the agent reads the commit with git_show before writing the record. It can put the commit hash and the changed file paths in the record, so a later reader can open the same diff.

Fields become columns as they recur

You don't design a decision-record template upfront. Write notes as work happens and add frontmatter like status, ticket and decided_on where it fits. Each field already shows as a column in the collection's table, with a type inferred from its values, and you can sort by it.

Once a field appears in at least 40% of the records, a banner above the table names it, its inferred type and how many records hold it, and asks whether to make it an official field. Pin field writes the type to .intabula/schema.json in the vault and turns on validation: values that don't match the type are listed under Needs attention. Hide dismisses the suggestion. A pinned status select can then group a saved kanban board of open decisions.

Why not just keep notes in the repo

Markdown kept next to the code works until you need to see decisions across repositories, filter them by status, or search them from your phone. Intabula gives each repo's collection its own context and schema and keeps them all in one vault, as plain files you can grep and move like the rest of your notes.

More in the docs: Linked folders, Data model