LLI Wiki — My Digital Knowledge Base

Writing a technical analysis before coding: compared options, lightweight ADR and AI assistants

Problem statement, current state, options table, decision and reasons, open points, and what AI helps with or gets wrong.

The urge to start coding straight away is expensive: you find the constraint that kills the solution after three days. So I write a short analysis note before the code: a Markdown file next to the project, which serves first as a thinking draft and then as the record of the decision.

The outline of the note

  1. Problem statement: two or three sentences. What is the need, for whom, which symptom or limit triggered it?
  2. Current state: how it works today, with verified facts only (rereading the code, a read-only query, official documentation). Assumptions are marked as such.
  3. Options compared in a table.
  4. Decision and its reasons.
  5. Open points: what remains to confirm, and by whom.

Comparing options in a table

A table forces the same criteria on every option:

Criterion A: backup exported to a file B: geo-replicated copy C: do nothing
Setup effort Medium Low None
Running cost Storage Secondary database None
Restore time Long Short Unchanged
Main risk Incomplete file Failover poorly tested Limit reached
Reversible? Yes Yes Yes

The options above are a generic example. I always keep "do nothing" as a baseline, and a "reversible?" row: a reversible decision can be taken faster.

A lightweight ADR

An ADR (Architecture Decision Record) is the "decision" part of the note, reduced to the essentials:

## Decision: copy the database through a request queue

- Status: accepted
- Context: manual copies are slow and untracked.
- Decision: requests are processed through a queue, with approval.
- Reasons: traceability, recovery after failure, no direct rights.
- Consequences: one component to maintain; the queue must be monitored.
- Alternatives rejected: manual script (untracked), third-party service (cost).

The key is the "Reasons" section. Six months from now nobody will remember why this was chosen over that: the file says so. If the decision changes, nothing is erased: a new ADR supersedes the old one (status "superseded").

AI assistants: help and traps

What works well:

Where it misleads:

Lessons learned

Mastodon LLIMastodon SocialFosstodon