Record what you decide not to do now
Use this when you or the person you work for decide not to do something now: an optimization left out of a change, a shortcut kept in something already built, an idea worth building later, or decided work that waits for time. A "later" that lives only in a conversation, a code review or a comment is gone when the session ends. A record in the organization is found by the next person or agent who needs it.
The rule
Write the record in the same step as the decision, before you move on. Name the event that should reopen it. Link it from wherever the decision was made.
Pick the home by what was decided
| What was decided | Where it goes | What it carries |
|---|---|---|
| A compromise accepted in something already built: an optimization left out, a shortcut kept, a known limit | The organization's type for accepted compromises, often called architectural debt | What it affects, why it was accepted now, the event that makes it worth fixing, how it would be fixed |
| A thought-through idea deliberately not built now | The organization's type for parked ideas | Who it is for, its rough shape and cost, why it waits, the event that reopens it |
| Work that is decided and only waits for time | An item on the tracker that owns that work | Who does it, the next step, the event or date it waits for |
Find the type first
Before you create a type, or ask the person whether one exists, call documents.searchTypes({ organizationId, query }) with the plain word for the kind: debt, idea, tracker. Read the description of the top rows; it says what one document of that type holds and when to use it. When the organization keeps no such type, tell the person and propose one: a short name in their words, one sentence on what a document of it holds, and the fields in the table above, none of them required. Set up an organization and Document types say how to create one.
Name the event that reopens it
Every record names one concrete event: a load or size threshold, a release of something it depends on, a customer asking for it, a date. "Later", "when convenient" and "after the launch" are not events. The event lets the next agent decide whether the record is due without asking the person again.
Link it from where the decision was made
A code review, design, plan or change description that says "later", "follow-up" or "not now" links the record. Whoever reads that sentence opens the record instead of guessing what was meant.
Example
A review of a change finds that a page reads the same settings twice on every load. Fixing it means restructuring a module, which is not worth it at today's traffic. The agent searches the organization's types for "debt", finds the type for accepted compromises, reads its description and creates one record: the page it affects, why it was accepted, "revisit when the page serves a thousand loads a minute", and how it would be fixed. It links the record from the review and tells the person in one line what it recorded.
Check that it worked
Ask the organization "what did we postpone, and why?". The answer should come from listing those types, not from searching old conversations.